عرض مصدر Laravel/authentication

<noinclude>{{DISPLAYTITLE:الاستيثاق في Laravel}}</noinclude>
== المقدمة ==
تريد أن تبدأ بسرعة؟ فقط شغِّل الأمر <code>php artisan make:auth</code> و <code>php artisan migrate</code> في تطبيق Laravel جديد. ثم انتقل بالمتصفح إلى العنوان <nowiki>http://your-app.test/register</nowiki> أو أي عنوان URL آخر تم تعيينه لتطبيقك. هذان الأمران سوف يعتنيان بنظام الاستيثاق بأكمله الخاص بك!

يجعل [[Laravel]] برمجة نظام الاستيثاق بسيطةًجدًا. في الحقيقة، يُعدّ كل شيء تقريبًا بالنسبة لك افتراضيًا دون تدخلٍ منك. يوجد ملف إعدادات الاستيثاق في <code>config/auth.php</code>، والذي يحتوي على العديد من الخيارات الموثقة جيدًا لتغيير وتبديل سلوك خدمات الاستيثاق.

في جوهرها، تتكون مرافق التوثيق من "الحراس - guards" و "الموفرين - providers".

يحدد الحراس كيفية استيثاق المستخدمين عند كل طلب. على سبيل المثال، يأتي [[Laravel]] مع الحارس session الذي يحافظ على الحالة باستخدام بتخزين الجلسة وملفات تعريف الارتباط (cookies).

يحدد الموفرون كيفية استرداد معلومات المستخدمين من سعة التخزين الدائم. يأتي [[Laravel]] بالدعم لاسترداد معلومات المستخدمين باستخدام [[Laravel/eloquent|Eloquent]] ومنشئ استعلام قاعدة البيانات. ومع ذلك، أنت حر في تعريف المزيد من موفري الخدمات حسب حاجة تطبيقك.

لا تقلق إذا كان كل هذا يبدو محيرًا الآن! أغلب التطبيقات لا تحتاج للتغيير على إعدادات الاستيثاق التلقائية.

== اعتبارات قاعدة البيانات ==
تلقائيَا، يتضمن [[Laravel]] نموذج App\User [[Laravel/eloquent|Eloquent]] في ملف تطبيقك. يمكن استخدام هذا النموذج مع برنامج التشغيل التلقائي للاستيثاق [[Laravel/eloquent|Eloquent]]. إذا كان تطبيقك لا يستخدم [[Laravel/eloquent|Eloquent]]، فيمكنك استخدام برنامج تشغيل الاستيثاق الخاص بقاعدة البيانات والذي يستخدم منشئ الاستعلام (query builder) الخاص بإطار Laravel.

عند إنشاء مخطط قاعدة البيانات لنموذج App\User، تأكد بأن طول عمود كلمة المرور لا يقل عن 60 محرفًا. الخيار الجيد سيكون الحفاظ على الطول التلقائي لعمود السلاسل النصية والذي يكون 255 محرفًا.

عليك أن تتأكد أيضًا من أن جدول المستخدمين users (أو ما يعادله) يحتوي على عمودٍ يقبل سلسلة نصية <code>remembre_token</code> من 100 حرف ويمكن أن تكون قيمته فارغةً (null). سيُستخدَم هذا العمود لتخزين رمز مميز للمستخدمين الذين يختارون (تذكرني - remember me) عند تسجيل الدخول إلى تطبيقك.

== مدخل سريع إلى الاستيثاق ==
يأتي [[Laravel]] مع العديد من وحدات تحكم الاستيثاق التي تكون منشأة مسبقًا، والتي تقع في مجال الأسماء <code>App\Http\Controllers\Auth</code>. يعالج <code>RegisterController</code> تسجيلات المستخدمين الجدد، ويتعامل <code>LoginController</code> مع الاستيثاق، يعالج <code>ForgotPasswordController</code> روابط البريد الإلكتروني لإعادة تعيين كلمات المرور، و يحتوي <code>ResetPasswordController</code> على المنطق اللازم لإعادة ضبط كلمات المرور. يستخدم كل من وحدات التحكم المذكورة سمة (trait) لإدراج التوابع الضرورية لها. بالنسبة للكثير من التطبيقات، لن تحتاج إلى تعديل وحدات التحكم هذه على الإطلاق.

=== التوجيه ===
يوفر [[Laravel]] طريقة سريعة لتجميع جميع المسارات والواجهات التي تحتاج لها للاستيثاق باستخدام أمرٍ واحدٍ بسيطٍ:<syntaxhighlight lang="php">
php artisan make:auth
</syntaxhighlight>

