توسعه بسته

• معرفی
  • نکته ای در مورد نماها
• کشف بسته
• ارائه دهندگان خدمات
• منابع
  • پیکربندی
  • مهاجرت ها
  • مسیرها
  • ترجمه ها
  • بازدیدها
  • مشاهده کامپوننت ها
  • "درباره" فرماندهی صنعتگر
• دستورات
• دارایی های عمومی
• انتشار گروه های فایل

معرفی

بسته ها راه اصلی اضافه کردن قابلیت به لاراول هستند. بسته‌ها ممکن است هر چیزی باشند، از روشی عالی برای کار با تاریخ‌هایی مانند کربن یا بسته‌ای که به شما امکان می‌دهد فایل‌ها را با مدل‌های Eloquent مانند Spatie's Laravel Media Library مرتبط کنید .

بسته بندی انواع مختلفی دارد. برخی از بسته ها مستقل هستند، به این معنی که با هر چارچوب PHP کار می کنند. Carbon و PHPUnit نمونه هایی از بسته های مستقل هستند. هر یک از این بسته ها می تواند با لاراول استفاده شود و آنها را در composer.json فایل شما نیاز دارد.

از سوی دیگر، بسته های دیگر به طور خاص برای استفاده با لاراول در نظر گرفته شده اند. این بسته‌ها ممکن است مسیرها، کنترل‌کننده‌ها، نماها و پیکربندی‌هایی داشته باشند که به‌طور خاص برای بهبود برنامه لاراول در نظر گرفته شده‌اند. این راهنما در درجه اول توسعه بسته هایی را پوشش می دهد که مخصوص لاراول هستند.

نکته ای در مورد نماها

هنگام نوشتن یک برنامه لاراول، معمولاً مهم نیست که از قراردادها یا نماها استفاده می کنید، زیرا هر دو اساساً سطح تست پذیری یکسانی را ارائه می دهند. با این حال، هنگام نوشتن بسته‌ها، بسته شما معمولاً به تمام کمک‌های تست لاراول دسترسی نخواهد داشت. اگر می‌خواهید بتوانید آزمایش‌های بسته خود را طوری بنویسید که گویی بسته در یک برنامه معمولی لاراول نصب شده است، می‌توانید از بسته Orchestral Testbench استفاده کنید .

کشف بسته

config/app.php در فایل پیکربندی برنامه لاراول ، این providers گزینه فهرستی از ارائه دهندگان خدماتی را که باید توسط لاراول بارگذاری شوند، تعریف می کند. هنگامی که شخصی بسته شما را نصب می کند، معمولاً می خواهید ارائه دهنده خدمات شما در این لیست قرار گیرد. به جای اینکه از کاربران بخواهید به صورت دستی ارائه دهنده خدمات خود را به لیست اضافه کنند، می توانید ارائه دهنده را در extra بخش فایل بسته خود تعریف کنید composer.json . علاوه بر ارائه دهندگان خدمات، می توانید نماهایی را که می خواهید ثبت شوند نیز فهرست کنید:

"extra": {
    "laravel": {
        "providers": [
            "Barryvdh\\Debugbar\\ServiceProvider"
        ],
        "aliases": {
            "Debugbar": "Barryvdh\\Debugbar\\Facade"
        }
    }
},

هنگامی که بسته شما برای کشف پیکربندی شد، لاراول به طور خودکار ارائه دهندگان خدمات و نماهای خود را هنگام نصب ثبت می کند و تجربه نصب راحت را برای کاربران بسته شما ایجاد می کند.

انصراف از کشف بسته

اگر شما مصرف‌کننده یک بسته هستید و می‌خواهید کشف بسته را برای یک بسته غیرفعال کنید، می‌توانید نام بسته را در بخش فایل extra برنامه خود ذکر کنید composer.json :

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

* شما می توانید با استفاده از کاراکتر داخل دستورالعمل برنامه خود، کشف بسته را برای همه بسته ها غیرفعال کنید dont-discover :

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

ارائه دهندگان خدمات

ارائه دهندگان خدمات نقطه اتصال بسته شما و لاراول هستند. یک ارائه‌دهنده خدمات مسئول اتصال چیزها به کانتینر سرویس لاراول و اطلاع دادن به لاراول برای بارگیری منابع بسته مانند نماها، پیکربندی و فایل‌های محلی‌سازی است.

یک ارائه دهنده سرویس Illuminate\Support\ServiceProvider کلاس را گسترش می دهد و شامل دو روش است: register و boot . کلاس پایه ServiceProvider در بسته Composer قرار دارد illuminate/support که باید آن را به وابستگی های بسته خود اضافه کنید. برای کسب اطلاعات بیشتر در مورد ساختار و هدف ارائه دهندگان خدمات، مستندات آنها را بررسی کنید .

منابع

پیکربندی

