Создание команд установщика для пакетов 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()
            });
    }
}

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

Начало работы

Этот пакет основан на том, как вы должны структурировать свой пакет. Чтобы легко начать работу, рассмотрите возможность использования нашего репозитория package-skeleton для запуска пакета. Скелет идеально структурирован для идеальной работы с этим пакетом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 метод.

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

configurePackage Этот hasConfigFile метод также сделает конфигурационный файл доступным для публикации. Пользователи вашего пакета смогут опубликовать конфигурационный файл с помощью этой команды.

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

Если ваш пакет содержит несколько конфигурационных файлов, вы можете передать их имена в виде массива в Работа с представлениями

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

Любые представления, предоставляемые вашим пакетом, должны быть помещены в `<package root>/resources/views`

hasConfigFileкаталог.

Вы можете зарегистрировать эти представления с помощью 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');

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

Вызов hasViews также сделает представления доступными для публикации. Пользователи вашего пакета смогут публиковать представления с помощью следующей команды:

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

Совместное использование глобальных данных с представлениями Вы можете поделиться данными со всеми представлениями

с помощью этого методаsharesDataWithAllViews. Это сделает общую переменную доступной для всех представлений.

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

Работа с компонентами

представления колонки Все компоненты представления колонки, предоставляемые пакетом<package root>/src/Components, должны быть помещены в каталог.

Вы можете зарегистрировать эти представления с помощью hasViewComponents команды.

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

При этом компоненты представления будут зарегистрированы в Laravel. В случае , на него можно ссылаться в представлениях как <x-spatie-alert />, где spatie — префикс, Alert::classкоторый вы указали при регистрации.

Вызов 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',
];

... ваш пакет и пользователи смогут получить перевод с помощью:Если имя вашего пакета начинается с буквыlaravel-,

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

вы должны оставить это в приведенном выше примере.

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

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

{
    "Hello!": "Ciao!"
}

:... На выходе...

trans('Hello!');

... будетCiao!, если приложение использует итальянский язык.

Calling 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();

Работа с поставщиком

услуг для публикации Для некоторых пакетов требуется пример поставщика услуг, который должен быть скопирован в каталог приложения Laravel. Подумайте, например, о пакете, laravel/horizon который копирует в app\Providers 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.phpconfig/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: будет вызываться в начале register метода PackageServiceProvider
packageRegistered: будет вызываться в конце register метода PackageServiceProvider
bootingPackage: будет вызываться в начале boot метода PackageServiceProvider
packageBooted: будет вызываться в конце boot метода PackageServiceProvider

Детали загрузки тестирования

composer test

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

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

Начало работы

Использование

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

Любые представления, предоставляемые вашим пакетом, должны быть помещены в `<package root>/resources/views`

Использование пользовательского пространства

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

Совместное использование глобальных данных с представлениями Вы можете поделиться данными со всеми представлениями

Работа с компонентами

Работа с компоновщиками представлений Вы можете зарегистрировать любых компоновщиков представлений

Работа с переводами Любые переводы

Работа с ресурсами

Работа с миграциями

Работа с поставщиком

Регистрация команд Вы

Добавление команды

Работа с маршрутами Предполагается`PackageServiceProvider`, что все файлы маршрутов

Использование перехватчиков

Детали загрузки тестирования

Comments

Yurij Finiv

Full stack

All-in-one SEO platform for teams and individuals

Создание команд установщика для пакетов Laravel

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

Начало работы

Использование

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

Любые представления, предоставляемые вашим пакетом, должны быть помещены в <package root>/resources/views

Использование пользовательского пространства

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

Совместное использование глобальных данных с представлениями Вы можете поделиться данными со всеми представлениями

Работа с компонентами

Работа с компоновщиками представлений Вы можете зарегистрировать любых компоновщиков представлений

Работа с переводами Любые переводы

Работа с ресурсами

Работа с миграциями

Работа с поставщиком

Регистрация команд Вы

Добавление команды

Работа с маршрутами ПредполагаетсяPackageServiceProvider, что все файлы маршрутов

Использование перехватчиков

Детали загрузки тестирования

Comments

Yurij Finiv

Full stack

All-in-one SEO platform for teams and individuals

Любые представления, предоставляемые вашим пакетом, должны быть помещены в `<package root>/resources/views`

Работа с маршрутами Предполагается`PackageServiceProvider`, что все файлы маршрутов