توليد عناوين URL في Laravel

مقدمة

يوفّر Laravel العديد من المساعدين لمساعدتك في إنشاء عناوين URL لتطبيقك. فائدتهم الأساسية تظهر طبعا عند بناء روابط في قوالبك (templates) واستجابات الواجهة البرمجيّة، أو عند توليد ردود إعادة توجيه إلى جزء آخر من تطبيقك.

الأساسيات

توليد عناوين URL أساسية

يمكن استخدام المساعد url لتوليد عناوين URL عشوائية لتطبيقك. سيستخدم العنوان URL المُنشأ تلقائيًا المخطَّط (HTTP أو HTTPS) ويستضيف من الطلب الحالي:

$post = App\Post::find(1);

echo url("/posts/{$post->id}");

// http://example.com/posts/1

الوصول إلى العنوان URL الحالي

سترد النسخة Illuminate\Routing\UrlGenerator إن لم يُوفّر أي مسار إلى المساعد url، مما يتيح لك الوصول للمعلومات حول العنوان URL الحالي:

//   تحصّل على العنوان الحالي بدون سلسلة الاستعلام ...
 

echo url()->current();

// احصل على العنوان الحالي بما في ذلك سلسلة الاستعلام ...
echo url()->full();

// احصل على العنوان الكامل للطلب السابق ...
echo url()->previous();

يمكن الوصول لكل هذه التوابع عبر الواجهة الساكنة URL:

use Illuminate\Support\Facades\URL;

echo URL::current();

يمكن الوصول لكل تابع من هذه التوابع عبر الواجهة الساكنة URL:

use Illuminate\Support\Facades\URL;

echo URL::current();

العناوين URL للمسارات المسمّاة

يمكن استخدام المساعد route لتوليد العناوين URL للمسارات المُسمّاة. تتيح لك المسارات المُسمّاة توليد عناوين URL دون أن يقترن بالعنوان URL الفعلي المحدّد في المسار. وهكذا لا تحتاج لعمل أي تغييرات لنداءات دوال مسارك (function) إن تغيّر العنوان URL للمسار.  تخيل على سبيل المثال أن تطبيقك يحتوي على مسار محدد كما يلي:

Route::get('/post/{post}', function () {
   //
})->name('post.show');

لتوليد عنوان URL لهذا المسار تستطيع استخدام المساعد route على النحو التالي:

echo route('post.show', ['post' => 1]);

// http://example.com/post/1

ستولّد غالبًا عناوين URL باستخدام المفتاح الأساسي (primary key) للقوالب Eloquent. ولهذا السبب تستطيع تمرير نماذج Eloquent كقيم مُعاملة. سيستخرج المساعد route مفتاح النموذج الأساسي تلقائيًا:

echo route('post.show', ['post' => $post]);

العناوين URL الموقَّعة

يسمح لك Laravel بإنشاء عناوين URL "مُوقّعة" بسهولة للمسارات المسمّاة. لهذه العناوين "توقيع" مُشفّر (hash) يُلحق بسلسلة الاستعلام النصيّة مما يسمح بالتحقق من عدم تعديل العنوان URL منذ إنشائه. تُعتبر العناوين URL الموقّعة مفيدة جدًّا للمسارات المفتوحة للعموم (publicly accessible) لكن تحتاج لطبقة من الحماية ضد التلاعب بالعناوين URL.

قد تستخدم على سبيل المثال عناوين URL موقّعة لتنفيذ رابط "إلغاء اشتراك" عام يُرسل عبر البريد الإلكتروني إلى عملائك. لإنشاء عنوان URL موقّع لمسار مسمّى، استخدم التابع signedRoute للواجهة الساكنة URL:

use Illuminate\Support\Facades\URL;

return URL::signedRoute('unsubscribe', ['user' => 1]);

إن رغبت في إنشاء URL مسار مُوقّع مؤقت، تستطيع استخدام التابع temporarySignedRoute:

use Illuminate\Support\Facades\URL;

return URL::temporarySignedRoute(
    'unsubscribe', now()->addMinutes(30), ['user' => 1]
);

التحقق من طلبات المسار المُوقّعة

يجب استدعاء التابع hasValidSignature في الطلب الوارد للتحقق صلاحيّة توقيعه:

use Illuminate\Http\Request;

Route::get('/unsubscribe/{user}', function (Request $request) {
    if (! $request->hasValidSignature()) {
        abort(401);
    }

   // ...
})->name('unsubscribe');

يمكنك تعيين البرمجيّة الوسيطة Illuminate\Routing\Middleware\ValidateSignature على المسار كبديل. يجب تعيين مفتاح على هذه البرمجيّة الوسيطة في مصفوفة نواتك HTTP المسمّاة routeMiddleware إن لم يوجد مسبقا:

/**
 * برمجيّة المسار الوسيطة للتطبيقك.
 * 
 * يمكن تعيين هذه البرمجيّات الوسيطة على مجموعات أو استخدامها على حدة
 *
 * @var array
 */
protected $routeMiddleware = [
    'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
];

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

Route::post('/unsubscribe/{user}', function (Request $request) {
   // ...
})->name('unsubscribe')->middleware('signed');

URLs لأفعال وحدات التحكّم

ستولّد الدالّة action عنوان URL لفعل وحدة التحكّم المحدّد. لا تحتاج إلى تمرير مجال الاسم الكامل لوحدة التحكم. مرّر اسم صنف وحدة التحكّم نسبة لمجال اسم App\Http\Controllers بدل ذلك:

$url = action('HomeController@index');

يمكنك أيضًا الإشارة للأفعال باستخدام صيغة مصفوفة "قابلة للاستدعاء":

use App\Http\Controllers\HomeController;

$url = action([HomeController::class, 'index']);

تستطيع تمرير معاملات المسار كمتغيّر وسيط ثاني للدالة إن تقبّلتهم دالّة المتحكّم:

$url = action('UserController@profile', ['id' => 1]);

القيم الافتراضيّة

قد ترغب بتطبيقات معيّنة في تحديد قيم افتراضية  لمعاملات عناوين URL معيّنة على مستوى الطلب كاملا.  تخيّل على سبيل المثال أنّ العديد من مساراتك تعرّف معاملة {locale}:

Route::get('/{locale}/posts', function () {
   //
})->name('post.index');

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

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\URL;

class SetDefaultLocaleForUrls
{
    public function handle($request, Closure $next)
    {
        URL::defaults(['locale' => $request->user()->locale]);

        return $next($request);
    }
}

بمجرّد تعيين القيمة الافتراضية للمعاملة locale لن تحتاج لتمرير قيمتها عند توليد عناوين URL عبر المساعد route.

مصادر

• صفحة URL Generation من توثيق Laravel الرسمي.