يجب استخدام هذا الأمر على التطبيقات الجديدة، حيث سيقوم بتثبيت تخطيط الواجهة (layout view)، وواجهات التسجيل (registration) وتسجيل الدخول (login)، بالإضافة إلى المسارات لكل نقاط النهاية الخاصة بالاستيثاق. سيولَّد <code>HomeController</code> أيضًا للتعامل مع طلبات ما بعد تسجيل الدخول للوحة التحكم الخاصة بتطبيقك.

=== الواجهات ===
كما ذكرنا في القسم السابق، فإن الأمر <code>php artisan make:auth</code> سيُنشِئ كل الواجهات التي تحتاج ها للاستيثاق ويضعها في المجلد <code>resources/views/auth</code>.

الأمر <code>make:auth</code> سيُنشِئ أيضًا المجلد <code>resources/views/layouts</code> الذي يحتوي على التخطيط الأساسي (base layout) الخاص بتطبيقك. كل هذه الواجهات تستخدم إطار العمل [[Bootstrap]]، لكنك حر في تخصيصها كيفما تشاء.

=== الاستيثاق ===
الآن بعد أن أعددتَ المسارات والواجهات لوحدات تحكم الاستيثاق، أنت جاهز للتسجيل، وللاستيثاق على المستخدمين الجدد لتطبيقك! يمكنك تسجيل الدخول لتطبيقك عن طريق المتصفح لمّا كانت وحدات تحكم الاستيثاق تحتوي على المنطق (عن طريق السمات [traits]) لاستيثاق المستخدمين المسجلين ولتخزين المستخدمين الجدد في قاعدة البيانات.

==== تخصيص المسار ====
عندما يتم الاستيثاق على مستخدم بنجاح، سيُعاد توجيهه إلى الرابط<code>/home</code>. يمكنك تخصيص مسار إعادة التوجيه بعد الاستيثاق عن طريق تعريف الخاصية <code>redirectTo</code> على <code>LoginController</code> و <code>RegisterController</code> و <code>ResetPasswordController</code>:<syntaxhighlight lang="php">
protected $redirectTo = '/';
</syntaxhighlight>

بعد ذلك، يجب عليك تعديل التابع <code>handle</code> المتحكم بالبرنامج الوسيط <code>RedirectIfAuthenticated</code> لاستخدام رابط URI الجديد الخاص بك عند إعادة توجيه المستخدم.

إذا كان مسار إعادة التوجيه يحتاج إلى منطق إنشاء مخصص، فيمكنك تعريف التابع <code>redirectTo</code> بدلًا من خاصية <code>redirectTo</code>:<syntaxhighlight lang="php">
protected function redirectTo()

{

   return '/path';

}


</syntaxhighlight>

ملاحظة: سيكون للتابع <code>redirectTo</code> الأولوية على خاصية <code>redirectTo</code>.

==== تخصيص اسم المستخدم ====
بشكل افتراضي، يستخدم [[Laravel]] حقل البريد الإلكتروني للاستيثاق. إذا كنت ترغب في تخصيص هذا، فيمكنك تعريف التابع <code>username</code> في <code>LoginController</code>:<syntaxhighlight lang="php">
public function username()

{

   return 'username';

}


</syntaxhighlight>

==== تخصيص الحارس ====
يمكنك أيضًا تخصيص "الحارس" المستخدم لاستيثاق المستخدمين وتسجيلهم. للبدء، عرّف التابع <code>guard</code> على <code>LoginController</code>، و <code>RegisterController</code>، و <code>ResetPasswordController</code>. يجب أن يعيد التابع نسخة عن الحارس:<syntaxhighlight lang="php">
use Illuminate\Support\Facades\Auth;

protected function guard()

{

   return Auth::guard('guard-name');

}


</syntaxhighlight>

==== التحقق/تخصيص التخزين ====
لتعديل الحقول اللازم ملؤها في استمارة تسجيل مستخدم جديد في تطبيقك، أو لتخصيص كيفية تخزين المستخدمين الجدد في قاعدة البيانات الخاصة بك، يمكنك تعديل الصنف <code>RegisterController</code>. هذا الصنف مسؤولٌ عن التحقق من صحة المستخدمين وإنشاء مستخدمين جدد لتطبيقك.

يحتوي التابع validator في <code>RegisterController</code> على قواعد التحقق من صحة المستخدمين الجدد للتطبيق. أنت حر في تعديل هذا التابع كما تريد.

يُعدّ التابع <code>create</code> في <code>RegisterController</code> مسؤولًا عن إنشاء سجلات <code>App\User</code> جديدة في قاعدة البيانات الخاصة بك باستخدام [[Laravel/eloquent|Eloquent ORM]]. أنت حر في تعديل هذا التابع وفقًا لاحتياجات قاعدة البيانات الخاصة بك.

