Tworzenie poleceń instalatora dla pakietów Laravel

Pakiet Laravel Package Tools firmy Spatie dodał fajną funkcję, którą chcieliśmy pomóc podzielić się ze społecznością: usprawnione polecenia instalacyjne dla pakietów Laravel.

Narzędzia do tworzenia pakietów

Laravel Ten pakiet zawiera pakietyPackageServiceProvider, których można używać w pakietach do łatwego rejestrowania plików konfiguracyjnych, migracji i innych.

Oto przykład, jak można go użyć.

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

Pod maską wykona niezbędną pracę, aby zarejestrować niezbędne rzeczy i udostępnić wszelkiego rodzaju pliki.

Pierwsze kroki

Ten pakiet jest opiniowany na temat tego, jak powinieneś skonstruować swój pakiet. Aby łatwo zacząć, rozważ skorzystanie z naszego repozytorium package-skeleton, aby rozpocząć pakiet. Szkielet jest idealnie skonstruowany, aby idealnie współpracować z tym pakietemPackageServiceProvider.

Zastosowanie

: W pakiecie należy pozwolić usługodawcy na rozszerzenie 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');
    }
}

Przekazanie nazwy pakietu do name jest obowiązkowe.

Praca z plikiem

konfiguracyjnym Aby zarejestrować plik konfiguracyjny, należy utworzyć plik php z nazwą pakietu w config katalogu pakietu. W tym przykładzie powinno być w <package root>/config/your-package-name.php.

Jeśli nazwa pakietu zaczyna się od laravel-, oczekujemy, że plik konfiguracyjny nie zawiera tego prefiksu. Więc jeśli nazwa pakietu to laravel-cool-package, plik konfiguracyjny powinien mieć nazwę cool-package.php.

Aby zarejestrować ten plik konfiguracyjny, wywołaj hasConfigFile() $package metodęconfigurePackage.

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

Metoda hasConfigFile umożliwi również publikację pliku konfiguracyjnego. Użytkownicy pakietu będą mogli opublikować plik konfiguracyjny za pomocą tego polecenia.

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

Jeśli pakiet zawiera wiele plików konfiguracyjnych, można przekazać ich nazwy jako tablicę do hasConfigFile

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

Praca z widokami

Wszystkie widoki dostarczane przez pakiet powinny być umieszczone w katalogu<package root>/resources/views.

Widoki te można zarejestrować za pomocą hasViews polecenia.

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

Spowoduje to zarejestrowanie twoich poglądów w Laravel.

Jeśli masz widok<package root>/resources/views/myView.blade.php, możesz go użyć w ten sposób: view('your-package-name::myView'). Oczywiście możesz również użyć podkatalogów do uporządkowania swoich widoków. Widok znajdujący się w <package root>/resources/views/subdirectory/myOtherView.blade.php może być używany z view('your-package-name::subdirectory.myOtherView')rozszerzeniem .

Korzystanie z niestandardowej przestrzeni

nazw widoku Do hasViews metody można przekazać niestandardową przestrzeń nazw widoku.

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

Możesz teraz używać widoków pakietu w następujący sposób:

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

Publikowanie widoków Wywołanie hasViews spowoduje również publikowanie widoków

. Użytkownicy pakietu będą mogli publikować widoki za pomocą tego polecenia:

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

Udostępnianie danych globalnych widokom

Dane można udostępniać wszystkim widokom za pomocą tej sharesDataWithAllViews metody. Spowoduje to, że zmienna współdzielona będzie dostępna dla wszystkich widoków.

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

Praca ze składnikami

widoku blokowego Wszystkie składniki widoku bloków dostarczane przez pakiet powinny zostać umieszczone w katalogu<package root>/src/Components.

Widoki te można zarejestrować za pomocą hasViewComponents polecenia.

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

Spowoduje to zarejestrowanie komponentów widoku w Laravel. W przypadku Alert::class, można się do niego odwoływać w widokach jako <x-spatie-alert />, gdzie spatie jest prefiksem podanym podczas rejestracji.

Wywołanie hasViewComponents sprawi, że komponenty widoku będą mogły być publikowane i będą publikowane w app/Views/Components/vendor/<package name>formacie .

Użytkownicy pakietu będą mogli publikować komponenty widoku za pomocą następującego polecenia:

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

Praca z kompozytorami widoków Za pomocą hasViewComposers tej metody można zarejestrować dowolne kompozytory widoków

, których projekt używa. Można również zarejestrować wywołanie zwrotne, które odbiera $view argument zamiast nazwy klasy.

Aby zarejestrować kompozytora widoku we wszystkich widokach, użyj gwiazdki jako nazwy '*'widoku.

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

Praca z tłumaczeniami

Wszelkie tłumaczenia dostarczane przez pakiet powinny być umieszczone w katalogu<package root>/resources/lang/<language-code>.

Możesz zarejestrować te tłumaczenia za pomocą hasTranslations polecenia.

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

Spowoduje to zarejestrowanie tłumaczeń w Laravel.

Zakładając, że zapiszesz ten plik tłumaczenia w <package root>/resources/lang/en/translations.php...

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

... Twój pakiet i użytkownicy będą mogli pobrać tłumaczenie za pomocą:Jeśli nazwa pakietu zaczyna się odlaravel-,

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

powinieneś zostawić to wyłączone w powyższym przykładzie.

Kodowanie z ciągami tłumaczeń jako kluczami, należy tworzyć pliki JSON w <package root>/resources/lang/<language-code>.jsonformacie .

Na przykład tworzenie <package root>/resources/lang/it.json pliku w następujący sposób:

{
    "Hello!": "Ciao!"
}

... Wynik...

trans('Hello!');

