Версія фреймворка: 8.x

Розробка пакетів

Вступ

Пакети - це основний спосіб додати функціональність до Laravel. Пакети можуть бути чим завгодно, від чудового способу роботи з такими датами, якВуглець, або цілий фреймворк тестування BDD, наприкладБехат.

Існують різні типи пакетів. Деякі пакети є автономними, тобто вони працюють з будь-яким фреймворком PHP. Carbon та Behat - це приклади окремих пакетів. Будь-який із цих пакетів можна використовувати разом із Laravel, запитуючи їх у своємуcomposer.jsonфайл.

З іншого боку, інші упаковки спеціально призначені для використання з Laravel. Ці пакети можуть мати маршрути, контролери, View та конфігурацію, спеціально призначені для вдосконалення програми Laravel. Цей посібник насамперед охоплює розробку тих пакетів, які є специфічними для Laravel.

Примітка про фасади

При написанні заявки Laravel, як правило, не має значення, використовуєте ви контракти чи фасади, оскільки обидва вони забезпечують фактично рівні рівні перевірки. Однак під час написання пакетів ваш пакет, як правило, не матиме доступу до всіх помічників тестування Laravel. Якщо ви хочете мати можливість писати свої тести пакетів так, ніби вони існують у типовому додатку Laravel, ви можете використовуватиОркестровий випробувальний стендпакет.

Відкриття пакету

У програмі Laravelconfig/app.phpфайл конфігурації, файлprovidersПараметр визначає список Vendor послуг, які повинен завантажити Laravel. Коли хтось встановлює ваш пакет, ви зазвичай хочете, щоб ваш постачальник послуг був включений до цього списку. Замість того, щоб вимагати від користувачів вручну додавати свого постачальника послуг до списку, ви можете визначити цього постачальника вextraрозділ вашого пакетаcomposer.jsonфайл. Окрім Vendor послуг, ви можете також перерахувати будь-якихфасадиВи хочете бути зареєстрованим:

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

Після того, як ваш пакет буде налаштований на виявлення, Laravel автоматично реєструватиме своїх Vendor послуг та фасади після його встановлення, створюючи зручний досвід встановлення для користувачів вашого пакету.

Відмова від виявлення пакунків

Якщо ви є споживачем пакета і хочете відключити виявлення пакета для пакету, ви можете вказати ім'я пакета вextraрозділ вашої програмиcomposer.jsonфайл:

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

Ви можете вимкнути виявлення пакунків для всіх пакетів, що використовують*символу всередині вашої програмиdont-discoverдиректива:

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

Service Providers

Service Providersє точками зв’язку між вашим пакетом та Laravel. Постачальник послуг відповідає за прив'язку речей до Laravelслужбовий контейнерта інформування Laravel куди завантажувати ресурси пакету, такі як Views, конфігурація та файли локалізації.

Постачальник послуг розширюєIlluminate\Support\ServiceProviderклас і містить два методи:registerіboot. ОсноваServiceProviderклас знаходиться вilluminate/supportПакет Composer, який слід додати до залежностей власного пакета. Щоб дізнатись більше про структуру та призначення Vendor послуг, ознайомтесьїх документація.

Ресурси

Конфігурація

Як правило, вам потрібно буде опублікувати файл конфігурації пакета у власному додаткуconfigкаталог. Це дозволить користувачам вашого пакету легко замінити ваші параметри конфігурації за замовчуванням. Щоб дозволити публікацію файлів конфігурації, зателефонуйте на номерpublishesметод зbootспосіб вашого постачальника послуг:

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

Тепер, коли користувачі вашого пакету виконують Laravelvendor:publishкоманда, ваш файл буде скопійовано до вказаного місця публікації. Після публікації вашої конфігурації її значення можна отримати як будь-який інший конфігураційний файл:

$value = config('courier.option');
Не слід визначати Закриття у файлах конфігурації. Вони не можуть бути правильно серіалізовані, коли користувачі виконуютьconfig:cacheartisan командування.

Конфігурація пакета за замовчуванням

Ви також можете об'єднати власний файл конфігурації пакета з опублікованою копією програми. Це дозволить вашим користувачам визначати лише ті параметри, які вони дійсно хочуть замінити в опублікованій копії конфігурації. Щоб об'єднати конфігурації, використовуйте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спосіб повідомити Laravel, як їх завантажувати.loadMigrationsFromметод приймає шлях до міграцій вашого пакету як єдиний аргумент:

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

