سرویس گیرنده HTTP

معرفی
درخواست ها
درخواست های همزمان
ماکروها
آزمایش کردن
مناسبت ها

معرفی

لاراول یک API گویا و حداقلی را در اطراف کلاینت Guzzle HTTP ارائه می‌کند که به شما امکان می‌دهد به سرعت درخواست‌های HTTP خروجی را برای برقراری ارتباط با سایر برنامه‌های کاربردی وب ارسال کنید. بسته بندی لاراول در اطراف Guzzle بر رایج ترین موارد استفاده آن و یک تجربه توسعه دهنده فوق العاده متمرکز شده است.

درخواست ها

برای درخواست، می توانید از روش های head , get , post , put , patch و delete ارائه شده توسط Http نما استفاده کنید. ابتدا، بیایید نحوه ایجاد یک GET درخواست اساسی به URL دیگر را بررسی کنیم:

use Illuminate\Support\Facades\Http;
 
$response = Http::get('http://example.com');

این get متد نمونه ای از را برمی گرداند Illuminate\Http\Client\Response که روش های مختلفی را ارائه می دهد که ممکن است برای بررسی پاسخ استفاده شود:

$response->body() : string;
$response->json($key = null, $default = null) : array|mixed;
$response->object() : object;
$response->collect($key = null) : Illuminate\Support\Collection;
$response->status() : int;
$response->successful() : bool;
$response->redirect(): bool;
$response->failed() : bool;
$response->clientError() : bool;
$response->header($header) : string;
$response->headers() : array;

شی Illuminate\Http\Client\Response همچنین رابط PHP را پیاده سازی می کند ArrayAccess و به شما امکان می دهد به داده های پاسخ JSON مستقیماً روی پاسخ دسترسی داشته باشید:

return Http::get('http://example.com/users/1')['name'];

علاوه بر روش های پاسخ ذکر شده در بالا، روش های زیر ممکن است برای تعیین اینکه آیا پاسخ دارای کد وضعیت معین است یا خیر استفاده شود:

$response->ok() : bool;                  // 200 OK
$response->created() : bool;             // 201 Created
$response->accepted() : bool;            // 202 Accepted
$response->noContent() : bool;           // 204 No Content
$response->movedPermanently() : bool;    // 301 Moved Permanently
$response->found() : bool;               // 302 Found
$response->badRequest() : bool;          // 400 Bad Request
$response->unauthorized() : bool;        // 401 Unauthorized
$response->paymentRequired() : bool;     // 402 Payment Required
$response->forbidden() : bool;           // 403 Forbidden
$response->notFound() : bool;            // 404 Not Found
$response->requestTimeout() : bool;      // 408 Request Timeout
$response->conflict() : bool;            // 409 Conflict
$response->unprocessableEntity() : bool; // 422 Unprocessable Entity
$response->tooManyRequests() : bool;     // 429 Too Many Requests
$response->serverError() : bool;         // 500 Internal Server Error

قالب های URI

سرویس گیرنده HTTP همچنین به شما امکان می دهد URL های درخواستی را با استفاده از مشخصات قالب URI بسازید . برای تعریف پارامترهای URL که می تواند توسط الگوی URI شما گسترش یابد، می توانید از withUrlParameters روش استفاده کنید:

Http::withUrlParameters([
    'endpoint' => 'https://laravel.com',
    'page' => 'docs',
    'version' => '11.x',
    'topic' => 'validation',
])->get('{+endpoint}/{page}/{version}/{topic}');

درخواست های دامپینگ

اگر می‌خواهید نمونه درخواست خروجی را قبل از ارسال حذف کنید و اجرای اسکریپت را خاتمه دهید، می‌توانید این dd روش را به ابتدای تعریف درخواست خود اضافه کنید:

return Http::dd()->get('http://example.com');

درخواست داده

