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.

Per estendere un servizio senza crearlo finché non viene usato, applicando la configurazione anche quando è già stato risolto, consulta Hook di risoluzione dei servizi nei pacchetti. La pagina spiega quando viene eseguito callAfterResolving() e come progettare il codice per tollerare applicazioni ripetute. Per i metodi di registrazione che non trascinano stato nemmeno con Octane o con i queue worker, consulta Progettare il ciclo di vita dei servizi di un pacchetto. La pagina spiega l’implementazione interna di scoped() e le avvertenze sulle dipendenze conservate dai singleton.

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.

Le differenze rispetto al metodo di sostituzione ricorsiva di Laravel 13, la gestione delle liste con chiavi numeriche e la procedura di aggiornamento quando usi la cache della configurazione sono spiegate in Merge e cache della configurazione dei pacchetti.

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

Come specificare esplicitamente i middleware, evitare i conflitti di URI e nomi delle route e far arrivare le modifiche alla configurazione nella cache è spiegato in Registrazione e cache delle route di un pacchetto.

Pubblicazione delle migrazioni

Usando publishesMigrations() puoi registrare i file di migrazione per la pubblicazione. Nella configurazione standard di Laravel 13, database.migrations.update_date_on_publish è attivo, quindi il timestamp nel nome del file viene aggiornato al momento della pubblicazione. Se l’impostazione è disattivata o assente, questo aggiornamento non avviene.

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

Quando pubblicare o caricare direttamente, le condizioni per la modifica del timestamp, i rischi della ripubblicazione e le modifiche allo schema per gli utenti esistenti sono spiegati in Pubblicazione e aggiornamento delle migrazioni di un pacchetto.

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. L’ordine di ricerca effettivo e il fallback file per file, come far arrivare le modifiche ai template già pubblicati e la differenza rispetto alla cache di Blade sono spiegati in Sovrascrivere e aggiornare le view di un pacchetto.

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 />

Distribuzione degli asset pubblici

Per distribuire JavaScript, CSS e immagini del pacchetto, registra con publishes() la copia verso una destinazione come public_path('vendor/courier'). Anche se aggiorni il pacchetto, i file già pubblicati non cambiano automaticamente. La selezione dei file tramite tag e provider, la differenza tra --force e --existing, la gestione dei file eliminati e l’aggiornamento tramite laravel-assets sono spiegati in Asset pubblici e aggiornamento di un pacchetto.

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

La sovrascrittura parziale delle traduzioni PHP, l’ordine di caricamento e la destinazione di sovrascrittura delle traduzioni JSON, la compatibilità delle chiavi di traduzione e l’aggiornamento dei file pubblicati sono spiegati in Sovrascrittura e aggiornamento delle traduzioni di un pacchetto.

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

La registrazione delle classi di comando e la registrazione dei task di ottimizzazione sono operazioni distinte. Collisioni delle chiavi di registrazione, esclusione con --except, ordine di esecuzione rispetto ai task standard e codici di uscita in caso di errore sono spiegati in Cache dei pacchetti e integrazione con optimize.

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

Il momento in cui vengono valutati i dati, --only e l’output JSON, un design che non espone segreti e lo stato di registrazione nei test sono spiegati in Aggiungere informazioni diagnostiche del pacchetto ad about.

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