== استرداد المستخدم المستوثق منه ==
يمكنك الوصول إلى المستخدم الذي تم استيثاقه عبر واجهة <code>Auth</code>:<syntaxhighlight lang="php">
use Illuminate\Support\Facades\Auth;

// احصل على المستخدم الحالي المستوثق منه ...
$user = Auth::user();

// احصل على معرف المستخدم الحالي المستوثق منه ID...
$id = Auth::id();


</syntaxhighlight>

بدلًا من ذلك، بمجرد استيثاق المستخدم، يمكنك الوصول إلى المستخدم الذي تمت الاستيثاق منع عبر نسخة من <code>Illuminate\Http\Request</code>. تذكر أنَّه ستُضاف أصناف <code>type-hinted</code> تلقائيًا في دوال وحدة التحكم الخاصة بك:<syntaxhighlight lang="php">
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class ProfileController extends Controller
{
   /**
    * تحديث حساب المستخدم.
    *
    * @param  Request $request
    * @return Response
    */

   public function update(Request $request)

   {
      // $request->user() تعيد نسخة عن المستخدم المستوثق منه ...
   }
}

</syntaxhighlight>

==== تحديد ما إذا كان المستخدم الحالي مستوثقًا منه ====
لتحديد ما إذا كان المستخدم قد قام بالفعل بتسجيل الدخول إلى التطبيق الخاص بك، يمكنك استخدام التابع check على واجهة Auth، والتي ستعيد true إذا كان المستخدم مستوثقًا منه:<syntaxhighlight lang="php">
use Illuminate\Support\Facades\Auth;

if (Auth::check()) {
  // المستخدم قام بتسجيل الدخول...
}


</syntaxhighlight>

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

=== حماية المسارات ===
يمكن استخدام برنامج وسيط للسماح للمستخدمين الذين تم الاستيثاق lkil فقط بالوصول إلى مسار معين. يعتمد Laravel على الوسيط (middleware)‏ auth، الذي يُعرّف في Illuminate\Auth\Middleware\Authenticate. ولمّا كان هذا الوسيط مسجل بالفعل في نواة HTTP، فكل ما عليك فعله هو إرفاق الوسيط بتعريف المسار:<syntaxhighlight lang="php">
Route::get('profile', function () {
  // فقط المستخدمين المستوثق منهم يمكنهم الدخول...
})->middleware('auth');


</syntaxhighlight>

بالطبع، إذا كنت تستخدم وحدات تحكم (controllers)، يمكنك استدعاء التابع <code>middleware</code> من الدالة البانية لوحدة التحكم بدلًا من إرفاقها في تعريف المسار مباشرةً:<syntaxhighlight lang="php">
public function __construct()
{
   $this->middleware('auth');
}


</syntaxhighlight>

==== إعادة توجيه المستخدمين غير المستوثق منهم ====
عندما يكشف الوسيط auth مستخدمًا غير مصرحٍ به، فإنه سيعرض إما رد JSON 401، أو إذا لم يكن الطلبُ طلبَ AJAX، فسيعيد توجيه المستخدم إلى المسار المسمى login.

يمكنك تعديل هذا السلوك بتعريف التابع <code>unauthenticated</code> في ملف <code>app/Exceptions/Handler.php</code> :<syntaxhighlight lang="php">
use Illuminate\Auth\AuthenticationException;

protected function unauthenticated($request, AuthenticationException $exception)
{
   return $request->expectsJson()
               ? response()->json(['message' => $exception->getMessage()], 401)
               : redirect()->guest(route('login'));
}


</syntaxhighlight>

==== تحديد حارس ====
عند إرفاق الوسيط (middleware) ‏<code>auth</code> بمسار، يمكنك أيضًا تحديد أي حارس يجب استخدامه للاستيثاق من المستخدم. يجب أن يتطابق الحارس المحدد مع أحد المفاتيح الموجودة في مصفوفة الحراس guards الموجودة في ملف الإعدادات <code>auth.php</code>:<syntaxhighlight lang="php">
public function __construct()
{
   $this->middleware('auth:api');
}


</syntaxhighlight>

=== التضييق على تسجيل الدخول ===
إذا كنت تستخدم الصنف <code>LoginController</code> المضمن مع [[Laravel]]، فسوف يتم تضمين سمة (trait)‏ <code>Illuminate\Foundation\Auth\ThrottlesLogins</code> في وحدة التحكم الخاصة بك. افتراضيًا، لن يتمكن المستخدم من تسجيل الدخول لمدة دقيقة واحدة إذا فشل في تقديم بيانات الاعتماد الصحيحة بعد عدة محاولات. التضييق يكون فردي لاسم المستخدم أو بريده الإلكتروني وعنوان IP الخاص به.

