فهرست مستندات پروژه
سوالات متداول
چرا بدون هیچ وابستگی Composer؟
توسعه‌دهندگان ایرانی اغلب در محیط‌های شبکه‌ای محدود کار می‌کنند (تحریم، پروکسی شرکتی، دسترسی ناپایدار به Packagist). صفر وابستگی یعنی:
- چیزی برای بررسی امنیتی supply-chain نیست
- نصب بعد از vendor کردن یک بار، آفلاین کار می‌کند
- بدون وابستگی به فریم‌ورک خاص — همین کد روی Laravel، Symfony، Slim یا PHP خالص کار می‌کند
ارسال فقط از چیزی که خود PHP ارائه می‌دهد استفاده می‌کند: ext-curl، ext-json، ext-openssl، ext-soap.
چرا گرم و میلی‌متر به صورت عدد صحیح؟
عملیات ممیز شناور دقت را بی‌صدا از دست می‌دهد (0.1 + 0.2 !== 0.3). وزن و ابعاد مرسوله از API شرکت‌ها عبور می‌کنند، جایی که یک خطای گرد کردن می‌تواند سطح هزینه را تغییر دهد. اعداد صحیح ریاضی را واضح و قابل بازتولید می‌کنند.
چرا در v1 webhook پردازش نمی‌شود؟
هر شرکت شکل webhook متفاوتی دارد. یک انتزاع تمیز به کلاس WebhookParser برای هر شرکت نیاز دارد، و درست کردن آن به نمونه‌های واقعی ترافیک از هر شرکت نیاز دارد. تا آن زمان، الگوی پل مستندشده (دریافت webhook → فراخوانی track()) یک ShipmentInterface نرمال‌شده تولید می‌کند بدون اینکه ارسال نیاز به حدس زدن شکل payload داشته باشد.
می‌توانم شرکت خودم را اضافه کنم؟
بله — CONTRIBUTING.md را دنبال کنید. سه فایل (Config / Provider / ErrorCode) به اضافه یک تست و ثبت در Ersal::create().
چرا SupportsCOD یک marker interface بدون متد است؟
پس‌کرایه ویژگی یک booking است، نه یک فعل مجزا. SupportsCOD می‌گوید “این شرکت BookingRequest::$codAmount را محترم می‌شمارد” بدون اضافه کردن متد. مقدار $codAmount را مستقیم (یا از طریق BookingRequest::withCashOnDelivery()) تنظیم می‌کنید و provider در صورت پشتیبانی آن را serialize می‌کند.
چرا track() کد رهگیری نمی‌گیرد؟
کد رهگیری رو به شرکت و قابل نمایش به انسان است. ShipmentId دسته opaque ای است که کد شما صاحب آن است. این دو حتی وقتی مقدار رشته یکسان داشته باشند جدا هستند — همیشه از ShipmentId در کد داخلی استفاده کنید.
چه نسخه‌های PHP پشتیبانی می‌شوند؟
PHP 8.1، 8.2، 8.3، 8.4. CI روی هر چهار نسخه اجرا می‌شود.
آیا برای استفاده در production امن است؟
خود کتابخانه به صورت end-to-end تست شده و تحت PHPStan level 6 تحلیل استاتیک شده است. با این حال، آدرس endpointها و نام فیلدها در نسخه v1 مبتنی بر قراردادهای رایج مستندسازی عمومی است — قبل از قرار دادن در مسیر پرداخت production با پرتال توسعه‌دهنده شرکت خود تایید کنید. هر Config provider یک بازنویسی baseUrl / wsdlUrl می‌پذیرد برای همین منظور.
چگونه ارسال را در تست mock کنم؟
از طریق سازنده Ersal یک HttpClient mock تزریق کنید. هر provider در نهایت از مسیر HttpClient::postJson / getJson / deleteJson عبور می‌کند — می‌توانید آن‌ها را وادار کنید بدنه‌های ثابت HttpResponse برگردانند.
برای نمونه کامل به tests/Unit/Provider/TipaxProviderTest.php مراجعه کنید.