Laravel/contracts

مقدمة

عقود Laravel هي مجموعة من الواجهات (interfaces) التي تعرِّف الخدمات المركزية التي يوفرها إطار العمل. على سبيل المثال، يعرِّف العقد Illuminate\Contracts\Queue\Queue  الدوال اللازمة لصف الأعمال في الطوابير، بينما يعرِّف عقد Illuminate\Contracts\Mail \Mailer الدوال اللازمة لإرسال رسائل البريد الإلكتروني. لكل عقد تعريف استخدام (implementation) يوفره إطار العمل. على سبيل المثال، يوفِّر Laravel تعريف استخدام للطابور لعدة أنواع من المشغلات (drivers) كما يوفِّر تعريف استخدام للمُرسِل مشغل بواسطة SwiftMailer. توجد كل عقود Laravel  في مستودعات في  GitHub. هذا يوفر نقطة مرجعية سريعة لكل العقود المتوافرة كما يوفر حزمة (package) واحدة منفصلة يمكن لمطوري الحِزم إستخدامها.

مقارنة العقود والواجهات الساكنة (Facades)

توفر واجهات Laravel الساكنة والدوال البانية المساعدة (helper functions) طريقة بسيطة لاستخدام خدمات Laravel بدون الحاجة للتلميح على النوع (type-hint) أو استبيان العقود من حاوي الخدمات. في أغلب الحالات لكل واجهةٍ ساكنةٍ عقدٌ يعادلها.

عكس الواجهات الساكنة التي لا تتطلب أن منك تضمينها في الدالة البانية لصنفك، تسمح لك العقود بتعريف الاعتماديات المذكورة بوضوح (explicit dependencies) لأصنافك. يفضل بعض المطورين تعريف الاعتماديات بوضوح بهذه الطريقة وبالتالي استخدام العقود، بينما البعض الآخر يفضل سهولة أو راحة الواجهات المؤقتة.

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

متى تُستَخدم العقود؟

كما ذكرنا سابقًا، يعتمد الاختيار بين الواجهات والعقود على الذوق الشخصي وذوق فريق التطوير. كلاهما يُمكِّن من صناعة تطبيقات Laravel قوية ومختبرة بشكل جيد. ما دمت تبقي مسؤوليات أصنافك مركزة، لن تلاحظ تطبيقيًا إلا فروقًا قليلةً جدًا بين العقود والواجهات. مع ذلك قد تسأل عدة أسئلة حول العقود. على سبيل المثال، لم نستخدم الواجهات أصلًا؟ أليس استخدام الواجهات أكثر تعقيدًا؟ فلنلخص أسباب استخدام الواجهات للسببين التاليين: الارتباط الرخو (loose coupling) والبساطة.

الاقتران الرخو

فلنراجع أولًا بعض التعليمات البرمجية ضيقة الارتباط (tightly coupled) بتعريف استخدام ذاكرة تخزين مؤقتة (cache implementation). انظر في ما يلي:

<?php

namespace App\Orders;

class Repository
{
    /**
     * نسخة الذاكرة المؤقتة 
     */
    protected $cache;

    /**
     * أنشئ نسخة مستودع جديدة
     *
     * @param  \SomePackage\Cache\Memcached  $cache
     * @return void
     */
    public function __construct(\SomePackage\Cache\Memcached $cache)
    {
        $this->cache = $cache;
    }

    /**
     * Order by ID جلب 
     *
     * @param  int  $id
     * @return Order
     */
    public function find($id)
    {
        if ($this->cache->has($id))    {
           //
        }
    }
}

التعليمات البرمجية في هذا الصنف ضيقة الارتباط بتعريف استخدام ذاكرة تخزين مؤقتة (cache implementation). هي ضيقة الاقتران لأننا نعتمد على صنف ذاكرة مؤقتة ملموسة من بائع حِزم (package vendor). إن تغير API تلك الحِزمة علينا تغيير تعليماتنا البرمجية.