البته، معمولا هنگام درخواست POST ، PUT و PATCH ارسال داده های اضافی همراه با درخواست شما رایج است، بنابراین این روش ها آرایه ای از داده ها را به عنوان آرگومان دوم خود می پذیرند. به طور پیش فرض، داده ها با استفاده از نوع محتوا ارسال می شوند application/json :

use Illuminate\Support\Facades\Http;
 
$response = Http::post('http://example.com/users', [
    'name' => 'Steve',
    'role' => 'Network Administrator',
]);

دریافت پارامترهای درخواست درخواست

هنگام GET درخواست، می توانید یک رشته پرس و جو را مستقیماً به URL اضافه کنید یا آرایه ای از جفت های کلید / مقدار را به عنوان آرگومان دوم به متد ارسال کنید get :

$response = Http::get('http://example.com/users', [
    'name' => 'Taylor',
    'page' => 1,
]);

روش دیگر withQueryParameters ممکن است استفاده شود:

Http::retry(3, 100)->withQueryParameters([
    'name' => 'Taylor',
    'page' => 1,
])->get('http://example.com/users')

ارسال درخواست های کدگذاری شده URL فرم

اگر می‌خواهید داده‌ها را با استفاده از application/x-www-form-urlencoded نوع محتوا ارسال کنید، باید asForm قبل از درخواست خود با روش تماس بگیرید:

$response = Http::asForm()->post('http://example.com/users', [
    'name' => 'Sara',
    'role' => 'Privacy Consultant',
]);

ارسال درخواست خام

withBody اگر می‌خواهید هنگام درخواست، بدنه درخواستی خام ارائه دهید، می‌توانید از این روش استفاده کنید . نوع محتوا ممکن است از طریق آرگومان دوم متد ارائه شود:

$response = Http::withBody(
    base64_encode($photo), 'image/jpeg'
)->post('http://example.com/photo');

درخواست های چند قسمتی

اگر می‌خواهید فایل‌ها را به‌عنوان درخواست‌های چند قسمتی ارسال کنید، باید attach قبل از درخواست خود با روش تماس بگیرید. این روش نام فایل و محتویات آن را می پذیرد. در صورت نیاز، می‌توانید آرگومان سومی ارائه دهید که به عنوان نام فایل فایل در نظر گرفته می‌شود، در حالی که آرگومان چهارم ممکن است برای ارائه هدرهای مرتبط با فایل استفاده شود:

$response = Http::attach(
    'attachment', file_get_contents('photo.jpg'), 'photo.jpg', ['Content-Type' => 'image/jpeg']
)->post('http://example.com/attachments');

به جای ارسال محتوای خام یک فایل، می توانید یک منبع جریانی را ارسال کنید:

$photo = fopen('photo.jpg', 'r');
 
$response = Http::attach(
    'attachment', $photo, 'photo.jpg'
)->post('http://example.com/attachments');

سرصفحه ها

هدرها ممکن است با استفاده از روش به درخواست ها اضافه شوند withHeaders . این withHeaders روش آرایه ای از جفت کلید/مقدار را می پذیرد:

$response = Http::withHeaders([
    'X-First' => 'foo',
    'X-Second' => 'bar'
])->post('http://example.com/users', [
    'name' => 'Taylor',
]);

می توانید از accept روشی برای تعیین نوع محتوایی که برنامه شما در پاسخ به درخواست شما انتظار دارد استفاده کنید:

$response = Http::accept('application/json')->get('http://example.com/users');

برای راحتی، می توانید از این acceptJson روش برای تعیین سریع اینکه برنامه شما application/json در پاسخ به درخواست شما انتظار نوع محتوا را دارد استفاده کنید:

$response = Http::acceptJson()->get('http://example.com/users');

این withHeaders روش هدرهای جدید را در هدرهای موجود درخواست ادغام می کند. در صورت نیاز، می توانید تمام هدرها را با استفاده از replaceHeaders روش زیر جایگزین کنید:

$response = Http::withHeaders([
    'X-Original' => 'foo',
])->replaceHeaders([
    'X-Replacement' => 'bar',
])->post('http://example.com/users', [
    'name' => 'Taylor',
]);