Після реєстрації міграцій вашого пакету вони автоматично запускатимуться, колиphp artisan migrateкоманда виконується. Вам не потрібно експортувати їх до основної програмиdatabase/migrationsкаталог.

Переклади

Якщо ваш пакет міститьфайли перекладу, ви можете використовуватиloadTranslationsFromспосіб повідомити Laravel, як їх завантажувати. Наприклад, якщо ваш пакет названий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'),
    ]);
}

Тепер, коли користувачі вашого пакету виконують Laravelvendor:publishКоманда Artisan, переклади вашого пакету будуть опубліковані до вказаного місця публікації.

Перегляди

Зареєструвати пакункипоглядиз Laravel, вам потрібно сказати Laravel, де розташовані види. Ви можете зробити це за допомогою постачальника послугloadViewsFromметод.loadViewsFromметод приймає два аргументи: шлях до шаблонів View та ім'я вашого пакета. Наприклад, якщо ім’я вашого пакета -courier, Ви б додали наступне до свого постачальника послугbootметод:

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

Заміна переглядів пакетів

Коли ви використовуєтеloadViewsFromметоду, Laravel фактично реєструє два місця для ваших поглядів: додатокresources/views/vendorі вказаний вами каталог. Отже, використовуючиcourierНаприклад, Laravel спочатку перевірить, чи розробник надав власну версію View вresources/views/vendor/courier. Потім, якщо View не було налаштовано, Laravel здійснить пошук у каталозі перегляду пакетів, який ви вказали у своєму дзвінкуloadViewsFrom. Це полегшує користувачам пакунків можливість налаштовувати / перевизначати View вашого пакета.

Публікація поглядів

Якщо ви хочете зробити свої погляди доступними для публікації в програмі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'),
    ]);
}

Тепер, коли користувачі вашого пакету виконують Laravelvendor:publishКоманда Artisan, View вашого пакету будуть скопійовані у вказане місце публікації.

Перегляд компонентів

Якщо ваш пакет міститьпереглянути компоненти, ви можете використовуватиloadViewComponentsAsспосіб повідомити Laravel, як їх завантажувати.loadViewComponentsAsметод приймає два аргументи: префікс тегу для компонентів представлення та масив класу компонентів View. Наприклад, якщо префікс вашого пакета -courierі у вас єAlertіButtonперегляду компонентів, ви б додали наступне до постачальника послугbootметод:

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

Після того, як компоненти вашого представлення зареєстровані у постачальника послуг, ви можете посилатись на них у своєму поданні так:

<x-courier-alert />

<x-courier-button />

Анонімні компоненти

Якщо ваш пакет містить анонімні компоненти, вони повинні бути розміщені вcomponentsкаталог каталогу "View" вашого пакету (як вказаноloadViewsFrom). Потім ви можете відтворити їх, додавши ім'я компонента до простору імен View пакета:

<x-courier::alert />

Команди

Щоб зареєструвати команди Artisan вашого пакету в Laravel, ви можете використовуватиcommandsметод. Цей метод передбачає масив імен класів команд. Після реєстрації команд ви можете виконувати їх за допомогоюМайстер CLI:

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

Public Assets

Ваш пакет може мати такі Assets, як JavaScript, CSS та зображення. Опублікувати ці Assets в додаткуpublicдовідник, скористайтеся послугами постачальника послугpublishesметод. У цьому прикладі ми також додамо apublicтег групи активів, який може використовуватися для публікації груп пов’язаних активів:

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

Тепер, коли користувачі вашого пакету виконуютьvendor:publishКоманда активів буде скопійована до вказаного місця публікації. Оскільки вам зазвичай потрібно буде перезаписувати Assets кожного разу, коли пакет оновлюється, ви можете використовувати--forceпрапор:

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

Публікація файлових груп

Можливо, ви захочете опублікувати групи ресурсів та ресурсів пакета окремо. Наприклад, ви можете дозволити своїм користувачам публікувати файли конфігурації вашого пакета, не змушуючи публікувати Assets пакета. Ви можете зробити це, позначивши їх при виклику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