نقع في نفس الإشكالية إن رغبنا في تغيير التقنية المستخدمة ضمنيًا للذاكرة المؤقتة (Memcached) بأخرى (Redis)، سنضطر مجددا لتعديل مستودعنا. لا يجب على المستودع أن يعرف الكثير عن مُوفِّر البيانات أو كيفية توفيرها.

بإمكاننا تحسين تعليماتنا البرمجية بالاعتماد على واجهة (interface) بسيطة محايدة البائع (vendor agnostic) بدل هذه المقاربة:

<?php

namespace App\Orders;

use Illuminate\Contracts\Cache\Repository as Cache;

class Repository
{
    /**
     * نسخة ذاكرة التخزين المؤقتة
     */
    protected $cache;

    /**
     * أنشئ نسخة مستودع جديدة
     *
     * @param  Cache  $cache
     * @return void
     */
    public function __construct(Cache $cache)
    {
        $this->cache = $cache;
    }
}

الآن لا تقترن التعليمات البرمجية بأي بائع محدد أو حتى  Laravel. يمكنك الآن كتابة نسخة بديلة عن أي عقد تريده، بما أن حِزم العقود لا تحتوي على أي اعتماديات (dependencies) أو أي تعريف استخدام، مما يسمح لك باستبدال تعريف استخدام ذاكرة التخزين مؤقتة (cache implementation) بدون تعديل أي من تعليماتك المستهلكة لذاكرة التخزين المؤقتة.

البساطة

لمّا تُعرَّف كل خدمات Laravel بدقة داخل واجهات بسيطة يسهل تحديد الوظيفة التي توفرها الخدمة بشكل كبير. تصلح العقود كتوثيقات موجزة لخاصيات إطار العمل.

كيفية استخدام العقود

إذا كيف تتحصل على تعريف استخدام (implementation) عقد؟ المسألة بسيطة جدًا.

تُستَبْيَن العديد من أنواع الأصناف في Laravel عبر حاوي الخدمات بما فيها وحدات التحكم، ومنصتات الأحداث، والبرمجيات الوسيطة، والأعمال المصفوفة في الطوابير، وحتى تعابير المسارات المغلقة (route closure). إذا للحصول على تعريف استخدام لعقد يمكنك مجرد التلميح على نوع (type-hint) الواجهة في الدالة البانية (constructor) للصنف المُستَبْين.

لنلق نظرة على منصت الأحداث التالي كمثال:

<?php

namespace App\Listeners;

use App\User;
use App\Events\OrderWasPlaced;
use Illuminate\Contracts\Redis\Database;

class CacheOrderInformation
{
    /**
     * Redis تعريف إستخدام قاعدة البيانات
     */
    protected $redis;

    /**
     * أنشئ نسخة معالج أحداث جديدة
     *
     * @param  Database  $redis
     * @return void
     */
    public function __construct(Database $redis)
    {
        $this->redis = $redis;
    }

    /**
     * عالج الحدث.
     *
     * @param  OrderWasPlaced  $event
     * @return void
     */
    public function handle(OrderWasPlaced $event)
    {
       //
    }
}

سيقرأ حاوي الخدمات التلميحات على النوع عند استبيان منصت الأحداث (event listener) ثم يضيف القيمة المناسبة. للمزيد من المعلومات حول تسجيل الأشياء في حاوي الخدمات، أنظر توثيقه.

مرجع العقد

يُوفِّر هذا الجدول مرجعًا سريعًا لكل عقود Laravel وواجهاتها الساكنة المعادلة:

