Sviluppo di pacchetti Laravel

Cos’è un pacchetto

In Laravel un pacchetto è un pacchetto Composer che aggiunge funzionalità all’applicazione. Esistono principalmente due tipi.

Pacchetti standalone — librerie PHP generiche che non dipendono da Laravel (es. Carbon, Pest)
Pacchetti Laravel — pacchetti con funzionalità integrate a Laravel come route, controller, view, configurazioni

Questa guida tratta il secondo tipo, i pacchetti specifici per Laravel. Lo sviluppo di pacchetti richiede una conoscenza approfondita delle strutture interne di Laravel, come service provider, facade e pubblicazione dei file di configurazione.

Per scrivere test dei pacchetti si usa Orchestra Testbench. Puoi scrivere i test come faresti in una normale applicazione Laravel.

Auto-discovery dei pacchetti

Quando un pacchetto viene installato, Laravel legge la sezione extra.laravel di composer.json e registra automaticamente service provider e facade.

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

Con questa configurazione, l’utente non ha bisogno di modificare manualmente bootstrap/providers.php: il pacchetto viene caricato automaticamente.

Come è implementato l’auto-discovery e quando la cache viene ricostruita è spiegato in dettaglio in Struttura interna del package auto-discovery.

Disabilitare l’auto-discovery

Se l’utente vuole disabilitare l’auto-discovery per un pacchetto specifico, può configurarlo nel composer.json dell’applicazione.

"extra": {
    "laravel": {
        "dont-discover": [
            "acme/courier"
        ]
    }
}

Il ruolo dei service provider

Il service provider è il punto di ingresso del pacchetto. Qui centralizzi la registrazione di view, configurazioni, migrazioni, route e altre risorse in Laravel. Un service provider estende Illuminate\Support\ServiceProvider e ha due metodi: register e boot.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * Registra i servizi del pacchetto
     */
    public function register(): void
    {
        // qui vanno i binding sul service container
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * Esegue il bootstrap dei servizi del pacchetto
     */
    public function boot(): void
    {
        // la registrazione delle risorse va qui
        $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
        $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

        $this->publishesMigrations([
            __DIR__.'/../database/migrations' => database_path('migrations'),
        ]);

        $this->publishes([
            __DIR__.'/../config/courier.php' => config_path('courier.php'),
        ], 'courier-config');

        $this->publishes([
            __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
        ], 'courier-views');
    }
}

Non registrare event listener, route, view ecc. all’interno del metodo register. Potresti finire per usare per errore servizi di un altro service provider non ancora caricato. Le operazioni diverse dal binding vanno sempre effettuate nel metodo boot.

Pubblicazione dei file di configurazione

publishes() — pubblicare file

Chiamando publishes() nel metodo boot, permetti all’utente di copiare i file di configurazione nella propria applicazione con il comando vendor:publish.

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ]);
}

I valori di configurazione pubblicati si possono ottenere con il normale accesso a config.

$value = config('courier.option');

mergeConfigFrom() — unire con i valori di default

Usando mergeConfigFrom() nel metodo register, i valori di default del pacchetto vengono usati anche quando l’utente non ha pubblicato il file di configurazione.

public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

mergeConfigFrom() non unisce ricorsivamente gli array annidati fino ai livelli più profondi. Per configurazioni con array multidimensionali, se l’utente definisce solo una parte, le opzioni rimanenti potrebbero non essere unite.

Separare i gruppi di pubblicazione tramite tag

Passando un tag come secondo argomento di publishes(), l’utente può pubblicare solo le risorse di cui ha bisogno.

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ], 'courier-config');

    $this->publishesMigrations([
        __DIR__.'/../database/migrations/' => database_path('migrations'),
    ], 'courier-migrations');
}

# pubblica solo il file di configurazione
php artisan vendor:publish --tag=courier-config

# pubblica tutti i file forniti dal provider
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

Registrazione delle route

Per caricare i file di route si usa loadRoutesFrom(). Quando la cache delle route dell’applicazione è attiva, viene saltato automaticamente.