... Ciao! będzie, jeśli aplikacja używa języka włoskiego.

Calling hasTranslations sprawi, że tłumaczenia będą mogły być publikowane. Użytkownicy pakietu będą mogli publikować tłumaczenia za pomocą tego polecenia:

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

Praca z zasobami

Wszelkie zasoby dostarczane przez pakiet powinny zostać umieszczone w katalogu <package root>/resources/dist/ .

Możesz udostępnić te zasoby jako publikację metody hasAssets .

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

Użytkownicy pakietu będą mogli publikować zasoby za pomocą tego polecenia:

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

Spowoduje to skopiowanie zasobów do public/vendor/<your-package-name> katalogu w aplikacji, w której pakiet jest zainstalowany.

Praca z migracjami

Zakłada się PackageServiceProvider , że wszystkie migracje są umieszczane w tym katalogu: <package root>/database/migrations. Wewnątrz tego katalogu możesz umieścić dowolne migracje.

Aby zarejestrować migrację, należy przekazać jej nazwę bez rozszerzenia do hasMigration tabeli.

Jeśli plik migracji zostanie wywołany create_my_package_tables.php.stub , możesz zarejestrować je w następujący sposób:

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

Jeśli pakiet zawiera wiele plików migracji, możesz po prostu wywołać hasMigration wiele razy lub użyć hasMigrationspolecenia .

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

Wywołanie hasMigration sprawi, że migracje będą również możliwe do opublikowania. Użytkownicy pakietu będą mogli publikować migracje za pomocą tego polecenia:

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

Jak można się spodziewać, opublikowane pliki migracji będą poprzedzone bieżącą datą.

Możesz także włączyć rejestrację migracji bez konieczności publikowania ich przez użytkowników pakietu:

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

Praca z dostawcą

usług do publikacji Niektóre pakiety wymagają przykładowego dostawcy usług do skopiowania app\Providers do katalogu aplikacji Laravel. Pomyśl na przykład o pakiecie, laravel/horizon który kopiuje do HorizonServiceProvider aplikacji z pewnymi rozsądnymi ustawieniami domyślnymi.

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

Plik, który zostanie skopiowany do aplikacji, powinien być przechowywany w pakiecie w /resources/stubs/{$nameOfYourServiceProvider}.php.stubprogramie .

Gdy pakiet jest instalowany w aplikacji, uruchomienie tego polecenia...

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

... skopiuje /resources/stubs/{$nameOfYourServiceProvider}.php pakiet do app/Providers/{$nameOfYourServiceProvider}.php aplikacji użytkownika.

Rejestrowanie poleceń

Możesz zarejestrować dowolne polecenie dostarczone przez pakiet z funkcją hasCommand .

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

Jeśli pakiet zawiera wiele poleceń, można użyć hasCommand ich wiele razy lub przekazać tablicę do hasCommands

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

Dodawanie polecenia instalatora Zamiast zezwalać użytkownikom na ręczne publikowanie plików konfiguracyjnych, migracji i innych plików, można zdecydować się na dodanie polecenia

instalacji, które wykonuje całą tę pracę za jednym razem. Pakiety takie jak Laravel Horizon i Livewire zapewniają takie polecenia.

Korzystając z narzędzi Laravel Package Tools, nie musisz pisać samodzielnie InstallCommand . Zamiast tego możesz po prostu zadzwonić hasInstallCommand i skonfigurować go za pomocą zamknięcia. Oto przykład.

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')
            });
    }
}

Mając to na uwadze, użytkownik pakietu może wywołać to polecenie:

php artisan your-package-name:install

Używając powyższego kodu, polecenie to:

• Publikowanie pliku konfiguracyjnego
• Publikowanie migracji
• Skopiuj plik /resources/stubs/MyProviderName.php.stub z pakietu do app/Providers/MyServiceProviderName.php, a także zarejestruj tego dostawcę w config/app.php
• Zapytaj, czy migracje powinny być uruchamiane teraz
• Poproś użytkownika o otwarcie https://github.com/'your-vendor/your-repo-name' w przeglądarce, aby ją oznaczyć gwiazdką

Możesz również zadzwonić startWith i endWith na InstallCommand. Będą one odpowiednio wykonywane na początku i na końcu podczas biegania php artisan your-package-name:install. Można go użyć do wykonania dodatkowej pracy lub wyświetlenia dodatkowych danych wyjściowych.

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!');
                })
        });
}

Praca z trasami

Zakłada PackageServiceProvider się, że wszystkie pliki marszruty są umieszczane w tym katalogu: <package root>/routes. Wewnątrz tego katalogu możesz umieścić dowolne pliki

tras. Aby zarejestrować trasę, należy przekazać jej nazwę bez rozszerzenia do hasRoute metody.

Jeśli wywoływany jest plik trasy web.php , możesz zarejestrować je w następujący sposób:

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

Jeśli pakiet zawiera wiele plików tras, możesz po prostu wywołać hasRoute wiele razy lub użyć hasRoutes.

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

Korzystanie z haków

cyklu życia Możesz umieścić dowolną niestandardową logikę potrzebną pakietowi podczas uruchamiania w jednej z następujących metod:

• registeringPackage: zostanie wywołany na początku register metody PackageServiceProvider
• packageRegistered: zostanie wywołany na końcu register metody PackageServiceProvider
• bootingPackage: zostanie wywołany na początku boot metody PackageServiceProvider
• packageBooted: zostanie wywołany na końcu boot metody PackageServiceProvider

Szczegóły pobierania testów

composer test

: 
Autor: spatie
Kod źródłowy: https://github.com/spatie/laravel-package-tools 
Licencja: MIT
 #laravel #php