== استيثاق المستخدمين يدويًا ==
بالطبع، ليس واجبا عليك استخدام وحدات تحكم الاستيثاق المضمنة مع [[Laravel]]. إذا اخترت إزالة وحدات التحكم هذه، فستحتاج إلى إدارة الاستيثاق باستخدام أصناف استيثاق Laravel مباشرةً. لا تقلق، فهذا أمر سهل!

سنتمكن من الوصول إلى خدمات استيثاق [[Laravel]] عبر واجهة Auth ، لذلك سنحتاج إلى التأكد من استيراد واجهة <code>Auth</code> في أعلى الصنف. بعد ذلك، دعنا نتحقق من التابع <code>attempt</code> :<syntaxhighlight lang="php">
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class LoginController extends Controller
{
   /**
    * التعامل مع كلّ محاولات الاستيثاق     *
    * @param  \Illuminate\Http\Request $request
    *
    * @return Response
    */
   public function authenticate(Request $request)
   {
       $credentials = $request->only('email', 'password');
       if (Auth::attempt($credentials)) {
          // Authentication passed...
           return redirect()->intended('dashboard');
       }
   }
}


</syntaxhighlight>

يستقبل التابع <code>attempt</code> مصفوفةً من أزواج المفاتيح/القيم كأوّل وسيط لها. ستُستخدَم القيم في المصفوفة للعثور على المستخدم في جدول قاعدة البيانات. لذلك، في المثال أعلاه، سيتم استرداد المستخدم من خلال قيمة عمود البريد الإلكتروني. إذا عُثِرَ على المستخدم، فستُقارن كلمة المرور المشفرة والمخزنة في قاعدة البيانات مع قيمة كلمة المرور التي مُرِّرَت إلى التابع عبر المصفوفة. ليس عليك تشفير كلمة المرور المحددة كما هو الحال مع قيمة كلمة المرور، نظرًا لأن إطار العمل سيجري تلك العملية تلقائيًا قبل مقارنتها بكلمة المرور المخزنة في قاعدة البيانات. إذا تطابقت كلمتي المرور فستبدأ جلسة استيثاق للمستخدم.

سيعيد التابع <code>attempt</code> القيمة <code>true</code> إذا كان الاستيثاق ناجحًا. خلاف ذلك، ستُعاد القيمة <code>false</code>.

سيعيد التابع <code>intended</code> توجيه المستخدم إلى عنوان URL الذي كان يحاول الوصول إليه قبل أن يتم اعتراضه بواسطة برنامج الاستيثاق الوسيط (authentication middleware). يمكن إعطاء عنوان URI احتياطي لهذا التابع في حالة عدم توافر العنوان المقصود.

==== تحديد شروط إضافية ====
إذا كنت ترغب في ذلك، يمكنك أيضًا إضافة شروط إضافية إلى استعلام الاستيثاق بالإضافة إلى البريد الإلكتروني وكلمة المرور. على سبيل المثال، قد نتحقق من أن المستخدم معلم عليه على أنَّه نشط "active":<syntaxhighlight lang="php">
if (Auth::attempt(['email' => $email, 'password' => $password, 'active' => 1])) {
  // المستخدم نشط، غير محظور، وموجود .
}


</syntaxhighlight>

ملاحظة: في هذه الأمثلة، لا يعد البريد الإلكتروني إجباريًا، بل استخدمناه كمثال فقط. يجب عليك استخدام أي اسم عمود يتوافق مع "اسم المستخدم" (username) في قاعدة البيانات الخاصة بك.

==== الوصول إلى نسخة حارس محددة ====
يمكنك تحديد نسخة الحارس الذي ترغب في استخدامه عبر التابع guard على الواجهة <code>Auth</code>. هذا يسمح لك بإدارة الاستيثاق لأجزاء منفصلة من التطبيق الخاص بك باستخدام نماذج مستقلة تمامًا (separate authenticatable models) أو جداول مستخدم (user tables) مستقلة.

يجب أن يتطابق اسم الحارس الذي مُرِّرَ إلى التابع guard مع أحد الحراس الذين ضبطناها في ملف الإعدادات <code>auth.php</code> الخاص بك:<syntaxhighlight lang="php">
if (Auth::guard('admin')->attempt($credentials)) {
  //
}


</syntaxhighlight>

==== تسجيل الخروج ====
لتسجيل خروج المستخدمين من التطبيق الخاص بك، يمكنك استخدام التابع <code>logout</code> في الواجهة <code>Auth</code>. سيؤدي ذلك إلى مسح معلومات الاستيثاق من جلسة المستخدم:<syntaxhighlight lang="php">
Auth::logout();
</syntaxhighlight>