احراز هویت

می‌توانید اعتبارنامه‌های احراز هویت اولیه و خلاصه را با استفاده از روش‌ها withBasicAuth و withDigestAuth به ترتیب مشخص کنید:

// Basic authentication...
$response = Http::withBasicAuth('taylor@laravel.com', 'secret')->post(/* ... */);
 
// Digest authentication...
$response = Http::withDigestAuth('taylor@laravel.com', 'secret')->post(/* ... */);

توکن های حامل

اگر می خواهید به سرعت یک توکن حامل به Authorization هدر درخواست اضافه کنید، می توانید از withToken روش زیر استفاده کنید:

$response = Http::withToken('token')->post(/* ... */);

تایم اوت

این timeout روش ممکن است برای تعیین حداکثر تعداد ثانیه برای انتظار برای پاسخ استفاده شود. به طور پیش فرض، سرویس گیرنده HTTP پس از 30 ثانیه به پایان می رسد:

$response = Http::timeout(3)->get(/* ... */);

اگر از بازه زمانی داده شده بیشتر شود، یک نمونه از Illuminate\Http\Client\ConnectionException پرتاب می شود.

می‌توانید حداکثر تعداد ثانیه‌ای که باید در حین تلاش برای اتصال به سرور با استفاده از connectTimeout روش زیر منتظر بمانید را مشخص کنید:

$response = Http::connectTimeout(3)->get(/* ... */);

دوباره تلاش می کند

اگر می خواهید در صورت بروز خطای سرویس گیرنده یا سرور، سرویس گیرنده HTTP به طور خودکار درخواست را دوباره امتحان کند، می توانید از این retry روش استفاده کنید. این retry روش حداکثر تعداد دفعاتی که درخواست باید انجام شود و تعداد میلی ثانیه هایی که لاراول باید در بین تلاش ها منتظر بماند را می پذیرد:

$response = Http::retry(3, 100)->post(/* ... */);

اگر می‌خواهید به صورت دستی تعداد میلی‌ثانیه‌های خواب بین تلاش‌ها را محاسبه کنید، می‌توانید یک بسته را به عنوان آرگومان دوم به retry روش ارسال کنید:

use Exception;
 
$response = Http::retry(3, function (int $attempt, Exception $exception) {
    return $attempt * 100;
})->post(/* ... */);

برای راحتی، ممکن است یک آرایه به عنوان اولین آرگومان متد نیز ارائه کنید retry . این آرایه برای تعیین چند میلی ثانیه خواب بین تلاش های بعدی استفاده می شود:

$response = Http::retry([100, 200])->post(/* ... */);

در صورت نیاز، می توانید آرگومان سوم را به retry متد ارسال کنید. آرگومان سوم باید قابل فراخوانی باشد که تعیین می کند آیا تلاش های مجدد باید واقعاً انجام شوند یا خیر. برای مثال، ممکن است بخواهید فقط در صورتی درخواست را دوباره امتحان کنید که درخواست اولیه با یک ConnectionException :

use Exception;
use Illuminate\Http\Client\PendingRequest;
 
$response = Http::retry(3, 100, function (Exception $exception, PendingRequest $request) {
    return $exception instanceof ConnectionException;
})->post(/* ... */);

اگر تلاشی برای درخواست ناموفق بود، ممکن است بخواهید قبل از انجام تلاش جدید تغییری در درخواست ایجاد کنید. شما می توانید با تغییر آرگومان درخواست ارائه شده به فراخوانی که به retry متد ارائه کرده اید، به این امر دست یابید. برای مثال، اگر اولین تلاش یک خطای احراز هویت را نشان داد، ممکن است بخواهید دوباره درخواست را با یک نشانه مجوز جدید امتحان کنید:

use Exception;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\RequestException;
 
