آموزش پکیج نویسی در Laravel

پکیج نویسی (package development) در Laravel

1. مقدمه
2. service provider ها
3. Routing (آدرس دهی)
4. منابع (resource ها)
   • view ها
   • translation (فایل های ترجمه)
   • فایل تنظیمات (config)
5. منابع و asset های public
6. انتشار file group ها (گروهی از منابع و asset ها)

مقدمه

پکیج ها روش اصلی و اولین وسیله برای افزودن قابلیت ها و امکانات جدید به Laravel محسوب می شوند. پکیج می تواند هر چیزی از جمله یک روش بهینه برای کار با تاریخ ها همچون Carbon و یا یک فریم ورک کامل تست گیری BDD (توسعه ی رفتار محور) مانند Behat باشد.
البته پکیج ها انواع مختلف دارند. برخی از پکیج ها مستقل (stand-alone) هستند، بدین معنی که با هر چارچوب نرم افزاری سازگار بوده و کار می کنند. Behat و Carbon هر دو نمونه هایی از این دست پکیج ها هستند. برای استفاده از این پکیج ها در لاراول کافی است آن ها را از فایلcomposer.json خود درخواست کنید.
در طرف دیگر، پکیج هایی هستند که تنها ویژه ی کار با Laravel طراحی و ارائه می شوند. این پکیج ها دارای route ها، controller ها، view ها و تنظیماتی (config) هایی هستند که تنها برای افزایش کارایی اپلیکیشن لاراول تعبیه شده اند. این راهنمای آموزشی به شرح توسعه ی پکیج هایی که ویژه ی لاراول عرضه می شوند می پردازد.

Service provider ها

service provider ها در واقع پل ارتباطی بین اپلیکیشن Laravel و پکیج مورد نظر می باشند. service provider مسئولیت binding درservice container لاراول را بر عهده داشته و نیز به Laravel اعلان می کند منابع پیکج ها همچون view ها و فایل های تنظیمات، بومی سازی و چند زبانه کردن (localization) را در کجا بارگزاری کند.
service provider از کلاس Illuminate\Support\ServiceProvider ارث بری کرده و در کل دو متد register و boot را فراهم می کند. کلاس پایه ی service provider در پکیج Composer illuminate/support قرار دارد. شما بایستی آن را به dependency های پکیج خود اضافه نمایید.

Routing (آدرس دهی)

به منظور تعریف route های جدید برای پکیج خود، کافی است فایل routes را با استفاده از دستور require در داخل بدنه ی متد boot (از service provider پکیج خود) فراخوانی (اضافه) کنید. در داخل فایل های routes، می توانید با استفاده از فاساد Route تمامی route ها را همان طور که در یک اپلیکیشن متعارف لاراول register می کنید، به راحتی ثبت نمایید.

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot()
{
   if (! $this->app->routesAreCached()) {
       require __DIR__.'/../../routes.php';
   }
}

منابع (resource ها)

viewها

به منظور ثبت view های پکیج مورد نظر در Laravel، ابتدا می بایست به لاراول اعلان کنید فایل های view در چه مسیری قرار دارد و باید آن ها را از کجا بارگذاری کند. این کار را می توان با فراخوانی متد loadViewFrom انجام داد. این متد دو آرگومان ورودی دریافت می کند: مسیری قالب هایview و دیگری اسم پکیج. به عنوان مثال، اگر اسم پکیج courier باشد بایستی کد زیر را به متد boot سرویس پروایدر اضافه نمایید:

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot()
{
   $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');
}

view های پکیج را می توان با بهره گیری از عملگر دو نقطه پشت سرم package::view ارجاع داده و به آن ها دسترسی داشت. بنابراین برای بارگذاری ویو admin از پکیج courier، کد را به صورت زیر تنظیم می کنیم:

Route::get('admin', function () {
   return view('courier::admin');
});

بازنویسی view های پکیج

هنگامی که متد loadViewsFrom را بکار می برید، لاراول دو مکان مجزا برای view های شما در نظر می گیرد: یکی در پوشه یresources/views/ven اپلیکیشن و دیگری در دایرکتوری که توسط خود شما تعیین می شود. با توجه به مثال courier، زمانی که یک viewاز پکیج را درخواست می کنید، لاراول ابتدا بررسی می کند آیا یک نسخه ی سفارشی از view مورد نظر توسط توسعه دهنده درresources/views/vendor/courier ارائه شده یا خیر. در صورتی که view سفارشی نشده باشد، لاراول دایرکتوری view ای که شما فراهم کردید را طی فراخوانی متد loadViewsFrom جستجو و مکان یابی می کند. این قابلیت به کاربران اجازه می دهد تا به راحتی view های پکیج شما را تنظیم / بازنویسی (override) کنند.

انتشار view ها

اگر می خواهید فایل های view شما برای انتشار، در دایرکتوریresources/views/vendor در دسترس قرار گیرد، لازم است متد publish ازservice provider را فراخوانی نمایید. این متد آرایه ای از مسیرهای view و مکان هایی که در آن publish می شوند را به عنوان آرگومان می پذیرد.