العقود	الواجهة الساكنة المرجعية
Illuminate\Contracts\Auth\Access\Authorizable
Illuminate\Contracts\Auth\Access\Gate	Gate
Illuminate\Contracts\Auth\Authenticatable
Illuminate\Contracts\Auth\CanResetPassword
Illuminate\Contracts\Auth\Factory	Auth
Illuminate\Contracts\Auth\Guard	Auth::guard()
Illuminate\Contracts\Auth\PasswordBroker	Password::broker()
Illuminate\Contracts\Auth\PasswordBrokerFactory	Password
Illuminate\Contracts\Auth\StatefulGuard
Illuminate\Contracts\Auth\SupportsBasicAuth
Illuminate\Contracts\Auth\UserProvider
Illuminate\Contracts\Bus\Dispatcher	Bus
Illuminate\Contracts\Bus\QueueingDispatcher	Bus::dispatchToQueue()
Illuminate\Contracts\Broadcasting\Factory	Broadcast
Illuminate\Contracts\Broadcasting\Broadcaster	Broadcast::connection()
Illuminate\Contracts\Broadcasting\ShouldBroadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcastNow
Illuminate\Contracts\Cache\Factory	Cache
Illuminate\Contracts\Cache\Lock
Illuminate\Contracts\Cache\LockProvider
Illuminate\Contracts\Cache\Repository	Cache::driver()
Illuminate\Contracts\Cache\Store
Illuminate\Contracts\Config\Repository	Config
Illuminate\Contracts\Console\Application
Illuminate\Contracts\Console\Kernel	Artisan
Illuminate\Contracts\Container\Container	App
Illuminate\Contracts\Cookie\Factory	Cookie
Illuminate\Contracts\Database\ModelIdentifier
Illuminate\Contracts\Debug\ExceptionHandler
Illuminate\Contracts\Encryption\Encrypter	Crypt
Illuminate\Contracts\Events\Dispatcher	Event
Illuminate\Contracts\Filesystem\Cloud	Storage::cloud()
Illuminate\Contracts\Filesystem\Factory	Storage
Illuminate\Contracts\Filesystem\Filesystem	Storage::disk()
Illuminate\Contracts\Foundation\Application	App
Illuminate\Contracts\Hashing\Hasher	Hash
Illuminate\Contracts\Http\Kernel
Illuminate\Contracts\Mail\MailQueue	Mail::queue()
Illuminate\Contracts\Mail\Mailable
Illuminate\Contracts\Mail\Mailer	Mail
Illuminate\Contracts\Notifications\Dispatcher	Notification
Illuminate\Contracts\Notifications\Factory	Notification
Illuminate\Contracts\Pagination\LengthAwarePaginator
Illuminate\Contracts\Pagination\Paginator
Illuminate\Contracts\Pipeline\Hub
Illuminate\Contracts\Pipeline\Pipeline
Illuminate\Contracts\Queue\EntityResolver
Illuminate\Contracts\Queue\Factory	Queue
Illuminate\Contracts\Queue\Job
Illuminate\Contracts\Queue\Monitor	Queue
Illuminate\Contracts\Queue\Queue	Queue::connection()
Illuminate\Contracts\Queue\QueueableCollection
Illuminate\Contracts\Queue\QueueableEntity
Illuminate\Contracts\Queue\ShouldQueue
Illuminate\Contracts\Redis\Factory	Redis
Illuminate\Contracts\Routing\BindingRegistrar	Route
Illuminate\Contracts\Routing\Registrar	Route
Illuminate\Contracts\Routing\ResponseFactory	Response
Illuminate\Contracts\Routing\UrlGenerator	URL
Illuminate\Contracts\Routing\UrlRoutable
Illuminate\Contracts\Session\Session	Session::driver()
Illuminate\Contracts\Support\Arrayable
Illuminate\Contracts\Support\Htmlable
Illuminate\Contracts\Support\Jsonable
Illuminate\Contracts\Support\MessageBag
Illuminate\Contracts\Support\MessageProvider
Illuminate\Contracts\Support\Renderable
Illuminate\Contracts\Support\Responsable
Illuminate\Contracts\Translation\Loader
Illuminate\Contracts\Translation\Translator	Lang
Illuminate\Contracts\Validation\Factory	Validator
Illuminate\Contracts\Validation\ImplicitRule
Illuminate\Contracts\Validation\Rule
Illuminate\Contracts\Validation\ValidatesWhenResolved
Illuminate\Contracts\Validation\Validator	Validator::make()
Illuminate\Contracts\View\Engine
Illuminate\Contracts\View\Factory	View
Illuminate\Contracts\View\View	View::make()