Створення команд інсталятора для пакетів Laravel

Пакет Laravel Package Tools від Spatie додав чудову функцію, якою ми хотіли допомогти поділитися зі спільнотою: спрощені команди встановлення для пакетів Laravel.

Інструменти для створення пакетів

Laravel Цей пакунок містить пакунки, які можна використовувати у ваших пакунках PackageServiceProvider для легкої реєстрації конфігураційних файлів, міграції тощо.

Ось приклад того, як його можна використовувати.

use Spatie\LaravelPackageTools\PackageServiceProvider;
use Spatie\LaravelPackageTools\Package;
use MyPackage\ViewComponents\Alert;
use Spatie\LaravelPackageTools\Commands\InstallCommand;

class YourPackageServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('your-package-name')
            ->hasConfigFile()
            ->hasViews()
            ->hasViewComponent('spatie', Alert::class)
            ->hasViewComposer('*', MyViewComposer::class)
            ->sharesDataWithAllViews('downloads', 3)
            ->hasTranslations()
            ->hasAssets()
            ->publishesServiceProvider('MyProviderName')
            ->hasRoute('web')
            ->hasMigration('create_package_tables')
            ->hasCommand(YourCoolPackageCommand::class)
            ->hasInstallCommand(function(InstallCommand $command) {
                $command
                    ->publishConfigFile()
                    ->publishMigrations()
                    ->copyAndRegisterServiceProviderInApp()
                    ->askToStarRepoOnGitHub()
            });
    }
}

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

Початок роботи

Цей пакет містить думку про те, як ви повинні структурувати свій пакет. Щоб легко розпочати роботу, розгляньте можливість використання нашого сховища пакунків-скелетів, щоб запустити свій пакет. Скелет ідеально структурований, щоб ідеально працювати з цим пакетомPackageServiceProvider.

Використання

У вашому пакеті ви повинні дозволити своєму постачальнику послуг розширити Spatie\LaravelPackageTools\PackageServiceProvider.

use Spatie\LaravelPackageTools\PackageServiceProvider;
use Spatie\LaravelPackageTools\Package;

class YourPackageServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package) : void
    {
        $package->name('your-package-name');
    }
}

Передача назви name пакета є обов'язковою.

Робота з конфігураційним файлом

Щоб зареєструвати конфігураційний файл, вам слід створити файл php з іменем вашого пакета в каталозі вашого пакетаconfig. У цьому прикладі він повинен бути на .<package root>/config/your-package-name.php

Якщо ім'я пакунка починається з laravel-, ми очікуємо, що ваш конфігураційний файл не містить цього префікса. Отже, якщо ім'я вашого пакета , laravel-cool-packageконфігураційний файл повинен мати ім'я cool-package.php.

Щоб зареєструвати цей конфігураційний файл, зателефонуйте hasConfigFile() $package до методуconfigurePackage.

$package
    ->name('your-package-name')
    ->hasConfigFile();

Метод hasConfigFile також зробить конфігураційний файл доступним для публікації. Користувачі вашого пакета зможуть опублікувати конфігураційний файл за допомогою цієї команди.

php artisan vendor:publish --tag=your-package-name-config

Якщо ваш пакунок має декілька конфігураційних файлів, ви можете передати їх імена масивом до hasConfigFile

$package
    ->name('your-package-name')
    ->hasConfigFile(['my-config-file', 'another-config-file']);

Робота з представленнями Будь-які представлення

виглядів, які надає ваш пакет, повинні бути розміщені в <package root>/resources/views каталозі.

Ви можете зареєструвати ці подання за допомогою командиhasViews.

$package
    ->name('your-package-name')
    ->hasViews();

Це дозволить зареєструвати ваші погляди в Laravel.

Якщо у вас є представлення <package root>/resources/views/myView.blade.php, ви можете використовувати його так: view('your-package-name::myView'). Звичайно, ви також можете використовувати підкаталоги для впорядкування своїх переглядів. Представлення, розташоване за адресою, <package root>/resources/views/subdirectory/myOtherView.blade.php можна використовувати з view('your-package-name::subdirectory.myOtherView').

Використання настроюваного простору

імен представлень Методу hasViews можна передати настроюваний простір імен подань.

$package
    ->name('your-package-name')
    ->hasViews('custom-view-namespace');

Тепер ви можете використовувати вигляди пакета таким чином:

view('custom-view-namespace::myView');

Публікація представлень

Calling hasViews також зробить перегляди доступними для публікації. Користувачі вашого пакета зможуть публікувати представлення даних за допомогою цієї команди:

php artisan vendor:publish --tag=your-package-name-views

Спільний доступ до глобальних даних з переглядами

Ви можете поділитися даними з усіма поданнями за допомогою методуsharesDataWithAllViews. Це зробить спільну змінну доступною для всіх представлень.