public function boot(): void
{
    $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
}

Nel file di route si specificano i controller del pacchetto.

// routes/web.php
use Acme\Courier\Http\Controllers\TrackingController;
use Illuminate\Support\Facades\Route;

Route::prefix('courier')->group(function () {
    Route::get('/track/{id}', [TrackingController::class, 'show'])
        ->name('courier.track');
});

Pubblicazione delle migrazioni

Usando publishesMigrations() puoi pubblicare i file di migrazione. Al momento della pubblicazione Laravel aggiorna automaticamente il timestamp.

public function boot(): void
{
    $this->publishesMigrations([
        __DIR__.'/../database/migrations' => database_path('migrations'),
    ]);
}

Pubblicazione delle view

loadViewsFrom() — registrare le view

Con loadViewsFrom() registri la directory delle view. Tramite il namespace passato come secondo argomento, referenzi le view nella forma package::view.

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
}

Dopo la registrazione, le view si referenziano tramite il namespace del pacchetto.

Route::get('/dashboard', function () {
    return view('courier::dashboard');
});

Laravel cerca le view in due posizioni. Prima controlla la directory resources/views/vendor/courier dell’applicazione e, se non la trova, usa la directory delle view del pacchetto. Questo permette all’utente di personalizzare le view.

Pubblicare le view

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');

    $this->publishes([
        __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
    ], 'courier-views');
}

Registrare componenti Blade

Se includi componenti nel pacchetto, registrali nel metodo boot.

use Illuminate\Support\Facades\Blade;
use Acme\Courier\View\Components\AlertComponent;

public function boot(): void
{
    Blade::component('courier-alert', AlertComponent::class);
}

Puoi anche registrare in blocco usando un namespace di componenti.

use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::componentNamespace('Acme\\Courier\\View\\Components', 'courier');
}

{{-- registrazione individuale --}}
<x-courier-alert />

{{-- registrazione tramite namespace --}}
<x-courier::alert />

Pubblicazione dei file di traduzione

Con loadTranslationsFrom() registri i file di traduzione. Le traduzioni si referenziano nella forma package::file.key.

public function boot(): void
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

    $this->publishes([
        __DIR__.'/../lang' => $this->app->langPath('vendor/courier'),
    ]);
}

// uso della traduzione
echo trans('courier::messages.welcome');

Per usare file di traduzione JSON, utilizza loadJsonTranslationsFrom().

public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}

Registrazione dei comandi

I comandi Artisan del pacchetto si registrano con il metodo commands(). È comune registrarli solo in ambiente console.

use Acme\Courier\Console\Commands\InstallCommand;
use Acme\Courier\Console\Commands\SyncCommand;

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            SyncCommand::class,
        ]);
    }
}

Integrazione con il comando optimize

Se il pacchetto ha una propria cache, puoi integrarla con php artisan optimize e php artisan optimize:clear tramite il metodo optimizes().

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->optimizes(
            optimize: 'courier:cache',
            clear: 'courier:clear-cache',
        );
    }
}

Aggiungere informazioni al comando `about`

Per aggiungere informazioni sul pacchetto all’output di php artisan about, usa AboutCommand::add().

use Illuminate\Foundation\Console\AboutCommand;

public function boot(): void
{
    AboutCommand::add('Courier Package', fn () => ['Version' => '1.0.0']);
}

Creazione di facade

Le facade ti permettono di chiamare i binding del service container come metodi statici.

Crea la classe di servizio

<?php

namespace Acme\Courier;

class CourierManager
{
    public function __construct(
        protected array $config,
    ) {}

    public function send(string $to, string $message): bool
    {
        // logica di invio messaggio
        return true;
    }

    public function track(string $id): array
    {
        // logica di recupero delle informazioni di tracciamento
        return ['status' => 'delivered'];
    }
}

Crea la classe facade

Estendi Illuminate\Support\Facades\Facade e restituisci in getFacadeAccessor() la chiave del binding sul service container.