=== تذكر المستخدمين ===
إذا كنت ترغب في توفير خاصية "تذكرني" في التطبيق الخاص بك، فيجوز لك تمرير قيمة منطقية كوسيط ثاني إلى التابع <code>attempt</code>، والذي سيحافظ على استيثاق المستخدم إلى أجل غير مسمى، أو حتى يسجِّل الخروج يدويًا. بالطبع، يجب أن يتضمن جدول المستخدمين users الخاص بك العمود بنوع «سلسلة نصية» باسم <code>remember_token</code> ، والذي سيُستخدَم لتخزين رمز "تذكرني".<syntaxhighlight lang="php">
if (Auth::attempt(['email' => $email, 'password' => $password], $remember)) {
  // تم تذكر المستخدم ...
}


</syntaxhighlight>

ملاحظة: إذا كنت تستخدم <code>LoginController</code> المضمّن مع Laravel، فإن المنطق الصحيح "لتذكر" المستخدمين قد بُرمِج بالفعل من خلال السمات (traits) المستخدمة بواسطة وحدة التحكم.

إذا كنت "تتذكر" المستخدمين ، فيمكنك استخدام التابع <code>viaRemember</code> لتحديد ما إذا كان المستخدم قد تم استيثاقه باستخدام كعكة "Remember me":<syntaxhighlight lang="php">
if (Auth::viaRemember()) {
  //
}


</syntaxhighlight>

=== طرائق الاستيثاق الأخرى ===

==== الاستيثاق على نسخة المستخدم ====
إذا كنت تحتاج إلى تسجيل الدخول لنسخة مستخدم موجودة مسبقاً، فيمكنك استدعاء دالة <code>login</code> مع نسخة المستخدم. يجب أن يكون الكائن المحدد تطبيقًا لعقد <code>Illuminate\Contracts\Auth\Authenticatable</code>. وبالطبع ،فإن نموذج <code>App\User</code> المتضمن مع [[Laravel]] ينفذ بالفعل هذه الواجهة:<syntaxhighlight lang="php">
Auth::login($user);
// تسجيل الدخول و “تذكر” المستخدم المعطى
Auth::login($user, true);


</syntaxhighlight>

بالطبع، يمكنك تحديد نسخة الـحارس الذي ترغب في استخدامه :<syntaxhighlight lang="php">
Auth::guard('admin')->login($user);
</syntaxhighlight>

استيثاق على مستخدم عن طريق المعرف

لتسجيل دخول مستخدم في التطبيق من خلال المعرف الخاص بهم، يمكنك استخدام دالة <code>loginUsingId</code>. تقبل هذه دالة المفتاح الأساسي للمستخدم الذي ترغب في الاستيثاق عليه :<syntaxhighlight lang="php">
Auth::loginUsingId(1);
// تسجيل الدخول و “تذكر” المستخدم المعطى...
Auth::loginUsingId(1, true);


</syntaxhighlight>

استيثاق على مستخدم مرة واحدة

يمكنك استخدام دالة <code>once</code> لتسجيل مستخدم في التطبيق لطلب واحد. لن يتم استخدام أي جلسات أو ملفات تعريف ارتباط، مما يعني أن هذه الدالة قد تكون مفيدة عند إنشاء واجهة برمجة تطبيقات بلا حالة :<syntaxhighlight lang="php">
if (Auth::once($credentials)) {
  //
}


</syntaxhighlight>

استيثاق الــ [[HTML]] القاعدية

توفر استيثاق HTTP القاعدية طريقة سريعة لاستيثاق مستخدمي التطبيق دون إعداد صفحة "تسجيل دخول" خاصة. للبدء ، أرفق البرمجية الوسيطة <code>auth.basic</code> بمسارك. يتم تضمين البرمجية الوسيطة <code>auth.basic</code> مع إطار عمل [[Laravel]]، لذلك لا تحتاج إلى تعريفها :<syntaxhighlight lang="php">
Route::get('profile', function () {
  // فقط المستخدمين المصادق عليهم يمكنهم الدخول...
})->middleware('auth.basic');


</syntaxhighlight>

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

ملاحظة حول FastCGI

إذا كنت تستخدم PHP FastCGI، فقد لا تعمل استيثاق HTTP القاعدية بشكل صحيح خارج الصندوق. يجب إضافة الأسطر التالية إلى ملف <code>htaccess.</code> الخاص بك:<syntaxhighlight lang="php">
RewriteCond %{HTTP:Authorization} ^(.+)$
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]


</syntaxhighlight>