$package
    ->name('your-package-name')
    ->sharesDataWithAllViews('companyName', 'Spatie');

Робота з компонентами Blade view Будь-які компоненти

виду Blade, які надає ваш пакет, повинні бути розміщені в <package root>/src/Components каталозі.

Ви можете зареєструвати ці подання за допомогою командиhasViewComponents.

$package
    ->name('your-package-name')
    ->hasViewComponents('spatie', Alert::class);

Це зареєструє компоненти перегляду в Laravel. У випадку Alert::class, на нього можна посилатися у <x-spatie-alert />вигляді , де spatie - префікс, який ви вказали під час реєстрації.

Виклик hasViewComponents також зробить компоненти представлення придатними для публікації та буде опубліковано в app/Views/Components/vendor/<package name>.

Користувачі вашого пакунка зможуть публікувати компоненти перегляду за допомогою такої команди:

php artisan vendor:publish --tag=your-package-name-components

Робота з компонувальниками

подань Ви можете зареєструвати будь-які компонувальники переглядів, які використовує ваш проект, за допомогою методуhasViewComposers. Ви також можете зареєструвати зворотний виклик, який отримує $view аргумент замість імені класу.

Щоб зареєструвати компонувальника переглядів з усіма виглядами, використовуйте зірочку як ім'я '*'вигляду .

$package
    ->name('your-package-name')
    ->hasViewComposer('viewName', MyViewComposer::class)
    ->hasViewComposer('*', function($view) { 
        $view->with('sharedVariable', 123); 
    });

Робота з перекладами Будь-які переклади

, які надає ваш пакет, повинні бути розміщені в <package root>/resources/lang/<language-code> каталозі.

Ви можете зареєструвати ці переклади за допомогою командиhasTranslations.

$package
    ->name('your-package-name')
    ->hasTranslations();

Це дозволить зареєструвати переклади в Laravel.

Припускаючи, що ви збережете цей файл перекладу за адресою <package root>/resources/lang/en/translations.php...

return [
    'translatable' => 'translation',
];

... Ваш пакет і користувачі зможуть отримати переклад за допомогою:

trans('your-package-name::translations.translatable'); // returns 'translation'

Якщо назва вашого пакета починається з наlaravel-, вам слід залишити це в прикладі вище.

Кодування з рядками перекладу як ключами, ви повинні створити файли JSON у форматі <package root>/resources/lang/<language-code>.json.

Наприклад, створення <package root>/resources/lang/it.json файлу так:

{
    "Hello!": "Ciao!"
}

... На виході...

trans('Hello!');

... Ciao! буде, якщо в додатку використовується італійська мова.

Покликання hasTranslations також зробить переклади доступними для публікації. Користувачі вашого пакету зможуть публікувати переклади за допомогою цієї команди:

php artisan vendor:publish --tag=your-package-name-translations

Робота з активами

Будь-які активи, які надає ваш пакет, повинні бути розміщені в <package root>/resources/dist/ каталозі.

Ви можете зробити ці об'єкти доступними для публікації методомhasAssets.

$package
    ->name('your-package-name')
    ->hasAssets();

Користувачі вашого пакета зможуть публікувати активи за допомогою цієї команди:

php artisan vendor:publish --tag=your-package-name-assets

Це скопіює ресурси до каталогу public/vendor/<your-package-name> в додатку, де встановлено ваш пакет.

Робота з міграціями

ПрипускаєтьсяPackageServiceProvider, що будь-які міграції розміщуються в такому каталозі: <package root>/database/migrations. Усередині цього каталогу ви можете помістити будь-які міграції.

Щоб зареєструвати міграцію, слід передати її назву без розширення в hasMigration таблицю.

Якщо ваш файл міграції викликаєтьсяcreate_my_package_tables.php.stub, ви можете зареєструвати їх так:

$package
    ->name('your-package-name')
    ->hasMigration('create_my_package_tables');

Якщо ваш пакет містить кілька файлів міграції, ви можете просто зателефонувати hasMigration кілька разів або скористатися hasMigrations.

$package
    ->name('your-package-name')
    ->hasMigrations(['my_package_tables', 'some_other_migration']);

Виклики hasMigration також зроблять міграцію доступною для публікації. Користувачі вашого пакунка зможуть публікувати міграції за допомогою цієї команди:

php artisan vendor:publish --tag=your-package-name-migrations

Як і слід було очікувати, опубліковані файли міграції матимуть префікс поточної дати й часу.

Ви також можете ввімкнути реєстрацію перенесень, не вимагаючи від користувачів вашого пакета публікувати їх:

$package
    ->name('your-package-name')
    ->hasMigrations(['my_package_tables', 'some_other_migration'])
    ->runsMigrations();

Робота з постачальником послуг, які можна опублікувати Деякі пакети потребують прикладу постачальника

