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

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

معرفی

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

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

composer require guzzlehttp/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) : array|mixed;
$response->object() : object;
$response->collect($key = null) : Illuminate\Support\Collection;
$response->status() : int;
$response->ok() : bool;
$response->successful() : bool;
$response->redirect(): 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://example.com/users/1')['name'];

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

اگر می‌خواهید نمونه درخواست خروجی را قبل از ارسال حذف کنید و اجرای اسکریپت را خاتمه دهید، می‌توانید این 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,
]);

ارسال درخواست های کدگذاری شده 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'
)->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');

احراز هویت

می‌توانید اعتبارنامه‌های احراز هویت اولیه و خلاصه را با استفاده از روش‌ها 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(...);

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

$response = Http::retry(3, 100, function ($exception) {
    return $exception instanceof ConnectionException;
})->post(...);

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

رسیدگی به خطا

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 :

$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);
 
return $response['user']['id'];

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

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

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

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

return Http::post(...)->throw(function ($response, $e) {
    //
})->json();

گزینه های Guzzle

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

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

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

گاهی اوقات، ممکن است بخواهید چندین درخواست 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();

ماکروها

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

use Illuminate\Support\Facades\Http;
 
/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    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(...);

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

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

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

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

هنگام جعل پاسخ‌ها، ممکن است گاهی بخواهید درخواست‌هایی را که مشتری دریافت می‌کند بررسی کنید تا مطمئن شوید که برنامه شما داده‌ها یا هدرهای صحیح را ارسال می‌کند. می توانید این کار را با فراخوانی 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();

مناسبت ها

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

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

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Http\Client\Events\RequestSending' => [
        'App\Listeners\LogRequestSending',
    ],
    'Illuminate\Http\Client\Events\ResponseReceived' => [
        'App\Listeners\LogResponseReceived',
    ],
    'Illuminate\Http\Client\Events\ConnectionFailed' => [
        'App\Listeners\LogConnectionFailed',
    ],
];