/**
 * Perform post-registration booting of services.
 *
 * @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 لاراول را اجرا می کنند، view های پکیج مورد نظر همگی در مکان تعیین شده جایگذاری می شوند.

translation (فایل های ترجمه)

چنانچه پکیج ای که برای لاراول نوشته اید حاوی فایل های translation نیز می باشد، آنگاه لازم است به واسطه ی متد loadTranslationsFromبه لاراول اعلان کنید فایل های نام برده را از کجا بارگذاری کند. برای مثال اگر پکیج مورد نظر courier نام گذاری شده، در آن صورت می بایست کد زیر را به متد boot از service provider اضافه نمایید:

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot()
{
   $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');
}

برای معرفی و ارجاع به فایل های translation کافی است از عملگر "::" بدین صورت: package::file.line استفاده کنید. بنابراین برای بارگذاری رشته ی welcome از فایل messages پکیج courier به صورت زیر اقدام می کنیم:

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

انتشار فایل های translation

اگر می خواهید فایل های translation را در دایرکتوری resources/lang/vendor منتشر کنید، می بایست متد publishes از service provider را صدا بزنید. این متد آرایه ای از مسیرهای پکیج و مکان هایی که در آن publish می شوند را به عنوان آرگومان می پذیرد. به عنوان مثال برای منتشر کردن فایل های translation پکیج نمونه ی خود (courier)، به ترتیب زیر عمل می کنیم:

/**
 * Perform post-registration booting of services.
 *
 * @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 را اجرا می کنند تمامی فایل های ترجمه ی پکیج مورد نظر در مکان مشخص شده publish می شوند.

فایل تنظیمات

به طور معمول فایل تنظیمات پکیج در دایرکتوری config خود اپلیکیشن publish می شود. این امر به کاربران اجازه می دهد تا به آسانی گزینه های پیشفرض config را بازنویسی کنند. برای انتشار فایل تنظیمات نیز کافی است متد publishes را در تابع boot از service provider صدا بزنید:

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot()
{
   $this->publishes([
       __DIR__.'/path/to/config/courier.php' => config_path('courier.php'),
   ]);
}

زمانی که کاربر پکیج، دستور آرتیزان vendor:publish لاراول را اجرا می کند، فایل مورد نظر در مکان مشخص شده جایگذاری می شود. پس از این که فایل منتشر شد، می توان مثل هر فایل تنظیمات دیگری به آن دسترسی داشت:

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

فایل تنظیمات پیش فرض پکیج

همچنین می توان فایل تنظیمات پکیج خود را با فایل تنظیمات اپلیکیشن ترکیب کرد. این قابلیت به کاربران پکیج شما امکان می دهد تا تنها آپشن هایی را که می خواهند بازنویسی نمایند داخل نسخه ی کپی فایل تنظیمات publish شده، لحاظ کنند. برای ادغام فایل های پیکربندی، کافی است متدmergeConfigFrom را داخل متد register از service provider بکار ببرید:

/**
 * Register bindings in the container.
 *
 * @return void
 */
public function register()
{
   $this->mergeConfigFrom(
       __DIR__.'/path/to/config/courier.php', 'courier'
   );
}

منابع و asset های public

پکیج های شما می توانند asset هایی همچون اسکریپت های JavaScript، کدهای CSS و فایل های تصویری در خود داشته باشند. به منظور بارگذاری (publish) این asset ها در دایرکتوری public اپلیکیشن خود، متد publishes را استفاده نمایید. در این مثال یک تگ public نیز اضافه می کنیم که توسط آن می توان گروه هایی از asset های مربوطه را publish کرد:

اکنون اگر کاربران پکیج شما دستور vendor:publish را اجرا کنند، asset های شما در مکان مشخص شده جایگذاری می شوند. از آنجایی که باید با هر بار بروز رسانی پکیج، asset ها را بازنویسی کنید، استفاده از پارامتر --force الزامی می باشد:

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

اگر می خواهید مطمئن شوید که asset های public پکیج شما همیشه بروز هستند، در آن صورت می توانید این دستور را به لیست post-update-cmd در فایل composer.json اضافه نمایید.

انتشار file group ها (گروهی از منابع و asset ها)

ممکن است لازم باشد asset ها و منابع خود را در قالب ها گروه هایی به صورت جداگانه publish نمایید. به عنوان مثال ممکن است انتظار داشته باشید که کاربران بتوانند فایل های تنظیمات پکیج را به صورت جداگانه و بدون اینکه لازم باشد asset ها را نیز همزمان publish کنند، منتشر نمایند. برای نیل به این هدف کافی است در زمان فراخوانی متد publishes، آن ها را تگ گذاری نمایید. در مثال زیر دو گروه برای publish در متدboot تعریف می کنیم:

/**
 * Perform post-registration booting of services.
 *
 * @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');
}

حال کاربران پکیج شما می توانند این asset ها و منابع گروهی را با ارجاع و ذکر اسم تگ آن ها به هنگام اجرای دستور آرتیزان vendor:publishبه صورت مجزا publish و بارگذاری کنند:

                    php artisan vendor:publish --provider="Vendor\Providers\PackageServiceProvider" --tag="config"