$response = Http::withToken($this->getToken())->retry(2, 0, function (Exception $exception, PendingRequest $request) {
    if (! $exception instanceof RequestException || $exception->response->status() !== 401) {
        return false;
    }
 
    $request->withToken($this->getNewToken());
 
    return true;
})->post(/* ... */);

اگر همه درخواست ها با شکست مواجه شوند، یک نمونه از Illuminate\Http\Client\RequestException پرتاب می شود. اگر می‌خواهید این رفتار را غیرفعال کنید، ممکن است یک throw آرگومان با مقدار false . در صورت غیرفعال شدن، آخرین پاسخ دریافت شده توسط مشتری پس از تلاش مجدد برگردانده می شود:

$response = Http::retry(3, 100, throw: false)->post(/* ... */);

اگر همه درخواست ها به دلیل مشکل اتصال با شکست مواجه شوند، Illuminate\Http\Client\ConnectionException حتی زمانی که throw آرگومان روی false .

رسیدگی به خطا

400 برخلاف رفتار پیش‌فرض Guzzle، بسته‌بندی کلاینت HTTP لاراول استثنایی را روی خطاهای کلاینت یا سرور ( و 500 پاسخ‌های سطح از سرورها) ایجاد نمی‌کند . می‌توانید تعیین کنید که آیا یکی از این خطاها با استفاده از روش‌های، یا برگردانده successful شده clientError است serverError :

// Determine if the status code is >= 200 and < 300...
$response->successful();
 
// Determine if the status code is >= 400...
$response->failed();
 
// Determine if the response has a 400 level status code...
$response->clientError();
 
// Determine if the response has a 500 level status code...
$response->serverError();
 
// Immediately execute the given callback if there was a client or server error...
$response->onError(callable $callback);

پرتاب استثناها

اگر یک نمونه پاسخ دارید و می خواهید نمونه ای از Illuminate\Http\Client\RequestException اینکه کد وضعیت پاسخ نشان دهنده یک خطای مشتری یا سرور است را ارسال کنید، می توانید از روش های throw یا استفاده کنید throwIf :

use Illuminate\Http\Client\Response;
 
$response = Http::post(/* ... */);
 
// Throw an exception if a client or server error occurred...
$response->throw();
 
// Throw an exception if an error occurred and the given condition is true...
$response->throwIf($condition);
 
// Throw an exception if an error occurred and the given closure resolves to true...
$response->throwIf(fn (Response $response) => true);
 
// Throw an exception if an error occurred and the given condition is false...
$response->throwUnless($condition);
 
// Throw an exception if an error occurred and the given closure resolves to false...
$response->throwUnless(fn (Response $response) => false);
 
// Throw an exception if the response has a specific status code...
$response->throwIfStatus(403);
 
// Throw an exception unless the response has a specific status code...
$response->throwUnlessStatus(200);
 
return $response['user']['id'];

نمونه Illuminate\Http\Client\RequestException دارای یک ویژگی عمومی است $response که به شما امکان می دهد پاسخ برگشتی را بررسی کنید.

اگر خطایی رخ ندهد، این throw روش نمونه پاسخ را برمی‌گرداند و به شما امکان می‌دهد عملیات‌های دیگر را به متد زنجیره‌ای کنید throw :

return Http::post(/* ... */)->throw()->json();

اگر می‌خواهید قبل از پرتاب کردن استثنا، منطق اضافی را انجام دهید، می‌توانید یک بسته را برای متد ارسال کنید throw . پس از فراخوانی بسته شدن، استثنا به طور خودکار پرتاب می شود، بنابراین نیازی به پرتاب مجدد استثنا از داخل بسته نیست:

use Illuminate\Http\Client\Response;
use Illuminate\Http\Client\RequestException;
 
return Http::post(/* ... */)->throw(function (Response $response, RequestException $e) {
    // ...
})->json();

Guzzle Middleware