<?php

namespace Acme\Courier\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @method static bool send(string $to, string $message)
 * @method static array track(string $id)
 *
 * @see \Acme\Courier\CourierManager
 */
class Courier extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return \Acme\Courier\CourierManager::class;
    }
}

Effettua il binding nel service provider

public function register(): void
{
    $this->app->singleton(\Acme\Courier\CourierManager::class, function ($app) {
        return new \Acme\Courier\CourierManager($app['config']['courier']);
    });
}

Registra in composer.json

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

Aggiungendo alle facade le annotazioni PHPDoc @method, abiliti l’autocompletamento dell’IDE.

// chiama il servizio tramite la facade
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', 'Il pacco è arrivato');
$status = Courier::track('ABC-123');

DeferrableProvider — implementare il caricamento differito

I provider che effettuano solo binding sul service container possono implementare il caricamento differito tramite l’interfaccia DeferrableProvider. Poiché il provider viene caricato solo quando il servizio è effettivamente richiesto, le performance dell’applicazione migliorano.

<?php

namespace Acme\Courier;

use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * Restituisce l'elenco dei servizi forniti da questo provider
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravel compila e salva la lista dei servizi forniti dai provider differiti. Il provider viene caricato solo quando uno dei servizi elencati in provides() viene risolto.

Non usare DeferrableProvider per provider che devono registrare risorse (view, route, event listener ecc.). Se caricati in modo differito, tali risorse rimarrebbero non registrate.

Test del pacchetto

Per testare il pacchetto in isolamento si usa Orchestra Testbench. Puoi scrivere i test del pacchetto come se ti trovassi all’interno di una normale applicazione Laravel.

composer require --dev orchestra/testbench

Nel test case, sovrascrivi getPackageProviders() per registrare il service provider del pacchetto.

<?php

namespace Acme\Courier\Tests;

use Acme\Courier\CourierServiceProvider;
use Orchestra\Testbench\TestCase as BaseTestCase;

class TestCase extends BaseTestCase
{
    /**
     * Registra il service provider del pacchetto
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * Registra gli alias di facade del pacchetto
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * Configurazione d'ambiente per i test
     */
    protected function defineEnvironment($app): void
    {
        $app['config']->set('courier.api_key', 'test-key');
    }
}

<?php

namespace Acme\Courier\Tests\Feature;

use Acme\Courier\Facades\Courier;
use Acme\Courier\Tests\TestCase;

class CourierTest extends TestCase
{
    public function test_can_send_message(): void
    {
        $result = Courier::send('[email protected]', 'Messaggio di test');

        $this->assertTrue($result);
    }
}

Pubblicazione su Composer

Best practice per pubblicare il pacchetto su Packagist. Configurazione di base di composer.json

{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^11.0||^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ],
            "aliases": {
                "Courier": "Acme\\Courier\\Facades\\Courier"
            }
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

Dipendendo da illuminate/support puoi includere come dipendenze solo i componenti Laravel necessari, invece dell’intero illuminate/framework. Mantieni piccolo l’albero delle dipendenze del pacchetto.

Esempio di struttura delle directory

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── it/
│       └── messages.php
├── resources/
│   └── views/
│       └── dashboard.blade.php
├── routes/
│   └── web.php
├── src/
│   ├── Console/
│   │   └── Commands/
│   │       └── InstallCommand.php
│   ├── Facades/
│   │   └── Courier.php
│   ├── Http/
│   │   └── Controllers/
│   │       └── TrackingController.php
│   ├── CourierManager.php
│   └── CourierServiceProvider.php
├── tests/
│   ├── Feature/
│   └── TestCase.php
├── composer.json
└── README.md

Pagine correlate

Service provider

Approfondisci i metodi register e boot dei service provider e i provider differiti.

Gestione della compatibilità di versione

Strategie per gestire gli upgrade di versione maggiore di Laravel e PHP e configurazione della matrice di test con GitHub Actions.

Sviluppo con AI

Design pattern