7 أساسيات Laravel 11: الاستجابات

مقدمة

يجب أن تُرجع جميع المسارات ووحدات التحكم استجابة ليتم إرسالها مرة أخرى إلى متصفح المستخدم. يوفر Laravel عدة طرق مختلفة لإرجاع الاستجابات. أبسط استجابة هي إرجاع سلسلة نصية من مسار أو وحدة تحكم. سيقوم الإطار تلقائيًا بتحويل السلسلة النصية إلى استجابة HTTP كاملة:

Route::get('/', function () {
    return 'Hello World';
});

بالإضافة إلى إرجاع سلاسل نصية من مساراتك ووحدات التحكم، يمكنك أيضًا إرجاع مصفوفات. سيقوم الإطار تلقائيًا بتحويل المصفوفة إلى استجابة JSON:

Route::get('/', function () {
    return [1, 2, 3];
});

كائنات الاستجابة

عادةً، لن تقوم بإرجاع سلاسل نصية بسيطة أو مصفوفات من إجراءات مسارك فقط. بدلاً من ذلك، ستقوم بإرجاع نسخ كاملة من Illuminate\Http\Response أو عرض. إرجاع نسخة استجابة كاملة يتيح لك تخصيص رمز حالة HTTP للرّد والترويسات. ترث نسخة الاستجابة من فئة Symfony\Component\HttpFoundation\Response، التي توفر مجموعة متنوعة من الطرق لبناء استجابات HTTP:

Route::get('/home', function () {
    return response('Hello World', 200)
                  ->header('Content-Type', 'text/plain');
});

نماذج وكائنات Eloquent

يمكنك أيضًا إرجاع نماذج وكائنات Eloquent ORM مباشرة من مساراتك ووحدات التحكم. عندما تفعل ذلك، سيقوم Laravel تلقائيًا بتحويل النماذج والكائنات إلى استجابات JSON مع احترام الخصائص المخفية للنموذج:

use App\Models\User;
 
Route::get('/user/{user}', function (User $user) {
    return $user;
});

إرفاق الترويسات إلى الاستجابات

معظم طرق الاستجابة قابلة للسلسلة، مما يسمح بالبناء السلس لاستجابات الاستجابة. على سبيل المثال، يمكنك استخدام طريقة header لإضافة سلسلة من الترويسات إلى الاستجابة قبل إرسالها إلى المستخدم:

return response($content)
              ->header('Content-Type', $type)
              ->header('X-Header-One', 'Header Value')
              ->header('X-Header-Two', 'Header Value');

أو يمكنك استخدام طريقة withHeaders لتحديد مصفوفة من الترويسات ليتم إضافتها إلى الاستجابة:

return response($content)
              ->withHeaders([
                  'Content-Type' => $type,
                  'X-Header-One' => 'Header Value',
                  'X-Header-Two' => 'Header Value',
              ]);

Middleware التحكم في التخزين المؤقت

يتضمن Laravel middleware cache.headers، الذي يمكن استخدامه بسرعة لتعيين ترويسة Cache-Control لمجموعة من المسارات. يجب تقديم التوجيهات باستخدام "snake case" المكافئ لتوجيه Cache-Control المقابل ويجب فصلها بفاصلة منقوطة. إذا تم تحديد etag في قائمة التوجيهات، سيتم تلقائيًا تعيين تجزئة MD5 لمحتوى الاستجابة كمعرف ETag:

Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
    Route::get('/privacy', function () {
        // ...
    });
    Route::get('/terms', function () {
        // ...
    });
});

إرفاق الكوكيز إلى الاستجابات

يمكنك إرفاق كوكي إلى نسخة Illuminate\Http\Response الصادرة باستخدام طريقة cookie. يجب عليك تمرير الاسم، القيمة، وعدد الدقائق التي يجب اعتبار الكوكي صالحًا خلالها لهذه الطريقة:

return response('Hello World')->cookie(
    'name', 'value', $minutes);

تقبل طريقة cookie أيضًا بضع حجج إضافية تُستخدم بشكل أقل تواترًا. عادةً، تكون لهذه الحجج نفس الغرض والمعنى مثل الحجج التي سيتم إعطاؤها لطريقة setcookie الأصلية لـ PHP:

return response('Hello World')->cookie(
    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly);

إذا كنت ترغب في التأكد من إرسال كوكي مع الاستجابة الصادرة ولكنك لم تحصل بعد على نسخة من تلك الاستجابة، يمكنك استخدام واجهة Cookie "لإدراج" الكوكيز في قائمة الانتظار لإرفاقها بالاستجابة عند إرسالها. تقبل طريقة queue الحجج اللازمة لإنشاء نسخة كوكي. سيتم إرفاق هذه الكوكيز بالاستجابة الصادرة قبل إرسالها إلى المتصفح:

use Illuminate\Support\Facades\Cookie;
 
Cookie::queue('name', 'value', $minutes);

إنشاء نسخ كوكي

