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

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

معرفی

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

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

composer require guzzlehttp/guzzle

درخواست ها

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

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

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

$response->body() : string;
$response->json() : array|mixed;
$response->status() : int;
$response->ok() : bool;
$response->successful() : bool;
$response->failed() : bool;
$response->serverError() : bool;
$response->clientError() : bool;
$response->header($header) : string;
$response->headers() : array;

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

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

درخواست داده

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

$response = Http::post('http://test.com/users', [
    'name' => 'Steve',
    'role' => 'Network Administrator',
]);

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

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

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

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

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

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

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

withBody اگر می‌خواهید هنگام درخواست، بدنه درخواستی خام ارائه دهید، می‌توانید از روش استفاده کنید :

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

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

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

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

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

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

سرصفحه ها

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

$response = Http::withHeaders([
    'X-First' => 'foo',
    'X-Second' => 'bar'
])->post('http://test.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 روش ممکن است برای تعیین حداکثر تعداد ثانیه برای انتظار برای پاسخ استفاده شود:

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

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

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

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

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

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

رسیدگی به خطا

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

// Determine if the status code was >= 200 and < 300...
$response->successful();
 
// Determine if the status code was >= 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();

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

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

$response = Http::post(...);
 
// Throw an exception if a client or server error occurred...
$response->throw();
 
return $response['user']['id'];

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

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

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

گزینه های Guzzle

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

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

آزمایش کردن

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

جعل پاسخ ها

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

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

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

از طرف دیگر، می توانید یک آرایه را به fake متد ارسال کنید. کلیدهای آرایه باید الگوهای URL را که می‌خواهید جعل کنید و پاسخ‌های مرتبط با آنها را نشان دهند. این * کاراکتر ممکن است به عنوان یک کاراکتر عام استفاده شود. هر درخواستی که به URL هایی که جعلی نشده اند انجام شود در واقع اجرا خواهد شد. می توانید از این 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 و باید یک نمونه پاسخ را برگرداند:

Http::fake(function ($request) {
    return Http::response('Hello World', 200);
});

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

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

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

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

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

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

یا اگر می خواهید ادعا کنید که هیچ درخواستی ارسال نشده است، می توانید از assertNothingSent روش زیر استفاده کنید:

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