کلاینت‌های HTTP

بدون httpClient:، درخواست‌ها از OpenEmail\Http\CurlHttpClient می‌گذرند، که به چیزی جز افزونهٔ curl نیاز ندارد. برای هر کلاینت یک هندل cURL نگه می‌دارد، پس درخواست دوم از اتصالی که درخواست نخست باز کرده دوباره استفاده می‌کند، و صفحهٔ «پیکربندی» گزینه‌هایش را برای پراکسی‌ها، مراجع صدور گواهی و تنظیمات اضافی cURL فهرست می‌کند.

هر چه بایت‌ها را جابه‌جا کند، باقی کارها را خودِ کلاینت انجام می‌دهد: اعتبارنامه، کلیدهای idempotency، تلاش‌های دوباره و بک‌آف آن‌ها، مهلت هر تلاش و استثنای هر شکست. یک کلاینت HTTP فقط یک درخواست می‌فرستد و پاسخ را پس می‌دهد.

OpenEmail\Http\Psr18HttpClient هر کلاینتی را که PSR-18 را پیاده‌سازی کند، مانند Guzzle یا Symfony HttpClient، در بر می‌گیرد، پس درخواست‌ها از کلاینتی می‌گذرند که برنامهٔ شما از پیش پیکربندی کرده، همراه با middleware، لاگ‌گیری و تنظیمات پراکسی آن.

use GuzzleHttp\Client;use OpenEmail\Http\Psr18HttpClient;use OpenEmail\OpenEmail; $client = new OpenEmail(httpClient: new Psr18HttpClient(new Client())); $client->me->ping();

use OpenEmail\Http\Psr18HttpClient;use OpenEmail\OpenEmail;use Symfony\Component\HttpClient\HttpClient;use Symfony\Component\HttpClient\Psr18Client; $http = new Psr18Client(HttpClient::create(['timeout' => 30, 'max_redirects' => 0])); $client = new OpenEmail(httpClient: new Psr18HttpClient($http)); $client->me->ping();

PSR-18 درخواست‌هایش را با factoryهای PSR-17 می‌سازد. آداپتور اگر خودِ کلاینت factory هم باشد، مانند Psr18Client در Symfony، از آن استفاده می‌کند، سپس اگر php-http/discovery نصب باشد از آن، سپس از nyholm/psr7 یا factoryهای خودِ Guzzle، و اگر هیچ‌کدام را پیدا نکند InvalidArgumentException را پرتاب می‌کند و نام آنچه باید نصب شود را می‌آورد. برای اینکه خودتان آن‌ها را انتخاب کنید، requestFactory: و streamFactory: را بدهید. Psr18Client در Symfony به رابط‌های PSR-18 و یک پیاده‌سازی PSR-17 هم نیاز دارد، پس آن را با composer require symfony/http-client psr/http-client nyholm/psr7 نصب کنید.

use GuzzleHttp\Client;use Nyholm\Psr7\Factory\Psr17Factory;use OpenEmail\Http\Psr18HttpClient;use OpenEmail\OpenEmail; $factory = new Psr17Factory(); $client = new OpenEmail(httpClient: new Psr18HttpClient(new Client(), requestFactory: $factory, streamFactory: $factory)); $client->me->ping();

httpClient: هر چیزی را که OpenEmail\Http\HttpClient را پیاده‌سازی کند می‌پذیرد، رابطی با یک متد: send(HttpRequest $request): HttpResponse. برای هر وضعیتی، از جمله 4xx و 5xx، پاسخ را برگردانید، و فقط وقتی هیچ پاسخی نرسیده استثنا پرتاب کنید.

یک کلاینت ساختگی آنچه را که بیرون می‌رفت ثبت می‌کند و با هر چیزی که آزمون لازم دارد پاسخ می‌دهد، پس هیچ چیزی از دستگاه بیرون نمی‌رود و آزمون می‌تواند دقیقاً بررسی کند چه چیزی فرستاده شده است.

use OpenEmail\Http\HttpClient;use OpenEmail\Http\HttpRequest;use OpenEmail\Http\HttpResponse;use OpenEmail\OpenEmail; $fake = new class implements HttpClient {    public array $requests = [];     public function send(HttpRequest $request): HttpResponse    {        $this->requests[] = $request;         return new HttpResponse(            200,            ['content-type' => 'application/json'],            json_encode(['id' => 'msg_test', 'status' => 'sent', 'replayed' => false], JSON_THROW_ON_ERROR),        );    }}; $testClient = new OpenEmail(apiKey: 'oe_test_fake', httpClient: $fake, maxRetries: 0, disableUpdateNotice: true); $sent = $testClient->emails->send([    'from' => '[email protected]',    'to' => '[email protected]',    'subject' => 'Hi',    'text' => 'Hello',]); $request = $fake->requests[0]; echo $sent['status'], ' ', $request->method, ' ', $request->url, ' ', $request->header('Idempotency-Key'), PHP_EOL;var_dump($request);

• —وضعیتی بیرون از 2xx را با پاکت خطای API به‌عنوان بدنه برگردانید، مانند {"error": {"type": "validation_error", "code": "invalid_parameter", "message": "..."}}، تا زیرکلاس متناظر ApiException را بگیرید.
• —از send یک new HttpClientException('timed out', timeout: true) پرتاب کنید تا یک NetworkException بگیرید که isTimeout() آن true است. هر Exception دیگری، مانند RuntimeException، به یک NetworkException تبدیل می‌شود که isTimeout() آن false است.
• —یک LogicException و هر Error، مانند TypeError، باگ‌های خودِ نمونهٔ ساختگی به حساب می‌آیند. بی‌تغییر پرتاب می‌شوند و هرگز دوباره تلاش نمی‌شوند.