إذا كنت ترغب في إنشاء نسخة Symfony\Component\HttpFoundation\Cookie يمكن إرفاقها بنسخة الاستجابة في وقت لاحق، يمكنك استخدام مساعد cookie العالمي. لن يتم إرسال هذه الكوكي مرة أخرى إلى العميل ما لم يتم إرفاقها بنسخة الاستجابة:

$cookie = cookie('name', 'value', $minutes);
 
return response('Hello World')->cookie($cookie);

انتهاء صلاحية الكوكيز مبكرًا

يمكنك إزالة كوكي عن طريق انتهاء صلاحيته عبر طريقة withoutCookie للاستجابة الصادرة:

return response('Hello World')->withoutCookie('name');

إذا لم يكن لديك بعد نسخة من الاستجابة الصادرة، يمكنك استخدام طريقة expire لواجهة Cookie لإنتهاء صلاحية الكوكي:

Cookie::expire('name');

الكوكيز والتشفير

بشكل افتراضي، بفضل middleware Illuminate\Cookie\Middleware\EncryptCookies، يتم تشفير جميع الكوكيز التي تم إنشاؤها بواسطة Laravel وتوقيعها بحيث لا يمكن تعديلها أو قراءتها بواسطة العميل. إذا كنت ترغب في تعطيل التشفير لمجموعة فرعية من الكوكيز التي تم إنشاؤها بواسطة تطبيقك، يمكنك استخدام طريقة encryptCookies في ملف bootstrap/app.php لتطبيقك:

->withMiddleware(function (Middleware $middleware) {
    $middleware->encryptCookies(except: [
        'cookie_name',
    ]);
});

عمليات إعادة التوجيه

استجابات إعادة التوجيه هي نسخ من فئة Illuminate\Http\RedirectResponse، وتحتوي على الترويسات الصحيحة اللازمة لإعادة توجيه المستخدم إلى عنوان URL آخر. هناك عدة طرق لإنشاء نسخة RedirectResponse. أبسط طريقة هي استخدام مساعد redirect العالمي:

Route::get('/dashboard', function () {
    return redirect('home/dashboard');
});

في بعض الأحيان قد ترغب في إعادة توجيه المستخدم إلى الموقع السابق، مثل عند وجود خطأ في النموذج المرسل. يمكنك القيام بذلك باستخدام دالة back المساعدة العالمية. نظرًا لأن هذه الميزة تستخدم الجلسة، تأكد من أن المسار الذي يستدعي دالة back يستخدم مجموعة middleware web:

Route::post('/user/profile', function () {
    // تحقق من صحة الطلب...
    return back()->withInput();
});

إعادة التوجيه إلى المسارات المسماة

عند استدعاء مساعد redirect بدون معلمات، يتم إرجاع نسخة من Illuminate\Routing\Redirector، مما يتيح لك استدعاء أي طريقة على نسخة Redirector. على سبيل المثال، لإنشاء RedirectResponse إلى مسار مسمى، يمكنك استخدام طريقة route:

return redirect()->route('login');

إذا كان لمسارك معلمات، يمكنك تمريرها كمعامل ثاني لطريقة route:

// لمسار مع URI التالي: /profile/{id}
return redirect()->route('profile', ['id' => 1]);

ملء المعلمات عبر نماذج Eloquent

إذا كنت تعيد التوجيه إلى مسار يحتوي على معلمة "ID" يتم ملؤها من نموذج Eloquent، يمكنك تمرير النموذج نفسه. سيتم استخراج المعرف تلقائيًا:

// لمسار مع URI التالي: /profile/{id}
return redirect()->route('profile', [$user]);

إذا كنت ترغب في تخصيص القيمة التي يتم وضعها في معلمة المسار، يمكنك تحديد العمود في تعريف معلمة المسار (/profile/{id:slug}) أو يمكنك تجاوز طريقة getRouteKey على نموذج Eloquent الخاص بك:

/**
 * احصل على قيمة مفتاح المسار للن
 
موذج.
 */
public function getRouteKey(): mixed
{
    return $this->slug;
}

إعادة التوجيه إلى إجراءات وحدات التحكم

يمكنك أيضًا إنشاء عمليات إعادة توجيه إلى إجراءات وحدات التحكم. للقيام بذلك، قم بتمرير وحدة التحكم واسم الإجراء إلى طريقة action:

use App\Http\Controllers\UserController;
 
return redirect()->action([UserController::class, 'index']);

إذا كانت مسار وحدة التحكم الخاصة بك يتطلب معلمات، يمكنك تمريرها كمعامل ثاني لطريقة action:

return redirect()->action(
    [UserController::class, 'profile'], ['id' => 1]
);

إعادة التوجيه إلى نطاقات خارجية

في بعض الأحيان قد تحتاج إلى إعادة التوجيه إلى نطاق خارج تطبيقك. يمكنك القيام بذلك عن طريق استدعاء طريقة away، التي تنشئ RedirectResponse بدون أي تشفير URL إضافي، أو تحقق أو تحقق:

return redirect()->away('https://www.google.com');

إعادة التوجيه مع بيانات الجلسة المومضة