الاستيثاق القاعدية للــ [[HTML]] عديم الحالة

يمكنك أيضًا استخدام استيثاق HTTP القاعدية دون تعيين ملف تعريف ارتباط خاص بمستخدم في الجلسة، وهو أمر مفيد بشكل خاص لاستيثاق واجهة برمجة التطبيقات API. للقيام بذلك، قم بتعريف البرمجية الوسيطة التي تستدعي الدالة <code>onceBasic</code>. إذا لم يتم إرجاع أي رد بواسطة الدالة السابقة ، فقد يتم تمرير الطلب إلى التطبيق :<syntaxhighlight lang="php">
namespace App\Http\Middleware;
use Illuminate\Support\Facades\Auth;

class AuthenticateOnceWithBasicAuth
{
   /**
    * الإعتناء بإستعلام قادم.
    *
    * @param  \Illuminate\Http\Request  $request
    * @param  \Closure $next
    * @return mixed
    */

   public function handle($request, $next)
   {
       return Auth::onceBasic() ?: $next($request);
   }
}
  //بعد ذلك، سجّل البرمجية الوسيطة الخاصة بالمسار وأرفقها بالمسار:

Route::get('api/user', function () {

  // فقط المستخدمين المصادق عليهم يمكنهم الدخول ...
})->middleware('auth.basic.once');

</syntaxhighlight>

تسجيل الخروج

لتسجيل خروج المستخدمين يدويًا، يمكنك استخدام دالة <code>logout</code> على واجهة <code>Auth</code>. سيؤدي ذلك إلى مسح معلومات الاستيثاق في جلسة المستخدم:<syntaxhighlight lang="php">
use Illuminate\Support\Facades\Auth;

Auth::logout();


</syntaxhighlight>

استبعاد الجلسات على الأجهزة الأخرى

يوفر [[Laravel]] أيضًا آلية لإبطال و "تسجيل الخروج" من جلسات المستخدم النشطة على الأجهزة الأخرى دون إبطال جلسة العمل على أجهزتهم الحالية. قبل البدء، يجب أن تتأكد من أن البرمجية الوسيطة <code>Illuminate\Session\Middleware\AuthenticateSession</code> موجودة وغير محددة كتعليق في صنف <code>app/Http/Kernel.php</code> web مجموعة برمجية وسيطة :<syntaxhighlight lang="php">
'web' => [

  // ...
   \Illuminate\Session\Middleware\AuthenticateSession::class,
  // ...

],


</syntaxhighlight>

بعد ذلك، يمكنك استخدام دالة <code>logoutOtherDevices</code> على واجهة <code>Auth</code>. تتطلب هذه الدالة من المستخدم تقديم كلمة المرور الحالية الخاصة به، والتي يجب أن يقبلها التطبيق من خلال حقل إدخال:<syntaxhighlight lang="php">
use Illuminate\Support\Facades\Auth;

Auth::logoutOtherDevices($password);


</syntaxhighlight>

عندما يتم استدعاء دالة <code>logoutOtherDevices</code>، سيتم إلغاء جلسات العمل الأخرى للمستخدم تمامًا، مما يعني أنه سيتم "تسجيل الخروج" من جميع الحراس الذين تمت الاستيثاق بواسطتهم من قبل.

إضافة حراس مخصصين

يمكنك تحديد حراس الاستيثاق الخاصين بك باستخدام دالة <code>extend</code> على واجهة Auth. يجب عليك وضع هذا الاستدعاء للتمديد داخل مزود الخدمة. نظرًا لأن Laravel يأتي بالفعل مع <code>AuthServiceProvider</code>، يمكننا وضع الشفرة في هذا المزود :<syntaxhighlight lang="php">
namespace App\Providers;
use App\Services\Auth\JwtGuard;
use Illuminate\Support\Facades\Auth;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
   /**
    * Register any application authentication / authorization services.
    *
    * @return void
    */

   public function boot()
   {
       $this->registerPolicies();
       Auth::extend('jwt', function ($app, $name, array $config) {
          // Return an instance of Illuminate\Contracts\Auth\Guard...
           return new JwtGuard(Auth::createUserProvider($config['provider']));
       });
   }
}


</syntaxhighlight>

كما ترون في المثال أعلاه، الرد الذي يمرر إلى دالة <code>extend</code> يجب أن يرجع تجسيد لـ <code>Illuminate\Contracts\Auth\Guard</code>. تحتوي هذه الواجهة على بعض الدوال التي ستحتاج إلى برمجتها لتحديد حارس مخصص. بمجرد تحديد حارسك المخصص، يمكنك استخدام هذا الحارس في إعدادات الحراس في ملف الإعدادات <code>auth.php</code> الخاص بك:<syntaxhighlight lang="php">
'guards' => [

   'api' => [
       'driver' => 'jwt',
       'provider' => 'users',
   ],
],


