Laravel/packages

مقدمة

الحزم هي الطريقة الأولى لإضافة وظائف ل Laravel. يمكن أن تكون الحزم أي شيء مثل طريقة للعمل مع التواريخ مثل Carbon أو إطار متكامل لاختبار قواعد البيانات مثل Behat.

طبعًا، يوجد أنواع مختلفة من الحزم. بعض الحزم مكتفية بذاتها أي أنها تعمل مع أي إطار PHP مثل Behat و Carbon. يمكن طلب أي من هذه الحزم عبر الملف composer.json.

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

ملحوظة حول الواجهات الساكنة

عند كتابة تطبيق Laravel، لا يوجد في العادة فرق بين استعمال العقود أو الواجهات الساكنة حيث يوفر كلاهما نسبة مساوية من القابلية للاختبار. لكن عند كتابة حزم، لن يكون للحزم في العادة القدرة على استعمال مساعدات الاختبار. إن أردت كتابة اختبارات للحزمة كما توجد في العادة داخل تطبيق Laravel، يمكنك استعمال الحزمة ORchestral Testbench.

اكتشاف الحزم

في ملف الضبط config/app.php، يعرف الخيار providers لائحة من مقدمي الخدمات التي يجب تحميلها من قبل Laravel. عندما يحمل أحدهم حزمتك، ستريد أن تضمن هذه اللائحة مقدمي خدماتك. بدل أن تطلب من المستخدم أن يضيف مقدمي خدماتك يدويًّا لللائحة، يمكنك تعريف المقدم في القسم extra من الملف composer.json في الحزمة. بالإضافة لمقدمي الخدمات، يمكنك أيضًا تسجيل أي واجهة ساكنة تريد:

"extra": {

   "laravel": {
       "providers": [
           "Barryvdh\\Debugbar\\ServiceProvider"
       ],

       "aliases": {
           "Debugbar": "Barryvdh\\Debugbar\\Facade"

       }
   }
},

بعد ضبط الحزمة للاكتشاف، سيسجل Laravel تلقائيًّا مقدّمي الخدمات و الواجهات الساكنة عند تثبيت الحزمة، مما يوفر تجربة تثبيت سلسة للمستخدم.

الانسحاب من اكتشاف الحزم

إن كنت مستخدم حزمة و أردت أن تعطل خاصية اكتشاف الحزم، يمكنك ذكر اسم الحزمة في القسم extra من الملف composer.json:

"extra": {

   "laravel": {
       "dont-discover": [
           "barryvdh/laravel-debugbar"
       ]
   }
},

يمكنك تعطيل الاكتشاف لكل الحزم باستعمال الرمز "*" في التعليمة dont-discover:

"extra": {

   "laravel": {
       "dont-discover": [
           "*"
       ]
   }
},

مقدّمو الخدمات

تعتبر مقدّمو الخدمات نقطة الربط بين الحزمة و Laravel. يكون مقدّم الخدمة مسؤولًا عن ربط الخدمة في حاوي الخدمات و إعلام Laravel أين يحمل الموارد مثل الواجهات و ملفات الضبط و التوطين.

يرث مقدّم الخدمات الصنف Illuminate\Support\ServiceProvider و يحتوي التابعين register و boot. يوجد الصنف الأساسي ServiceProvider في الحزمة illuminate/support، التي يجب أن تضيفها اعتماديّات الحزمة. لمعرفة المزيد حول هيكلة و هدف المقدّم، تفقد التوثيق.

الموارد

الضبط

في العادة، ستحتاج لنشر ملف ضبط الحزمة في دليل التطبيق config. ممّا سيسمح للمستخدم بإعادة تعريف خيارات الضبط الأساسية. للسماح لملفات الضبط بالنشر، ناد التابع publishes من التابع boot في مقدّم الخدمات:

/**
*تنفيذ خدمات ما بعد التسجيل
*
* @return void
*/

public function boot()
{
   $this->publishes([
      __DIR__.'/path/to/config/courier.php' => config_path('courier.php'),

   ]);
}

الآن عندما ينفذ المستخدم الأمر vendor: publish، سينُنسَخ الملف في مكان النشر المحدد. عند نشر الضبط، يمكن الوصول إلى محتواه كأي ملف ضبط آخر:

$value = config('courier.option');

تنبيه: يجب عدم تعريف Closures في ملفات ضبطك لكونها غير قابلة للسلسلة بطريقة صحيحة عند تنفيذ المستخدمين لأمر Artisan config:cache.

حزمة الضبط الافتراضيّة

يمكنك دمج ضبط حزمتك مع ملف ضبط التطبيق المنشور. سيسمح هذا للمستخدم بتعريف الخيارات التي يريد فقط. لدمج الضبط، استعمل التابع MergeConfigFrom في التابع register من مقدّم الخدمة:

/**
* تسجيل الربد في الحاوي
*
* @return void
*/

public function register()
{
   $this->mergeConfigFrom(
       __DIR__.'/path/to/config/courier.php', 'courier'
   );
}

تنبيه: تدمج هذه الطريقة المستوى الأول فقط من مصفوفة الضبط. إن عرف المستخدم مصفوفة ضبط متعددة الأبعاد، لن تدمج الخيارات الناقصة.

المسارات

إن احتوت الحزمة على مسارات، يمكنك تحميلها باستعمال التابع loadRoutesFrom. سيحدد التابع تلقائيًّا إن كانت المسارات مخزنة ولن يحملها في تلك الحالة:

/**

*تنفيذ خدمات ما بعد التسجيل.

*

* @return void

*/

public function boot()

{

   $this->loadRoutesFrom(__DIR__.'/routes.php');

}

التهجيرات

إن كانت الحزمة تحتوي تهجيرات قواعد بيانات، يمكنك استعمال التابع loadMigrationsFrom لإعلام Laravel بكيفية تحميلها. يقبل التابع loadMigrationsFrom المسار للحزمة كمعامل وحيد:

/**

* تنفيذ خدمات ما بعد التسجيل.

*

* @return void

*/

public function boot()

{

   $this->loadMigrationsFrom(__DIR__.'/path/to/migrations');

}

بعد تسجيل التهجيرات في التطبيق، يُنفذ الأمر php artisan migrate تلقائيًّا و لا تحتاج لنقلهم لدليل التهجير الرئيسي database/migrations.

الترجمة

إذا احتوى التطبيق على ملفات ترجمة، يمكنك استعمال التابع loadTranslationsFrom لإعلام Laravel بكيفية تحميلها. مثلًا، إذا كان اسم الحزمة courier، يجب عليك إضافة التالي للتابع boot من مقدّم الخدمة:

/**

*  تنفيذ خدمات ما بعد التسجيل.

*

* @return void

*/

public function boot()

{

   $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');

}

تُذكر ترجمة الحزمة باستعمال اتفاقية التسمية package::file.line. لذا يمكنك تحميل السطر welcome من الملف messages من الحزمة courier كما يلي:

echo trans('courier::messages.welcome');

نشر الترجمة

إذا أردت نشر ترجمة الحزمة في الدليل resources/lang/vendor، يمكنك استعمال التابع publishes من مقدّم الخدمة. يقبل التابع publishes مصفوفة من مسارات الحزمة والأماكن التي يراد النشر إليها. مثلا، لنشر ملفات ترجمة الحزمة courier، يمكنك القيام بالتالي

/**

*  تنفيذ خدمات ما بعد التسجيل.

* @return void

*/

public function boot()

{

   $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');

   $this->publishes([

       __DIR__.'/path/to/translations' => resource_path('lang/vendor/courier'),

   ]);

}

الآن عند استخدام الحزمة، نفّذ الأمر vendor:publish وستُنشر ملفات الترجمة في المكان المحدد.

الواجهات

لتسجيل واجهات الحزمة مع Laravel، ستحتاج لإخبار Laravel أين توجد الواجهات. يمكنك القيام بهذا بمساعدة التابع loadViewsFrom. يقبل التابع معاملين: المسار لقالب الواجهات و اسم الحزمة. مثلا، إن كان اسم الحزمة courier، ستضيف التالي للتابع boot من مقدّم الخدمة:

/**

*  تنفيذ خدمات ما بعد التسجيل.

*

* @return void

*/