به طور معمول، شما باید فایل پیکربندی بسته خود را در config دایرکتوری برنامه منتشر کنید. این به کاربران بسته شما اجازه می دهد تا به راحتی گزینه های پیکربندی پیش فرض شما را نادیده بگیرند. برای اینکه اجازه دهید فایل های پیکربندی شما منتشر شوند، publishes روش را از boot روش ارائه دهنده خدمات خود فراخوانی کنید:

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ]);
}

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

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

شما نباید در فایل های پیکربندی خود بسته ها را تعریف کنید. هنگامی که کاربران دستور Artisan را اجرا می کنند، نمی توان آنها را به درستی سریال کرد config:cache .

پیکربندی بسته پیش‌فرض

همچنین می توانید فایل پیکربندی بسته خود را با نسخه منتشر شده برنامه ادغام کنید. این به کاربران شما این امکان را می‌دهد که فقط گزینه‌هایی را که واقعاً می‌خواهند در نسخه منتشر شده فایل پیکربندی لغو کنند، تعریف کنند. برای ادغام مقادیر فایل پیکربندی، از mergeConfigFrom روش موجود در روش ارائه دهنده خدمات خود استفاده کنید register .

این mergeConfigFrom متد مسیر فایل پیکربندی بسته شما را به عنوان اولین آرگومان خود و نام کپی برنامه از فایل پیکربندی را به عنوان آرگومان دوم می پذیرد:

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

این روش فقط سطح اول آرایه پیکربندی را ادغام می کند. اگر کاربران شما تا حدی یک آرایه پیکربندی چند بعدی را تعریف کنند، گزینه های از دست رفته ادغام نمی شوند.

مسیرها

اگر بسته شما حاوی مسیرهایی است، می توانید آنها را با استفاده از loadRoutesFrom روش بارگیری کنید. این روش به طور خودکار تعیین می کند که آیا مسیرهای برنامه در حافظه پنهان هستند یا خیر و اگر مسیرها قبلاً کش شده باشند، فایل مسیرهای شما را بارگیری نمی کند:

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
}

مهاجرت ها

اگر بسته شما حاوی مهاجرت های پایگاه داده است ، می توانید از loadMigrationsFrom روشی برای اطلاع رسانی به لاراول برای بارگذاری آنها استفاده کنید. این loadMigrationsFrom متد مسیر مهاجرت های بسته شما را به عنوان تنها آرگومان خود می پذیرد:

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
}

هنگامی که مهاجرت های بسته شما ثبت شد، هنگام php artisan migrate اجرای دستور به طور خودکار اجرا می شوند. لازم نیست آنها را به database/migrations فهرست برنامه صادر کنید.

ترجمه ها

اگر بسته شما حاوی فایل های ترجمه است ، می توانید از loadTranslationsFrom روشی برای اطلاع رسانی به لاراول برای بارگذاری آنها استفاده کنید. به عنوان مثال، اگر بسته شما نام دارد courier ، باید موارد زیر را به boot روش ارائه دهنده خدمات خود اضافه کنید:

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');
}

ترجمه های بسته با استفاده از package::file.line قرارداد نحوی ارجاع می شوند. بنابراین، می‌توانید خط courier بسته welcome را از messages فایل به صورت زیر بارگیری کنید:

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

انتشار ترجمه ها

اگر می خواهید ترجمه های بسته خود را در فهرست برنامه منتشر کنید lang/vendor ، می توانید از publishes روش ارائه دهنده خدمات استفاده کنید. این publishes روش آرایه ای از مسیرهای بسته و مکان های انتشار دلخواه آنها را می پذیرد. به عنوان مثال، برای انتشار فایل های ترجمه برای courier بسته، می توانید کارهای زیر را انجام دهید:

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');
 
    $this->publishes([
        __DIR__.'/../lang' => $this->app->langPath('vendor/courier'),
    ]);
}

اکنون زمانی که کاربران بسته شما دستور Artisan لاراول را اجرا می کنند vendor:publish ، ترجمه های بسته شما در محل انتشار مشخص شده منتشر می شود.

بازدیدها

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

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
}

نماهای بسته با استفاده از package::view قرارداد نحوی ارجاع داده می شوند. بنابراین، هنگامی که مسیر مشاهده شما در یک ارائه دهنده خدمات ثبت شد، می توانید نمای dashboard بسته را courier مانند این بارگذاری کنید:

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

نادیده گرفتن بازدیدهای بسته

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

انتشار نماها

اگر می خواهید نماهای خود را برای انتشار در resources/views/vendor فهرست برنامه در دسترس قرار دهید، می توانید از publishes روش ارائه دهنده خدمات استفاده کنید. این publishes روش آرایه ای از مسیرهای مشاهده بسته و مکان های انتشار دلخواه آنها را می پذیرد:

/**
 * Bootstrap the package services.
 *
 * @return void
 */
public function boot()
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
 
    $this->publishes([
        __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
    ]);
}