</syntaxhighlight>

حراس طلب الإغلاق

إن أبسط طريقة لبرمجة نظام استيثاق مخصص يستند إلى إستعلام HTTP هو باستخدام دالة Auth::viaRequest. تتيح لك هذه الدالة تحديد عملية الاستيثاق الخاصة بك بسرعة باستخدام إغلاق واحد.

للبدء، استدعي دالة Auth::viaRequest ضمن دالة boot الخاص بـ AuthServiceProvider. تقبل دالة viaRequest اسم حارس كمدخل أول لها. يمكن أن يكون هذا الاسم أي سلسلة نصية تصف حارسك المخصص. يجب أن يكون المدخل الثاني للدالة عبارة عن إغلاق الذي يتلقى طلب HTTP الوارد ويعيد نسخة مستخدم أو، في حالة فشل الاستيثاق، فراغ :<syntaxhighlight lang="php">
use App\User;

use Illuminate\Http\Request;

use Illuminate\Support\Facades\Auth;

/**

* Register any application authentication / authorization services.

*

* @return void

*/

public function boot()

{

   $this->registerPolicies();

   Auth::viaRequest('custom-token', function ($request) {

       return User::where('token', $request->token)->first();

   });

}


</syntaxhighlight>

بمجرد تحديد حارسك المخصص، يمكنك استخدام هذا الحارس في إعدادات الحراس في ملف الإعدادات auth.php الخاص بك:<syntaxhighlight lang="php">
'guards' => [

   'api' => [

       'driver' => 'custom-token',

   ],

],


</syntaxhighlight>

إضافة موفري مستخدم مخصصين

إذا كنت لا تستخدم قاعدة بيانات علائقية تقليدية لتخزين المستخدمين، فستحتاج إلى تمديد Laravel مع موفر المستخدم للاستيثاق الخاص بك. سنستخدم دالة provider على واجهة Auth لتحديد موفر مستخدم مخصص:<syntaxhighlight lang="php">
namespace App\Providers;

use Illuminate\Support\Facades\Auth;

use App\Extensions\RiakUserProvider;

use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider

{

   /**

    * Register any application authentication / authorization services.

    *

    * @return void

    */

   public function boot()

   {

       $this->registerPolicies();

       Auth::provider('riak', function ($app, array $config) {

          // إعادة نسخة عن : Illuminate\Contracts\Auth\UserProvider...

           return new RiakUserProvider($app->make('riak.connection'));

       });

   }

}


</syntaxhighlight>

بعد تسجيل الموفر باستخدام دالة provider، يمكنك التبديل إلى موفر المستخدم الجديد في ملف الإعدادات auth.php. أولاً، حدد موفر يستخدم برنامج التشغيل الجديد الخاص بك:<syntaxhighlight lang="php">
'providers' => [

   'users' => [

       'driver' => 'riak',

   ],

],


</syntaxhighlight>

أخيرًا ، يمكنك استخدام هذا الموفر في إعدادات الحراس الخاصة بك:<syntaxhighlight lang="php">
'guards' => [

   'web' => [

       'driver' => 'session',

       'provider' => 'users',

   ],

],


</syntaxhighlight>

عقد مزود المستخدم

تعتبر تطبيقات Illuminate\Contracts\Auth\UserProvider مسؤولة فقط عن تنفيذ تطبيق Illuminate\Contracts\Auth\Authenticatable خارج نظام تخزين مستمر، مثل MySQL و Riak وغيرها. تسمح هاتان الواجهتان لآليات استيثاق Laravel بمواصلة العمل بغض النظر عن كيفية تخزين بيانات المستخدم أو نوع الصنف المستخدم لتمثيلها.

دعونا نلقي نظرة على عقد Illuminate\Contracts\Auth\UserProvider :<syntaxhighlight lang="php">
namespace Illuminate\Contracts\Auth;

interface UserProvider {

   public function retrieveById($identifier);

   public function retrieveByToken($identifier, $token);

   public function updateRememberToken(Authenticatable $user, $token);

   public function retrieveByCredentials(array $credentials);

   public function validateCredentials(Authenticatable $user, array $credentials);

}

</syntaxhighlight>

تستلم الدالة retrieveById عادة مفتاحاً يمثل المستخدم، مثل مُعرِّف تزايدي تلقائي من قاعدة بيانات MySQL. برمجية Authenticatable التي تطابق المعرف يجب أن تسترجع وتعاد بواسطة الدالة.