عادةً ما يتم إعادة التوجيه إلى عنوان URL جديد ووميض البيانات إلى الجلسة في نفس الوقت. عادةً، يتم ذلك بعد أداء عملية بنجاح عند وميض رسالة نجاح إلى الجلسة. للراحة، يمكنك إنشاء نسخة RedirectResponse ووميض البيانات إلى الجلسة في سلسلة طريقة سلسة واحدة:

Route::post('/user/profile', function () {
    // ...
    return redirect('dashboard')->with('status', 'Profile updated!');
});

بعد إعادة توجيه المستخدم، يمكنك عرض الرسالة المومضة من الجلسة. على سبيل المثال، باستخدام بناء جملة Blade:

@if (session('status'))
    {{ session('status') }}
@endif

إعادة التوجيه مع المدخلات

يمكنك استخدام طريقة withInput المقدمة من نسخة RedirectResponse لوميض بيانات المدخلات الحالية للطلب إلى الجلسة قبل إعادة توجيه المستخدم إلى موقع جديد. يتم ذلك عادةً إذا واجه المستخدم خطأ في التحقق من الصحة. بمجرد ومض المدخلات إلى الجلسة، يمكنك بسهولة استرجاعها أثناء الطلب التالي لإعادة ملء النموذج:

return back()->withInput();

أنواع الاستجابة الأخرى

يمكن استخدام مساعد response لإنشاء أنواع أخرى من نسخ الاستجابة. عندما يتم استدعاء مساعد response بدون حجج، يتم إرجاع تنفيذ لعقد Illuminate\Contracts\Routing\ResponseFactory. توفر هذه العقدة عدة طرق مفيدة لإنشاء الاستجابات.

استجابات العرض

إذا كنت بحاجة إلى التحكم في حالة الاستجابة والترويسات ولكنك تحتاج أيضًا إلى إرجاع عرض كمحتوى الاستجابة، يجب عليك استخدام طريقة view:

return response()
            ->view('hello', $data, 200)
            ->header('Content-Type', $type);

بالطبع، إذا لم تكن بحاجة إلى تمرير رمز حالة HTTP مخصص أو ترويسات مخصصة، يمكنك استخدام دالة view المساعدة العالمية.

استجابات JSON

ستقوم طريقة json تلقائيًا بتعيين ترويسة Content-Type إلى application/json، بالإضافة إلى تحويل المصفوفة المعطاة إلى JSON باستخدام دالة json_encode لـ PHP:

return response()->json([
    'name' => 'Abigail',
    'state' => 'CA',
]);

إذا كنت ترغب في إنشاء استجابة JSONP، يمكنك استخدام طريقة json مع طريقة withCallback:

return response()
            ->json(['name' => 'Abigail', 'state' => 'CA'])
            ->withCallback($request->input('callback'));

تنزيل الملفات

يمكن استخدام طريقة download لإنشاء استجابة تجبر متصفح المستخدم على تنزيل الملف في المسار المعطى. تقبل طريقة download اسم الملف كمعامل ثاني للطريقة، والذي سيحدد اسم الملف الذي يراه المستخدم عند تنزيل الملف. أخيرًا، يمكنك تمرير مصفوفة من ترويسات HTTP كمعامل ثالث للطريقة:

return response()->download($pathToFile);
return response()->download($pathToFile, $name, $headers);

التنزيل المتدفق

في بعض الأحيان قد ترغب في تحويل استجابة سلسلة نصية لعملية معينة إلى استجابة قابلة للتنزيل دون الحاجة إلى كتابة محتويات العملية إلى القرص. يمكنك استخدام طريقة streamDownload في هذا السيناريو. تقبل هذه الطريقة إغلاق، واسم الملف، ومصفوفة اختيارية من الترويسات كمعاملاتها:

use App\Services\GitHub;
 
return response()->streamDownload(function () {
    echo GitHub::api('repo')
                ->contents()
                ->readme('laravel', 'laravel')['contents'];
}, 'laravel-readme.md');

استجابات الملفات

يمكن استخدام طريقة file لعرض ملف، مثل صورة أو PDF، مباشرة في متصفح المستخدم بدلاً من بدء تنزيل. تقبل هذه الطريقة المسار المطلق للملف كمعاملها الأول ومصفوفة من الترويسات كمعاملها الثاني:

return response()->file($pathToFile);
return response()->file($pathToFile, $headers);

ماكرو الاستجابة

إذا كنت ترغب في تعريف استجابة مخصصة يمكنك إعادة استخدامها في مجموعة متنوعة من مساراتك ووحدات التحكم، يمكنك استخدام طريقة macro على واجهة Response. عادةً، يجب عليك استدعاء هذه الطريقة من طريقة boot لأحد موفري خدمة تطبيقك، مثل موفر خدمة App\Providers\AppServiceProvider:

use Illuminate\Support\Facades\Response;
 
Response::macro('caps', function (string $value) {
    return Response::make(strtoupper($value));
});

المراجع

لمزيد من المعلومات، راجع وثائق Laravel بواسطة فريق Laravel.