послуг для копіювання в app\Providers каталог програми Laravel. Подумайте, наприклад, про пакет, laravel/horizon який копіює у HorizonServiceProvider ваш додаток з деякими розумними налаштуваннями за замовчуванням.

$package
    ->name('your-package-name')
    ->publishesServiceProvider($nameOfYourServiceProvider);

Файл, який буде скопійовано в додаток, повинен зберігатися у вашому пакеті в /resources/stubs/{$nameOfYourServiceProvider}.php.stub.

Коли ваш пакет встановлено в програму, запустіть цю команду...

php artisan vendor:publish --tag=your-package-name-provider

... буде скопійовано /resources/stubs/{$nameOfYourServiceProvider}.php у вашому пакеті в app/Providers/{$nameOfYourServiceProvider}.php додаток користувача.

Реєстрація команд

Ви можете зареєструвати будь-яку команду, яку ваш пакет надає з hasCommand цією функцією.

$package
    ->name('your-package-name')
    ->hasCommand(YourCoolPackageCommand::class);

Якщо ваш пакунок містить декілька команд, ви можете використовувати hasCommand їх кілька разів або передати масив Додавання hasCommands

$package
    ->name('your-package-name')
    ->hasCommands([
        YourCoolPackageCommand::class,
        YourOtherCoolPackageCommand::class,
    ]);

команди

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

При використанні інструментів Laravel Package Tools вам не потрібно писати самостійноInstallCommand. Замість цього ви можете просто зателефонувати і налаштувати його, hasInstallCommand використовуючи закриття. Ось приклад.

use Spatie\LaravelPackageTools\PackageServiceProvider;
use Spatie\LaravelPackageTools\Package;
use Spatie\LaravelPackageTools\Commands\InstallCommand;

class YourPackageServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('your-package-name')
            ->hasConfigFile()
            ->hasMigration('create_package_tables')
            ->publishesServiceProvider('MyServiceProviderName')
            ->hasInstallCommand(function(InstallCommand $command) {
                $command
                    ->publishConfigFile()
                    ->publishMigrations()
                     ->askToRunMigrations()
                    ->copyAndRegisterServiceProviderInApp()
                    ->askToStarRepoOnGitHub('your-vendor/your-repo-name')
            });
    }
}

Після цього користувач пакета може викликати таку команду:Використовуючи код вище, ця команда:

php artisan your-package-name:install

• Публікація конфігураційного файлу
• Публікація перенесень
• скопіюйте пакет до /resources/stubs/MyProviderName.php.stub app/Providers/MyServiceProviderName.php, а також зареєструйте цього постачальника в config/app.php
• Запитайте, чи слід запускати перенесення зараз
• Запропонуйте користувачеві відкритися https://github.com/'your-vendor/your-repo-name' в браузері, щоб зірочка

Також можна зателефонувати startWith і endWith на InstallCommand. Вони будуть відповідно виконуватися на початку і в кінці при бігу php artisan your-package-name:install. Ви можете використовувати це для виконання додаткової роботи або відображення додаткового результату.

use use Spatie\LaravelPackageTools\Commands\InstallCommand;

public function configurePackage(Package $package): void
{
    $package
        // ... configure package
        ->hasInstallCommand(function(InstallCommand $command) {
            $command
                ->startWith(function(InstallCommand $command) {
                    $command->info('Hello, and welcome to my great new package!')
                })
                ->publishConfigFile()
                ->publishMigrations()
               ->askToRunMigrations()
                ->copyAndRegisterServiceProviderInApp()
                ->askToStarRepoOnGitHub('your-vendor/your-repo-name')
                ->endWith(function(InstallCommand $command) {
                    $command->info('Have a great day!');
                })
        });
}

Робота з маршрутами

Передбачається PackageServiceProvider , що будь-які файли маршрутів розміщуються в такому каталозі: <package root>/routes. Всередині цього каталогу ви можете помістити будь-які файли маршрутів.

Щоб зареєструвати свій маршрут, вам слід передати його назву без розширення до методу hasRoute .

Якщо ваш файл маршруту викликається web.php , ви можете зареєструвати їх таким чином:

$package
    ->name('your-package-name')
    ->hasRoute('web');

Якщо ваш пакет містить кілька файлів маршруту, ви можете просто зателефонувати hasRoute кілька разів або скористатися hasRoutes.

$package
    ->name('your-package-name')
    ->hasRoutes(['web', 'admin']);

Використання гачків життєвого циклу

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

• registeringPackage: буде викликатися на старті методу registerPackageServiceProvider
• packageRegistered: буде викликано в кінці методу registerPackageServiceProvider
• bootingPackage: буде викликатися на старті методу bootPackageServiceProvider
• packageBooted: буде викликано в кінці методу bootPackageServiceProvider

Деталі завантаження тестування

composer test

: 
Автор: spatie
Вихідний код: https://github.com/spatie/laravel-package-tools 
Ліцензія: MIT
 #laravel #php