public function boot()

{

   $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');

}

تُذكر واجهات الحزمة باستخدام اتفاقية التسمية package::view. لذا بعد تسجيل مسار الواجهات في مقدّم الخدمة، يمكنك تحميل الواجهة admin من الحزمة courier كما يلي:

Route::get('admin', function () {

   return view('courier::admin');

});

إعادة تعريف واجهات الحزمة

عندما تستعمل التابع loadViewsFrom، يسجل Laravel فعليًّا مكانين لواجهاتك: الدليل resources/views/vendor و الدليل الذي حدّدته. لذا، باستعمال المثال courier، سيتثبت Laravel أولًا من إذا كان المبرمج وفّر نسخة مخصصة من الواجهات في الدليل resources/views/vendor/courier. ثمّ إذا لم يجد النسخة المخصصة، يتفقد Laravel مسار الواجهات الذي حددته في نداء loadViewsFrom. يسهّل هذا على المستخدم تخصيص/ إعادة تعريف واجهات الحزمة.

نشر الواجهات

إذا أردت توفير الواجهات للنشر في الدليل resources/views/vendor، يمكنك استخدام التابع publishes. سيقبل التابع مصفوفة من مسارات الواجهات بالإضافة للمكان المراد النشر إليه:

/**

* تنفيذ خدمات ما بعد التسجيل.

*

* @return void

*/

public function boot()

{

   $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');

   $this->publishes([

       __DIR__.'/path/to/views' => resource_path('views/vendor/courier'),

   ]);

}

الآن عندما ينفذ المستخدم الأمر vendor:publish، ستُنسخ واجهات الحزمة في المكان المحدد.

الأوامر

لتسجيل أوامر artisan الحزمة مع Laravel، يمكنك استعمال التابع command. يقبل هذا التابع مصفوفة من أسماء أصناف الأوامر. بعد تسجيل الأوامر، يمكنك تنفيذها باستعمال واجهة خط الأوامر artisan cli:

/**

* إطلاق خدمات التطبيق.

*

* @return void

*/

public function boot()

{

   if ($this->app->runningInConsole()) {

       $this->commands([

           FooCommand::class,

           BarCommand::class,

       ]);

   }

}

الأصول العامة

قد تحتوي الحزمة على أصول مثل javascript, css أو صور. لنشر هذه الأصول للدليل public من التطبيق، استخدم تابع مقدّم الخدمات publishes. في هذا المثال، سنضيف أيضا وسم مجموعة الأصول public التي يمكن استخدامها لنشر مجموعات من الأصول المتقاربة:

/**

*  تنفيذ خدمات ما بعد التسجيل.

*

* @return void

*/

public function boot()

{

   $this->publishes([

       __DIR__.'/path/to/assets' => public_path('vendor/courier'),

   ], 'public');

}

الآن، عندما ينفذ مستخدم الحزمة الأمر vendor:publish، ستُنسخ الأصول لمكان النشر المحدد. بما أنك ستحتاج لإعادة تعريف الأصول كلما حيّنت الحزمة، يمكنك استخدام الخيار force--:

hp artisan vendor:publish --tag=public --force

نشر مجموعات الملفات

قد تريد نشر مجموعات من الموارد والأصول كل على حدة. على سبيل المثال، قد تريد السماح للمستخدم بنشر ضبط الحزمة دون إرغامه على نشر الأصول معها. يمكنك القيام بذلك بإضافة وسوم عند نداء التابع publishes من مزود الخدمة. لنستخدم مثلًا الوسوم لتحديد مجموعتي نشر في التابع boot من مقدّم الخدمات:

/**

* تنفيذ خدمات ما بعد التسجيل.

*

* @return void

*/

public function boot()

{

   $this->publishes([

       __DIR__.'/../config/package.php' => config_path('package.php')

   ], 'config');

   $this->publishes([

       __DIR__.'/../database/migrations/' => database_path('migrations')

   ], 'migrations');

}

الآن يمكنك نشر إحدى المجموعتين بذكر  وسومها عند تنفيذ الأمر vendor:publish:

php artisan vendor:publish --tag=config

مصادر

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