تسترد الدالة retrieveByToken مستخدمًا مع معرفه الوحيد identifier$ و الرمز المميز "تذكرني"، المسجل في حقل remember_token. كما هو الحال مع الطريقة السابقة، يجب إرجاع برمجية Authenticatable.

تقوم دالة updateRememberToken بتحديث حقل المستخدم remember_token بالرمز المميز الجديد. يتم تعيين رمز مميز جديد لمحاولة تسجيل الدخول الناجحة "تذكرني" أو عندما يقوم المستخدم بتسجيل الخروج.

تتلقى دالة retrieveByCredentials مصفوفة بيانات الاعتماد التي تم تمريرها إلى دالة Auth::attempt عند محاولة تسجيل الدخول إلى التطبيق. الدالة عليها بعدها أن "تستعلم" في التخزين الدائم الأساسي، للمستخدم مطابقة أوراق الاعتماد تلك. عادةً، ستقوم هذه الدالة بتشغيل استعلام يحتوي على شرط "where" على credentials['username']. يجب أن تقوم الدالة بإرجاع برمجيةAuthenticatable. يجب ألا تحاول هذه الدالة إجراء التحقق من صحة كلمة المرور أو الاستيثاق عليها.

يجب أن تقارن دالة validateCredentials المستخدم مع بيانات الاعتماد للاستيثاق على المستخدم. على سبيل المثال، من المحتمل أن تستخدم هذه الدالة Hash::check لمقارنة قيمة $user-> getAuthPassword () بقيمة $credentials['password']. يجب أن ترجع هذه الدالة صوابًا أو خطأً true أو false مما يشير إلى ما إذا كانت كلمة المرور صالحة.

العقد المصادق عليه

الآن بعد أن اكتشفنا كل دالة من دوال UserProvider، لنلقي نظرة على عقد Authenticatable. تذكر، يجب على الموفر إرجاع برمجيات هذه الواجهة من الدوال  retrieveById, retrieveByToken، و retrieveByCredentials :<syntaxhighlight lang="php">
namespace Illuminate\Contracts\Auth;

interface Authenticatable {

   public function getAuthIdentifierName();

   public function getAuthIdentifier();

   public function getAuthPassword();

   public function getRememberToken();

   public function setRememberToken($value);

   public function getRememberTokenName();

}


</syntaxhighlight>

هذه الواجهة بسيطة. يجب أن ترجع الدالة getAuthIdentifierName اسم حقل "المفتاح الأساسي" للمستخدم ويجب أن ترجع الدالةgetAuthIdentifier "المفتاح الأساسي" للمستخدم. في خلفية MySQL، مرة أخرى، سيكون هذا المفتاح الأساسي تزايد تلقائي. يجب أن تقوم getAuthPassword بإرجاع كلمة المرور المجزئة الخاصة بالمستخدم. تسمح هذه الواجهة لنظام الاستيثاق بالعمل مع أي صنف للمستخدم، بغض النظر عن أي ORM أو طبقة تخزين مجرة، تستخدمها. افتراضياً، يتضمن Laravel صنف مستخدم في مجلد التطبيق الذي يقوم بتنفيذ هذه الواجهة، لذا يمكنك استشارة هذا الصنف للحصول على مثال للتنفيذ.

أحداث

يثير Laravel مجموعة متنوعة من الأحداث أثناء عملية الاستيثاق. يمكنك إرفاق المستمعين بهذه الأحداث في EventServiceProvider :<syntaxhighlight lang="php">
/**

* The event listener mappings for the application.

*

* @var array

*/

protected $listen = [

   'Illuminate\Auth\Events\Registered' => [

       'App\Listeners\LogRegisteredUser',

   ],

   'Illuminate\Auth\Events\Attempting' => [

       'App\Listeners\LogAuthenticationAttempt',

   ],

   'Illuminate\Auth\Events\Authenticated' => [

       'App\Listeners\LogAuthenticated',

   ],

   'Illuminate\Auth\Events\Login' => [

       'App\Listeners\LogSuccessfulLogin',

   ],

   'Illuminate\Auth\Events\Failed' => [

       'App\Listeners\LogFailedLogin',

   ],

   'Illuminate\Auth\Events\Logout' => [

       'App\Listeners\LogSuccessfulLogout',

   ],

   'Illuminate\Auth\Events\Lockout' => [

       'App\Listeners\LogLockout',

   ],

   'Illuminate\Auth\Events\PasswordReset' => [

       'App\Listeners\LogPasswordReset',

   ],

];


</syntaxhighlight>

== مصادر ==
* [https://laravel.com/docs/5.6/authentication صفحة Authentification في توثيق Laravel الرسمي.]
[[تصنيف:Laravel]]
[[تصنيف:Laravel Security]]