توسعه بسته

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

معرفی

بسته ها راه اصلی اضافه کردن قابلیت به لاراول هستند. بسته‌ها ممکن است هر چیزی باشند، از یک روش عالی برای کار با تاریخ‌هایی مانند کربن یا یک چارچوب آزمایشی کامل BDD مانند Behat .

بسته بندی انواع مختلفی دارد. برخی از بسته ها مستقل هستند، به این معنی که با هر چارچوب PHP کار می کنند. کربن و بهات نمونه هایی از بسته های مستقل هستند. هر یک از این بسته ها ممکن است با درخواست لاراول در 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 application services.
 *
 * @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 :

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

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

مسیرها

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

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

مهاجرت ها

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

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

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

کارخانه ها

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

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadFactoriesFrom(__DIR__.'/path/to/factories');
}

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

factory(Package\Namespace\Model::class)->create();

ترجمه ها

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

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

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

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

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

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

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

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

بازدیدها

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

/**
 * Bootstrap any application services.
 *
 * @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 روش استفاده می کنید، لاراول در واقع دو مکان را برای نماهای شما ثبت می کند: دایرکتوری برنامه resources/views/vendor و دایرکتوری که شما مشخص کرده اید. بنابراین، با استفاده از courier مثال، لاراول ابتدا بررسی می کند که آیا یک نسخه سفارشی از view توسط توسعه دهنده در ارائه شده است یا خیر resources/views/vendor/courier . سپس، اگر نمای شخصی سازی نشده باشد، لاراول دایرکتوری نمای بسته را که در تماس خود با آن مشخص کرده اید جستجو می کند loadViewsFrom . این امر باعث می‌شود تا کاربران بسته به راحتی نماهای بسته شما را شخصی‌سازی یا نادیده بگیرند.

انتشار نماها

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

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

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

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

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

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadViewComponentsAs('courier', [
        Alert::class,
        Button::class,
    ]);
}

هنگامی که اجزای view شما در یک ارائه دهنده خدمات ثبت شد، می توانید آنها را در نمای خود به این صورت ارجاع دهید:

<x-courier-alert />
 
<x-courier-button />

اجزای ناشناس

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

<x-courier::alert />

دستورات

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

/**
 * Bootstrap the application services.
 *
 * @return void
 */
public function boot()
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            FooCommand::class,
            BarCommand::class,
        ]);
    }
}

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

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

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

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

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

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

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

/**
 * Bootstrap any application 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');
}

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

php artisan vendor:publish --tag=config