از آنجایی که کلاینت HTTP لاراول توسط Guzzle پشتیبانی می‌شود، می‌توانید از Guzzle Middleware برای دستکاری درخواست خروجی یا بررسی پاسخ دریافتی استفاده کنید. برای دستکاری درخواست خروجی، یک میان افزار Guzzle را از طریق withRequestMiddleware روش زیر ثبت کنید:

use Illuminate\Support\Facades\Http;
use Psr\Http\Message\RequestInterface;
 
$response = Http::withRequestMiddleware(
    function (RequestInterface $request) {
        return $request->withHeader('X-Example', 'Value');
    }
)->get('http://example.com');

به همین ترتیب، می توانید پاسخ HTTP ورودی را با ثبت یک میان افزار از طریق withResponseMiddleware روش زیر بررسی کنید:

use Illuminate\Support\Facades\Http;
use Psr\Http\Message\ResponseInterface;
 
$response = Http::withResponseMiddleware(
    function (ResponseInterface $response) {
        $header = $response->getHeader('X-Example');
 
        // ...
 
        return $response;
    }
)->get('http://example.com');

میان افزار جهانی

گاهی اوقات، ممکن است بخواهید میان افزاری را ثبت کنید که برای هر درخواست خروجی و پاسخ دریافتی اعمال می شود. برای انجام این کار، می توانید از روش های globalRequestMiddleware و استفاده کنید globalResponseMiddleware . به طور معمول، این روش ها باید در boot متد برنامه شما استفاده شوند AppServiceProvider :

use Illuminate\Support\Facades\Http;
 
Http::globalRequestMiddleware(fn ($request) => $request->withHeader(
    'User-Agent', 'Example Application/1.0'
));
 
Http::globalResponseMiddleware(fn ($response) => $response->withHeader(
    'X-Finished-At', now()->toDateTimeString()
));

گزینه های Guzzle

می‌توانید با استفاده از روش، گزینه‌های درخواست Guzzle اضافی را برای درخواست خروجی مشخص کنید withOptions . این withOptions روش آرایه ای از جفت کلید/مقدار را می پذیرد:

$response = Http::withOptions([
    'debug' => true,
])->get('http://example.com/users');

گزینه های جهانی

برای پیکربندی گزینه های پیش فرض برای هر درخواست خروجی، می توانید از globalOptions روش استفاده کنید. به طور معمول، این روش باید از boot روش برنامه شما فراخوانی شود AppServiceProvider :

use Illuminate\Support\Facades\Http;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Http::globalOptions([
        'allow_redirects' => false,
    ]);
}

درخواست های همزمان

گاهی اوقات، ممکن است بخواهید چندین درخواست HTTP را همزمان انجام دهید. به عبارت دیگر، شما می خواهید به جای صدور متوالی درخواست ها، چندین درخواست به طور همزمان ارسال شوند. این می تواند منجر به بهبود عملکرد قابل توجهی در هنگام تعامل با API های کند HTTP شود.

خوشبختانه، ممکن است با استفاده از این pool روش این کار را انجام دهید. این pool روش بسته شدنی را می‌پذیرد که یک Illuminate\Http\Client\Pool نمونه را دریافت می‌کند و به شما امکان می‌دهد به راحتی درخواست‌ها را برای ارسال به مخزن درخواست اضافه کنید:

use Illuminate\Http\Client\Pool;
use Illuminate\Support\Facades\Http;
 
$responses = Http::pool(fn (Pool $pool) => [
    $pool->get('http://localhost/first'),
    $pool->get('http://localhost/second'),
    $pool->get('http://localhost/third'),
]);
 
return $responses[0]->ok() &&
       $responses[1]->ok() &&
       $responses[2]->ok();

همانطور که می بینید، هر نمونه پاسخ بر اساس ترتیبی که به استخر اضافه شده قابل دسترسی است. در صورت تمایل، می‌توانید درخواست‌ها را با استفاده از as روشی نام‌گذاری کنید که به شما امکان می‌دهد به پاسخ‌های مربوطه با نام دسترسی داشته باشید:

use Illuminate\Http\Client\Pool;
use Illuminate\Support\Facades\Http;
 
