Laravel/routing

التوجيه (Routing)

التوجيه الأساسي

تقبل أغلب مسارات Laravel الأساسيّة مُتغّيرين: رابط URI  و نطاق مغلق Closure مما يُوفّر طريقة بسيطة ومعبّرة جدّا لتعريف المسارات (routes):

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

ملفات المسار الإفتراضيّة

كل مسارات Laravel مُعرّفة في ملفات مساراتك الموجودة في المجلّد routes. يُحمّل إطار العمل كل هذه الملفّات تلقائيًا. يعرّف الملف routes/web.php كل المسارات المُخصّصة لواجهة الويب. مجموعة البرمجيّات الوسيطة web معيّنة على كل المسارات وتوفّر خاصيّات مثل حالة الجلسة (session state) والحماية CSRF. المسارات في routes/api.php بلا حالة (stateless) ومجموعة البرمجيّات الوسيطة api مُعيّنة عليهم.

ستبدأ في أغلب التطبيقات بتعريف المسارات في ملفك routes/web.php. يمكن الوصول للمسارات المُعرّفة في routes/web.php بإدخال رابط URL المسار المُعرّف في مُتصفّحك. على سبيل المثال، تستطيع الوصول للمسار التالي بالتنقّل إلى الرابط http://your-app.test/user على متصفّحك:

Route::get('/user', 'UserController@index');

المسارات المُعرّفة في الملف routes/api.php متداخلة ضمن مجموعة المسارات عبر RouteServiceProvider. تضاف السابقة /api قبل URI تلقائيًّا داخل هذه المجموعة حتى لا تضطر لإضافتها يدويًّا لكل مسار في الملف. تستطيع تعديل السابقة وإعدادات مجموعة المسارات الأخرى بتعديل الصنف RouteServiceProvider.

توابع جهاز التوجيه المُتوفّرة

يسمح لك المُوجّه (router) بتسجيل مسارات تستجيب لأية طريقة HTTP:

Route::get($uri, $callback);
Route::post($uri, $callback);
Route::put($uri, $callback);
Route::patch($uri, $callback);
Route::delete($uri, $callback);
Route::options($uri, $callback);

قد تحتاج أحيانًا لتسجيل مسار يستجيب لأكثر من طريقة HTTP. يمكنك فعل ذلك باستخدام التابع match أو يمكنك حتى تسجيل مسار يستجيب لكل طرق HTTP باسخدام التابع any:

Route::match(['get', 'post'], '/', function () {
   //
});

Route::any('foo', function () {
   //
});

الحماية CSRF

يجب أن تحتوي كل استمارات HTML التي تشير لمسارات POST، أو PUT، أو DELETE المُعرّفة بملف المسارات web على حقل رمز CSRF. وإلا سيُرفض الطلب. يمكنك القراءة أكثر عن الحماية CSRF في توثيق CSRF:

<form method="POST" action="/profile">
    @csrf
    ...
</form>

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

إن كنت بصدد تعريف مسار يعيد التوجيه إلى رابط URI آخر، تستطيع استخدام التابع Route::redirect. يوفّر هذا التابع اختصارًا ملائمًا كي لا تضطر لتعريف مسار أو وحدة تحكّم (controller) كاملة. يقبل التابع واجهة view كأول متغيّر وسيط URI وإسم عرض (view name) كثاني متغيّر. علاوة على ذلك، تستطيع توفير مصفوفة بيانات لتمريرها للعرض (view) كمتغيّر وسيط ثالث اختياري:

Route::redirect('/here', '/there', 301);

مسارات العروض

تستطيع استخدام التابع Route::view إن احتجت فقط لرد عرض. يوفّر هذا التابع طريقاً مختصراً كي لا تضطر لتعريف مسار أو وحدة تحكّم كاملين  مثل التابع redirect. يقبل التابع view رابط URI كمُتغيّره الوسيط الأوّل واسم عرض كمتغيّره الثاني. إضافةً لذلك تستطيع توفير مصفوفة بيانات لتمريرها كمتغيّر ثالث إختياري:

Route::view('/welcome', 'welcome');

Route::view('/welcome', 'welcome', ['name' => 'Taylor']);

معاملات المسار (Route Parameters)

المعاملات المطلوبة (Required Parameters)

ستحتاج أحيانًا لالتقاط أجزاء من رابط URI ضمن مسارك. قد تحتاج مثلا لاقتطاع معرّف المستخدم. تستطيع فعل هذا بتعريف معاملات المسار:

Route::get('user/{id}', function ($id) {
    return 'User '.$id;
});

تستطيع تعريف أي عدد من المعاملات التي يتطلبها مسارك:

Route::get('posts/{post}/comments/{comment}', function ($postId, $commentId) {
   //
});

توضع معاملات المسار دائما بين {} معقّفين ويجب أن تتضمن محارف أبجديّة (alphabetic characters)، لا يجب أن تتضمّن الحرف - . استخدم الشرطة السفليّة (_) بدل استخدام الحرف -. تضاف معاملات المسار لردود نداء (callback) / وحدات تحكم المسار بناءًا على ترتيبهن - أسماء ردود النداء / متغيّرات وحدة التحكّم الوسيطة لا تهم.

المعاملات الاختياريّة

قد تحتاج أحيانًا لتحديد معامل (parameter) مسار لكن مع جعله اختياريًّا. تستطيع فعل هذا بوضع نقطة استفهام ? بعد اسم المعامل. لا تنس إعطاء متغيّر المسار قيمة افتراضيّة (default value):

Route::get('user/{name?}', function ($name = null) {
    return $name;
});

Route::get('user/{name?}', function ($name = 'John') {
    return $name;
});

قيود التعابير النمطيّة (Regular Expression Constraints)

تستطيع تقييد بنية معاملات مسارك باستخدام التابع where في نسخة مسار. يقبل التابع where  اسم المعامل وتعبيرًا نمطيًّا يُعرّف كيفيّة تقييد المعامل:

Route::get('user/{name}', function ($name) {
   //
})->where('name', '[A-Za-z]+');

Route::get('user/{id}', function ($id) {
   //
})->where('id', '[0-9]+');

Route::get('user/{id}/{name}', function ($id, $name) {
   //
})->where(['id' => '[0-9]+', 'name' => '[a-z]+']);

القيود العامّة

إن رغبت في تقييد معامل مسار ما بشكل دائم من طرف تعبير نمطي ما، تستطيع استخدام التابع pattern. يمكنك تعريف هذه الأنماط (patterns) في التابع boot من RouteServiceProvider:

/**
 *
 * عرّف قيود نموذج مسارك، ومرشّحات الأنماط، الخ
 * @return void
 */
public function boot()
{
    Route::pattern('id', '[0-9]+');

    parent::boot();
}

يطبّق النمط (pattern) فور تعريفه تلقائيًّا على كل المسارات التي تستخدم اسم المعامل ذاك:

Route::get('user/{id}', function ($id) {
   // عدداً {id} تنفّذ فقط إن كان 
});

المسارات المُسمّاة (Named Routes)

تسمح المسارات المُسمّاة بتوليد روابط  URLs أو إعادات توجيه لمسارات معيّنة. يمكنك تحديد اسم لمسار ما بربط التابع name بتعريف المسار:

Route::get('user/profile', function () {
    //
})->name('profile');

تستطيع أيضًا تحديد أسماء المسارات لأفعال وحدات التحكّم:

Route::get('user/profile', 'UserProfileController@show')->name('profile');

توليد روابط URLs للمسارات المُسمّاة

بعد تعيينك اسمًا لمسار محدّد، تستطيع استخدام اسم المسار عند توليد روابط URLs أو إعادات توجيه عبر الدالّة العامّة route:

// URLs توليد 
$url = route('profile');

// توليد إعادات توجيه
return redirect()->route('profile');

تستطيع تمرير المعاملات كالمتغيّر الوسيط الثّاني للدالّة route إن عرّف المسار المُسمّى المعاملات. ستضاف المعاملات المُعطاة تلقائيًّا داخل رابط URL في مكانهن الصّحيح:

Route::get('user/{id}/profile', function ($id) {
   //
})->name('profile');

$url = route('profile', ['id' => 1]);

فحص المسار الحالي (Inspecting The Current Route)

إذا رغبت في التأكّد إن وُجّه الطلب الحالي لمسار مُسمّى محدّد، يمكنك استخدام التابع named على نسخة المسار. قد مثلا تتحقّق من اسم المسار الحالي من برمجيّة مسار وسيطة:

/**
 * معالجة طلب وارد
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Closure  $next
 * @return mixed
 */
public function handle($request, Closure $next)
{
    if ($request->route()->named('profile')) {
       //
    }

    return $next($request);
}