اکنون وقتی کاربران بسته شما دستور Artisan لاراول را اجرا می کنند vendor:publish ، نماهای بسته شما در محل انتشار مشخص شده کپی می شود.

مشاهده کامپوننت ها

اگر در حال ساخت بسته‌ای هستید که از اجزای Blade استفاده می‌کند یا کامپوننت‌ها را در دایرکتوری‌های غیر متعارف قرار می‌دهد، باید کلاس کامپوننت و نام مستعار تگ HTML آن را به‌طور دستی ثبت کنید تا لاراول بداند کامپوننت را کجا پیدا کند. شما معمولاً باید اجزای خود را در boot روش ارائه دهنده خدمات بسته خود ثبت کنید:

use Illuminate\Support\Facades\Blade;
use VendorPackage\View\Components\AlertComponent;
 
/**
 * Bootstrap your package's services.
 *
 * @return void
 */
public function boot()
{
    Blade::component('package-alert', AlertComponent::class);
}

هنگامی که کامپوننت شما ثبت شد، ممکن است با استفاده از تگ مستعار آن رندر شود:

<x-package-alert/>

بارگیری خودکار اجزای بسته

از طرف دیگر، می‌توانید از componentNamespace روشی برای بارگیری خودکار کلاس‌های مؤلفه بر اساس قرارداد استفاده کنید. به عنوان مثال، یک Nightshade بسته ممکن است دارای Calendar اجزایی باشد ColorPicker که در Nightshade\Views\Components فضای نام قرار دارند:

use Illuminate\Support\Facades\Blade;
 
/**
 * Bootstrap your package's services.
 *
 * @return void
 */
public function boot()
{
    Blade::componentNamespace('Nightshade\\Views\\Components', 'nightshade');
}

این اجازه می دهد تا از اجزای بسته توسط فضای نام فروشنده آنها با استفاده از نحو استفاده شود package-name:: :

<x-nightshade::calendar />
<x-nightshade::color-picker />

Blade به طور خودکار کلاسی را که به این مؤلفه پیوند داده شده است، با پوشش پاسکال نام مؤلفه شناسایی می کند. زیر شاخه ها نیز با استفاده از نماد "نقطه" پشتیبانی می شوند.

اجزای ناشناس

components اگر بسته شما حاوی اجزای ناشناس است، آنها باید در فهرستی از فهرست "views" بسته شما قرار گیرند (همانطور که در loadViewsFrom روش مشخص شده است ). سپس، می توانید آنها را با پیشوند نام کامپوننت با فضای نام view بسته ارائه دهید:

<x-courier::alert />

"درباره" فرماندهی صنعتگر

دستور Artisan داخلی لاراول about خلاصه ای از محیط و پیکربندی برنامه را ارائه می دهد. بسته‌ها ممکن است اطلاعات اضافی را از طریق کلاس به خروجی این فرمان وارد کنند AboutCommand . به طور معمول، این اطلاعات ممکن است از روش ارائه دهنده خدمات بسته شما اضافه شود boot :

use Illuminate\Foundation\Console\AboutCommand;
 
/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    AboutCommand::add('My Package', fn () => ['Version' => '1.0.0']);
}

دستورات

برای ثبت دستورات Artisan بسته خود با لاراول، می توانید از این commands روش استفاده کنید. این متد آرایه ای از نام کلاس های فرمان را انتظار دارد. هنگامی که دستورات ثبت شد، می توانید آنها را با استفاده از Artisan CLI اجرا کنید :

use Courier\Console\Commands\InstallCommand;
use Courier\Console\Commands\NetworkCommand;
 
/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            NetworkCommand::class,
        ]);
    }
}

دارایی های عمومی

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

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/../public' => public_path('vendor/courier'),
    ], 'public');
}

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

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

انتشار گروه های فایل

ممکن است بخواهید گروه هایی از دارایی ها و منابع بسته را جداگانه منتشر کنید. به عنوان مثال، ممکن است بخواهید به کاربران خود اجازه دهید تا فایل های پیکربندی بسته شما را بدون اینکه مجبور به انتشار دارایی های بسته شما باشند، منتشر کنند. می‌توانید این کار را با «برچ‌گذاری» آن‌ها هنگام فراخوانی publishes روش از سوی ارائه‌دهنده خدمات بسته انجام دهید. به عنوان مثال، بیایید از تگ ها برای تعریف دو گروه انتشار برای courier بسته ( courier-config و courier-migrations ) در boot روش ارائه دهنده خدمات بسته استفاده کنیم:

/**
 * Bootstrap any package services.
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/../config/package.php' => config_path('package.php')
    ], 'courier-config');
 
    $this->publishes([
        __DIR__.'/../database/migrations/' => database_path('migrations')
    ], 'courier-migrations');
}

اکنون کاربران شما می توانند این گروه ها را به طور جداگانه با ارجاع به برچسب خود هنگام اجرای vendor:publish دستور منتشر کنند:

php artisan vendor:publish --tag=courier-config