$responses = Http::pool(fn (Pool $pool) => [
    $pool->as('first')->get('http://localhost/first'),
    $pool->as('second')->get('http://localhost/second'),
    $pool->as('third')->get('http://localhost/third'),
]);
 
return $responses['first']->ok();

سفارشی سازی درخواست های همزمان

این pool روش را نمی‌توان با سایر روش‌های سرویس گیرنده HTTP مانند متدهای withHeaders یا متد زنجیر کرد middleware . اگر می‌خواهید هدرهای سفارشی یا میان‌افزار را برای درخواست‌های ادغام‌شده اعمال کنید، باید آن گزینه‌ها را روی هر درخواست در استخر پیکربندی کنید:

use Illuminate\Http\Client\Pool;
use Illuminate\Support\Facades\Http;
 
$headers = [
    'X-Example' => 'example',
];
 
$responses = Http::pool(fn (Pool $pool) => [
    $pool->withHeaders($headers)->get('http://laravel.test/test'),
    $pool->withHeaders($headers)->get('http://laravel.test/test'),
    $pool->withHeaders($headers)->get('http://laravel.test/test'),
]);

ماکروها

کلاینت HTTP لاراول به شما اجازه می دهد تا «ماکرو» را تعریف کنید، که می تواند به عنوان مکانیزمی روان و گویا برای پیکربندی مسیرهای درخواست و هدرهای رایج در هنگام تعامل با سرویس ها در سراسر برنامه شما عمل کند. برای شروع، می توانید ماکرو را در boot متد کلاس برنامه خود تعریف کنید App\Providers\AppServiceProvider :

use Illuminate\Support\Facades\Http;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Http::macro('github', function () {
        return Http::withHeaders([
            'X-Example' => 'example',
        ])->baseUrl('https://github.com');
    });
}

هنگامی که ماکرو شما پیکربندی شد، می توانید آن را از هر جایی در برنامه خود فراخوانی کنید تا یک درخواست در انتظار با پیکربندی مشخص شده ایجاد کنید:

$response = Http::github()->get('/');

آزمایش کردن

بسیاری از سرویس‌های لاراول عملکردی را ارائه می‌کنند که به شما کمک می‌کند تست‌ها را آسان و واضح بنویسید، و کلاینت HTTP لاراول نیز از این قاعده مستثنی نیست. روش Http نما fake به شما این امکان را می‌دهد که به مشتری HTTP دستور دهید هنگام درخواست، پاسخ‌های stubbed/dummy را بازگرداند.

جعل پاسخ ها

به عنوان مثال، برای دستور دادن به سرویس گیرنده HTTP برای بازگرداندن 200 پاسخ های کد وضعیت خالی برای هر درخواست، می توانید fake متد را بدون آرگومان فراخوانی کنید:

use Illuminate\Support\Facades\Http;
 
Http::fake();
 
$response = Http::post(/* ... */);

جعل کردن URL های خاص

از طرف دیگر، می توانید یک آرایه را به fake متد ارسال کنید. کلیدهای آرایه باید الگوهای URL را که می‌خواهید جعل کنید و پاسخ‌های مرتبط با آنها را نشان دهند. این * کاراکتر ممکن است به عنوان یک کاراکتر عام استفاده شود. هر درخواستی که به URL هایی که جعلی نشده اند انجام شود در واقع اجرا خواهد شد. می‌توانید از روش Http نما response برای ایجاد پاسخ‌های خرد/جعلی برای این نقاط پایانی استفاده کنید:

Http::fake([
    // Stub a JSON response for GitHub endpoints...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),
 
    // Stub a string response for Google endpoints...
    'google.com/*' => Http::response('Hello World', 200, $headers),
]);

اگر می‌خواهید یک الگوی URL بازگشتی مشخص کنید که همه URL‌های بی‌همتا را حذف کند، می‌توانید از یک * کاراکتر استفاده کنید:

Http::fake([
    // Stub a JSON response for GitHub endpoints...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),
 
    // Stub a string response for all other endpoints...
    '*' => Http::response('Hello World', 200, ['Headers']),
]);

جعل توالی پاسخ

گاهی اوقات ممکن است لازم باشد مشخص کنید که یک URL واحد باید مجموعه ای از پاسخ های جعلی را با یک ترتیب خاص بازگرداند. می توانید این کار را با استفاده از Http::sequence روش ساخت پاسخ ها انجام دهید:

Http::fake([
    // Stub a series of responses for GitHub endpoints...
    'github.com/*' => Http::sequence()
                            ->push('Hello World', 200)
                            ->push(['foo' => 'bar'], 200)
                            ->pushStatus(404),
]);

وقتی تمام پاسخ‌های یک دنباله پاسخ مصرف شد، هر درخواست دیگری باعث می‌شود که دنباله پاسخ استثنایی ایجاد کند. اگر می خواهید یک پاسخ پیش فرض را مشخص کنید که باید در صورت خالی بودن یک دنباله بازگردانده شود، می توانید از whenEmpty روش زیر استفاده کنید:

Http::fake([
    // Stub a series of responses for GitHub endpoints...
    'github.com/*' => Http::sequence()
                            ->push('Hello World', 200)
                            ->push(['foo' => 'bar'], 200)
                            ->whenEmpty(Http::response()),
]);

اگر می‌خواهید دنباله‌ای از پاسخ‌ها را جعل کنید، اما نیازی به تعیین الگوی URL خاصی که باید جعلی باشد، ندارید، می‌توانید از Http::fakeSequence روش زیر استفاده کنید:

Http::fakeSequence()
        ->push('Hello World', 200)
        ->whenEmpty(Http::response());

پاسخ به تماس جعلی

اگر به منطق پیچیده‌تری برای تعیین پاسخ‌هایی که باید برای نقاط پایانی خاص بازگردانید نیاز دارید، ممکن است روش بسته شود fake . این بسته شدن یک نمونه از Illuminate\Http\Client\Request و باید یک نمونه پاسخ را دریافت کند. در بسته شدن خود، ممکن است هر منطقی را که برای تعیین نوع پاسخی که باید برگردانید انجام دهید:

use Illuminate\Http\Client\Request;
 
Http::fake(function (Request $request) {
    return Http::response('Hello World', 200);
});

جلوگیری از درخواست های سرگردان

اگر می‌خواهید اطمینان حاصل کنید که تمام درخواست‌های ارسال شده از طریق سرویس گیرنده HTTP در طول آزمایش فردی یا مجموعه آزمایشی کامل شما جعلی هستند، می‌توانید با روش تماس بگیرید preventStrayRequests . پس از فراخوانی این روش، هر درخواستی که پاسخ جعلی مربوطه ندارد، به جای درخواست HTTP واقعی، یک استثنا ایجاد می کند:

use Illuminate\Support\Facades\Http;
 
Http::preventStrayRequests();
 
Http::fake([
    'github.com/*' => Http::response('ok'),
]);
 
// An "ok" response is returned...
Http::get('https://github.com/laravel/framework');
 
// An exception is thrown...
Http::get('https://laravel.com');

بازرسی درخواست ها

هنگام جعل پاسخ‌ها، ممکن است گاهی بخواهید درخواست‌هایی را که مشتری دریافت می‌کند بررسی کنید تا مطمئن شوید که برنامه شما داده‌ها یا هدرهای صحیح را ارسال می‌کند. می توانید این کار را با فراخوانی Http::assertSent متد بعد از فراخوانی انجام دهید Http::fake .

این assertSent روش بسته شدنی را می‌پذیرد که یک Illuminate\Http\Client\Request نمونه دریافت می‌کند و باید یک مقدار بولی برگرداند که نشان می‌دهد آیا درخواست مطابق با انتظارات شما است یا خیر. برای گذراندن آزمون، حداقل باید یک درخواست مطابق با انتظارات داده شده صادر شده باشد:

use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
 
Http::fake();
 
Http::withHeaders([
    'X-First' => 'foo',
])->post('http://example.com/users', [
    'name' => 'Taylor',
    'role' => 'Developer',
]);
 
Http::assertSent(function (Request $request) {
    return $request->hasHeader('X-First', 'foo') &&
           $request->url() == 'http://example.com/users' &&
           $request['name'] == 'Taylor' &&
           $request['role'] == 'Developer';
});

در صورت نیاز، می توانید ادعا کنید که درخواست خاصی با استفاده از assertNotSent روش ارسال نشده است:

use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
 
Http::fake();
 
Http::post('http://example.com/users', [
    'name' => 'Taylor',
    'role' => 'Developer',
]);
 
Http::assertNotSent(function (Request $request) {
    return $request->url() === 'http://example.com/posts';
});

می‌توانید از این assertSentCount روش برای تأیید تعداد درخواست‌هایی که در طول آزمایش «ارسال شده‌اند» استفاده کنید:

Http::fake();
 
Http::assertSentCount(5);

یا، می‌توانید از این assertNothingSent روش برای تأیید اینکه هیچ درخواستی در طول آزمایش ارسال نشده است استفاده کنید:

Http::fake();
 
Http::assertNothingSent();

ثبت درخواست ها / پاسخ ها

می توانید از این recorded روش برای جمع آوری تمام درخواست ها و پاسخ های مربوط به آنها استفاده کنید. متد recorded مجموعه ای از آرایه ها را برمی گرداند که حاوی نمونه هایی از Illuminate\Http\Client\Request و Illuminate\Http\Client\Response :

Http::fake([
    'https://laravel.com' => Http::response(status: 500),
    'https://nova.laravel.com/' => Http::response(),
]);
 
Http::get('https://laravel.com');
Http::get('https://nova.laravel.com/');
 
$recorded = Http::recorded();
 
[$request, $response] = $recorded[0];

علاوه بر این، این recorded روش بسته شدنی را می‌پذیرد که نمونه‌ای از آن را دریافت می‌کند Illuminate\Http\Client\Request و Illuminate\Http\Client\Response ممکن است برای فیلتر کردن جفت‌های درخواست/پاسخ بر اساس انتظارات شما استفاده شود:

use Illuminate\Http\Client\Request;
use Illuminate\Http\Client\Response;
 
Http::fake([
    'https://laravel.com' => Http::response(status: 500),
    'https://nova.laravel.com/' => Http::response(),
]);
 
Http::get('https://laravel.com');
Http::get('https://nova.laravel.com/');
 
$recorded = Http::recorded(function (Request $request, Response $response) {
    return $request->url() !== 'https://laravel.com' &&
           $response->successful();
});

مناسبت ها

لاراول سه رویداد را در طول فرآیند ارسال درخواست های HTTP اجرا می کند. رویداد RequestSending قبل از ارسال یک درخواست فعال می شود، در حالی که ResponseReceived رویداد پس از دریافت پاسخ برای یک درخواست معین فعال می شود. ConnectionFailed در صورت عدم دریافت پاسخ برای یک درخواست معین، رویداد فعال می شود .

و رویدادها هر دو حاوی یک ویژگی عمومی هستند که می‌توانید از آن برای بررسی نمونه استفاده RequestSending کنید . به همین ترتیب، رویداد حاوی یک ویژگی و همچنین ویژگی است که ممکن است برای بازرسی نمونه مورد استفاده قرار گیرد. می توانید شنوندگان رویداد را برای این رویدادها در برنامه خود ایجاد کنید: ConnectionFailed $request Illuminate\Http\Client\Request ResponseReceived $request $response Illuminate\Http\Client\Response

use Illuminate\Http\Client\Events\RequestSending;
 
class LogRequest
{
    /**
     * Handle the given event.
     */
    public function handle(RequestSending $event): void
    {
        // $event->request ...
    }
}