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);
}

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

تسمح لك مجموعات المسارات بمشاركة الخاصيات (attributes)، مثل البرمجيّات الوسيطة أو مجالات الأسماء (namespaces)، بين عدد كبير من المسارات دون الحاجة لتعريفها على حدة كل مرّة. تحدّد الخاصيات المشتركة في شكل مصفوفة كأول معاملة للتابع Route::group.

البرمجيّات الوسيطة

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

Route::middleware(['first', 'second'])->group(function () {
    Route::get('/', function () {
       // يستخدم البرمجيّة الوسيطة الاولى والثانية  
    });

    Route::get('user/profile', function () {
       // يستخدم البرمجيّة الوسيطة الاولى والثانية 
    });
});

مجالات الأسماء

تعيين نفس مجال الأسماء PHP لمجموعة من وحدات التحكّم باستخدام التابع namespace هي حالة استخدام شائعة أخرى لمجموعات المسارات:

Route::namespace('Admin')->group(function () {
   //   "App\Http\Controllers\Admin" وحدات التحكم داخل جال الاسماء 
});

يتضمّن RouteServiceProvider افتراضيًّا ملفات مساراتك داخل مجموعة مجال أسماء، ممّا يسمح لك بتسجيل مسارات وحدة التجكّم دون الحاجة لتحديد سابقة مجال الأسماء App\Http\Controllers كاملة. تحتاج فقط لتحديد جزء مجال الأسماء الذي يأتي مع مجال الأسماء App\Http\Controllers الأساسي.

توجيه النطاقات الفرعيّة (Sub-Domain Routing)

يمكن استخدام مجموعات المسارات أيضًا لمعالجة توجيه النطاقات الفرعيّة (sub-domain). يمكن تعيين معاملات المسارات للنطاقات الفرعيّة مثل رابط URI المسارات تمامًا مما يسمح لك بالحصول على جزء من النطاق الفرعي لاستخدامه في مسارك أو في وحدة تحكّمك. يمكن تحديد النطاق الفرعي بمناداة التابع domain قبل تعريف المجموعة:

Route::domain('{account}.myapp.com')->group(function () {
    Route::get('user/{id}', function ($account, $id) {
       // "/admin/users" URL يماثل 
    });
});

سابقات المسار (Route Prefixes)

يمكن استخدام التابع prefix لسبق (prefix) كل مسار في المجموعة برابط URI معيّن. قد ترغب مثلًا في سبق كل روابط URIs المسارات داخل المجموعة admin:

Route::prefix('admin')->group(function () {
    Route::get('users', function () {
       // "/admin/users" URL يماثل 
    });
});

سابقات اسم المسار

يمكن استخدام التابع name لسبق كل اسم مسار في المجموعة بسلسلة نصيّة (string) معيّنة. قد ترغب مثلًا في سبق كل أسماء المسارات المجموعة ب admin. تسبق السلسلة النصيّة اسم المسار كما هي تمامًا لذا تأكّد من إضافة الحرف اللاحق . في السّابقة:

Route::name('admin.')->group(function () {
    Route::get('users', function () {
       // Route assigned name "admin.users"...
    })->name('users');
});

ارتباط نموذج المسار (Route Model Binding)

عند إضافة نموذج ID لمسار أو وحدة تحكّم، كثيرا ما ستستعلم (query) لاسترداد النموذج الذي يوافق ذاك ID. يوفّر ارتباط نموذج المسار طريقة ملائمة لإضافة نسخ نموذجك (model instances) مباشرة لمساراتك. يمكنك مثلًا إضافة نسخة النموذج User التي تطابق ID المحدد بدل إضافة ID المستخدم.

الارتباط الضمني

يستبين Laravel تلقائيًّا النماذج Eloquent المعرّفة في أفعال المسارات أو وحدات تحكّم التي تطابق متغيّراتها (variables) المُلمّحة على النوع (type-hinted) جزءًا من اسم مسار. على سبيل المثال:

Route::get('api/users/{user}', function (App\User $user) {
    return $user->email;
});

بما أن نوع المتغيّر user$ مُلمّح (type-hinted) على أنه النموذج Eloquent  الخاص ب App\User واسم المتغيّر يطابق جزء {user} من رابط URI، سيضيف Laravel نسخة النموذج صاحبة المعرّف ID المطابق للقيمة من رابط URI الطلب. سيولّد رد 404 HTTP تلقائيًّا إن لم توجد نسخة نموذج مطابقة.

تخصيص الاسم المفتاح (Customizing The Key Name)

إن أردت أن يستخدم ارتباط النموذج عمود قاعدة بيانات عدا المعرّف id عند استرداد صنف نموذج معيّن، تستطيع إعادة تعريف (override) التابع getRouteKeyName  في النموذج Eloquent:

/**
 * تحصّل على مفتاح المسار للنموذج.
 *
 * @return string
 */
public function getRouteKeyName()
{
    return 'slug';
}

الارتباط الصّريح

لتسجيل ارتباط صريح، استخدم التابع model للمُوجّه (router) لتحديد صنف معاملة معيّنة. يجب أن تعرّف ارتباطات نموذجك الصّريح في التابع boot من صنف RouteServiceProvider:

public function boot()
{
    parent::boot();

    Route::model('user', App\User::class);
}

في الخطوة التّالية عرّف مسارًا يحتوي معاملة {user}:

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

ستضاف نسخة User للمسار بما أننا ربطنا كل معاملات {user} بالنموذج App\User. فمثلا الان سيضيف الطلب المُوجّه الى profile/1 نسخة User من قاعدة البيانات ذات ID يساوي 1.

إن لم توجد نسخة نموذج في قاعدة البيانات سيولّد رد 404 HTTP تلقائيٌّا.

تخصيص منطق التحليل (Customizing The Resolution Logic)

إن رغبت في استخدام منطق تحليل خاص بك، ما عليك إلا استخدام التابع Route::bind. سيتلقى النطاق المغلق Closure الذي تمرره للتابع bind  قيمة الجزء URI ويرد نسخة من الصّنف الذي يجب إضافته للمسار:

public function boot()
{
    parent::boot();

    Route::bind('user', function ($value) {
        return App\User::where('name', $value)->first() ?? abort(404);
    });
}

المسارات الاحتياطية (Fallback Routes)

تستطيع تعريف مسار إحتياطي يُنفَّذ عندما لا يطابق أي مسار اخر الطلب الوارد باستخدام التابع Route::fallback. تعرض الطلبات غير المُعالجة عموما صفحة "404" عبر معالج استثناءات تطبيقك. لكن ستُطبّق كل البرمجيّات الوسيطة في مجموعة البرمجيّات web الوسيطة على المسار fallback بما أنك تستطيع تعريفه داخل ملفك routes/web.php. أنت حر طبعًا في إضافة برمجيّات وسيطة لهذا المسار حسب الحاجة:

Route::fallback(function () {
   //
});

حدّ المعدّل (Rate Limiting)

يحتوي Laravel على برمجيّة وسيطة لحد معدّل الوصول للمسارات داخل تطبيقك. عيّن للبدء البرمجيّة الوسيطة throttle على مسار أو مجموعة مسارات. تقبل البرمجيّة الوسيطة throttle معاملتين تقرّران الحد الأقصى من الطلبات التي يمكن صنعها في عدد معيّن من الدقائق. فلنحدد مثلًا عدد المرات التي يقدر مستخدم مصادق عليه من الوصول فيها لمجموعة المسارات التالية 60 مرة في الدقيقة:

Route::middleware('auth:api', 'throttle:60,1')->group(function () {
    Route::get('/user', function () {
       //
    });
});

حد المعدّل الديناميكي

تستطيع تحديد حد طلبات أقصى ديناميكي على أساس خاصيّة (attribute) للنموذج User المصادق عليه. يمكنك مثلًا تمرير اسم الخاصية للبرمجيّة الوسيطة throttle  إن احتوى نموذجك User على الخاصيّة rate_limit كي يُستخدم لحساب حد الطلبات الأقصى:

Route::middleware('auth:api', 'throttle:rate_limit,1')->group(function () {
    Route::get('/user', function () {
        //
    });
});

انتحال تابع الاستمارة (Form Method Spoofing)

لا تدعم استمارات HTML الطرق PUT، و PATCH، و DELETE. لذلك ستحتاج لإضافة حقل method_ خفيّ للاستمارة عند تعريف مسارات PUT، و PATCH، و DELETE التي تُنادى من استمارة HTML. ستُستَخدم القيمة المرسلة مع الحقل method_ كتابع الطلب HTTP:

<form action="/foo/bar" method="POST">
    <input type="hidden" name="_method" value="PUT">
    <input type="hidden" name="_token" value="{{ csrf_token() }}">
</form>

تستطيع استخدام توجيه method Blade@ لتوليد حقل الإدخال method_:

<form action="/foo/bar" method="POST">
    @method('PUT')
    @csrf
</form>

الوصول للمسار الحالي

تستطيع استخدام التوابع current، و currentRouteName، و currentRouteAction على الواجهة الساكنة Route للوصول للمعلومة حول معالجة المسار للطلب القادم:

$route = Route::current();

$name = Route::currentRouteName();

$action = Route::currentRouteAction();

ارجع لتوثيق API لكل من الصنف الأساسي لواجهة المسار الساكنة ونسخة المسار لمراجعة كل الدوال الممكنة الوصول.

المصادر

• صفحة Routing في توثيق الرّسمي.