توسعه بسته

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

معرفی

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

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

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

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

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

کشف بسته

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

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

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

انصراف از Package Discovery

اگر شما مصرف‌کننده یک بسته هستید و می‌خواهید کشف بسته را برای یک بسته غیرفعال کنید، می‌توانید نام بسته را در بخش فایل 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.
 */
public function boot(): void
{
    $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.
 */
public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

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

مسیرها

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

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

مهاجرت ها

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

/**
 * Bootstrap any package services.
 */
public function boot(): void
{
    $this->publishesMigrations([
        __DIR__.'/../database/migrations' => database_path('migrations'),
    ]);
}

فایل های زبان

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

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

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

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

با استفاده از این روش می توانید فایل های ترجمه JSON را برای بسته خود ثبت کنید loadJsonTranslationsFrom . این روش مسیر دایرکتوری حاوی فایل های ترجمه JSON بسته شما را می پذیرد:

/**
 * Bootstrap any package services.
 */
public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}

انتشار فایل های زبان

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

/**
 * Bootstrap any package services.
 */
public function boot(): void
{
    $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.
 */
public function boot(): void
{
    $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.
 */
public function boot(): void
{
    $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.
 */
public function boot(): void
{
    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.
 */
public function boot(): void
{
    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.
 */
public function boot(): void
{
    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.
 */
public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            NetworkCommand::class,
        ]);
    }
}

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

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

/**
 * Bootstrap any package services.
 */
public function boot(): void
{
    $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.
 */
public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/package.php' => config_path('package.php')
    ], 'courier-config');
 
    $this->publishesMigrations([
        __DIR__.'/../database/migrations/' => database_path('migrations')
    ], 'courier-migrations');
}

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

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