Développement de packages Laravel

Qu’est-ce qu’un package ?

Dans Laravel, un package est un package Composer qui ajoute des fonctionnalités à votre application. Il en existe globalement deux types :

Package autonome — bibliothèque PHP générique qui ne dépend pas de Laravel (par exemple : Carbon, Pest)
Package Laravel — package intégré à Laravel qui expose des routes, des contrôleurs, des vues, de la configuration, etc.

Ce guide traite du second cas, à savoir le développement de packages spécifiques à Laravel. Concevoir un tel package suppose une bonne connaissance de la structure interne de Laravel : service providers, façades, publication de fichiers de configuration, etc.

Pour tester votre package, utilisez Orchestra Testbench. Vous pourrez écrire les tests de votre package comme s’il s’agissait d’une application Laravel classique.

Découverte automatique des packages

Lorsqu’un package est installé, Laravel lit la section extra.laravel de son composer.json afin d’enregistrer automatiquement les service providers et les façades.

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

Grâce à cette configuration, l’utilisateur n’a plus besoin d’éditer manuellement bootstrap/providers.php : le package est chargé automatiquement.

Le fonctionnement interne de la découverte automatique et le moment où le cache est reconstruit sont détaillés dans Fonctionnement interne de la découverte de packages.

Désactiver la découverte automatique

Si un utilisateur souhaite désactiver la découverte automatique pour un package donné, il peut le déclarer dans le composer.json de son application.

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

Rôle du service provider

Le service provider est le point d’entrée d’un package. C’est là que l’on centralise l’enregistrement des ressources (vues, configuration, migrations, routes…) auprès de Laravel. Le service provider hérite de Illuminate\Support\ServiceProvider et possède deux méthodes : register et boot.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * Enregistre les services du package.
     */
    public function register(): void
    {
        // Les bindings dans le service container se font ici
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

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

    /**
     * Amorce les services du package.
     */
    public function boot(): void
    {
        // L'enregistrement des ressources se fait ici
        $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');
    }
}

N’enregistrez ni écouteurs d’événements, ni routes, ni vues dans la méthode register. Vous risqueriez d’utiliser par erreur un service issu d’un autre service provider pas encore chargé. Tout traitement autre qu’un binding doit se faire dans boot.

Publication du fichier de configuration

publishes() — publier des fichiers

En appelant publishes() dans boot, vous permettez aux utilisateurs de copier le fichier de configuration dans leur application via la commande vendor:publish.

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

Une fois publié, l’accès à la configuration se fait de manière classique :

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

mergeConfigFrom() — fusionner avec des valeurs par défaut

En utilisant mergeConfigFrom() dans la méthode register, vous garantissez que les valeurs par défaut du package sont utilisées même lorsque l’utilisateur n’a pas publié le fichier de configuration.

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

mergeConfigFrom() ne fusionne pas les tableaux imbriqués en profondeur. Sur des configurations comportant des tableaux multidimensionnels, une définition partielle par l’utilisateur peut empêcher la fusion des options restantes.

Séparer les groupes de publication par tag

En passant un tag comme deuxième argument à publishes(), vous permettez aux utilisateurs de publier uniquement les ressources dont ils ont besoin.

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

# Publier uniquement le fichier de configuration
php artisan vendor:publish --tag=courier-config

# Publier tous les fichiers fournis par le provider
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

Enregistrement des routes

Utilisez loadRoutesFrom() pour charger un fichier de routes. Si le cache des routes de l’application est actif, le chargement est automatiquement ignoré.

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

Dans le fichier de routes, référencez les contrôleurs du package :

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

Publication des migrations

publishesMigrations() permet de publier les fichiers de migration. Laravel met à jour automatiquement l’horodatage au moment de la publication.

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

Publication des vues

loadViewsFrom() — enregistrer un dossier de vues

loadViewsFrom() enregistre un dossier de vues. Le namespace passé en deuxième argument permet ensuite de référencer les vues sous la forme package::view.

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

Une fois enregistrée, chaque vue s’utilise via le namespace du package :

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

Laravel cherche les vues à deux emplacements : d’abord dans resources/views/vendor/courier de l’application, puis, à défaut, dans le dossier de vues du package. Cela permet aux utilisateurs de personnaliser les vues.

Publier les vues

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

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

Enregistrer des composants Blade

Si votre package fournit des composants Blade, enregistrez-les dans la méthode boot.

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

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

Vous pouvez également enregistrer un namespace entier de composants en une seule fois.

use Illuminate\Support\Facades\Blade;

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

{{-- Cas d'un enregistrement individuel --}}
<x-courier-alert />

{{-- Cas d'un enregistrement par namespace --}}
<x-courier::alert />

Publication des fichiers de traduction

loadTranslationsFrom() enregistre les fichiers de traduction. Les traductions se référencent sous la forme package::file.key.

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

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

// Utilisation d'une traduction
echo trans('courier::messages.welcome');

Pour des fichiers de traduction au format JSON, utilisez loadJsonTranslationsFrom().

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

Enregistrement des commandes

Les commandes Artisan du package sont enregistrées via la méthode commands(). Il est courant de ne les enregistrer que dans l’environnement 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,
        ]);
    }
}

Intégration à la commande `optimize`

Si le package possède son propre cache, la méthode optimizes() permet de l’intégrer aux commandes php artisan optimize et php artisan optimize:clear.

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

Ajouter des informations à la commande `about`

Pour ajouter des informations sur votre package dans la sortie de php artisan about, utilisez AboutCommand::add().

use Illuminate\Foundation\Console\AboutCommand;

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

Créer une façade

Les façades permettent d’appeler un binding du service container comme s’il s’agissait d’une méthode statique.

Créer la classe de service

<?php

namespace Acme\Courier;

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

    public function send(string $to, string $message): bool
    {
        // Traitement d'envoi du message
        return true;
    }

    public function track(string $id): array
    {
        // Récupération des informations de suivi
        return ['status' => 'delivered'];
    }
}

Créer la classe façade

Héritez de Illuminate\Support\Facades\Facade et renvoyez la clé du binding du service container depuis getFacadeAccessor().

<?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;
    }
}

Déclarer le binding dans le service provider

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

Déclarer la façade dans composer.json

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

En ajoutant des annotations PHPDoc @method aux méthodes de la façade, vous activez l’autocomplétion dans les IDE.

// Utilisation du service via la façade
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', 'Votre colis est arrivé');
$status = Courier::track('ABC-123');

DeferrableProvider — mettre en place le chargement différé

Un provider qui se contente d’enregistrer des bindings dans le service container peut être chargé de manière différée en implémentant l’interface DeferrableProvider. Le provider n’est chargé que lorsque le service est effectivement requis, ce qui améliore les performances de l’application.

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

    /**
     * Retourne la liste des services fournis par ce provider.
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravel compile et stocke la liste des services fournis par les deferred providers. Le provider n’est chargé qu’au moment où un des services listés dans provides() est résolu.

N’utilisez pas DeferrableProvider pour un provider qui doit enregistrer des ressources (vues, routes, écouteurs d’événements…). Si le provider est différé, ces ressources ne seront jamais enregistrées.

Tester un package

Pour tester un package indépendamment, utilisez Orchestra Testbench. Vous pourrez écrire les tests comme si vous étiez dans une application Laravel classique.

composer require --dev orchestra/testbench

Dans votre classe de test, surchargez getPackageProviders() pour enregistrer les service providers du package.

<?php

namespace Acme\Courier\Tests;

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

class TestCase extends BaseTestCase
{
    /**
     * Enregistre les service providers du package.
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * Enregistre les alias de façades du package.
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * Configuration d'environnement pour les tests.
     */
    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]', 'Message de test');

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

Publication sur Composer

Voici quelques bonnes pratiques pour publier votre package sur Packagist. Configuration de base du 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
}

En dépendant de illuminate/support plutôt que de illuminate/framework, vous n’importez que les composants de Laravel dont vous avez réellement besoin. Gardez l’arbre de dépendances de votre package aussi léger que possible.

Exemple de structure de répertoires

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── fr/
│       └── 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

Pages associées

Service providers

Revenez sur les méthodes register et boot des service providers et sur les deferred providers.

Gestion de la compatibilité entre versions

Découvrez les stratégies pour prendre en charge les montées de version majeures de Laravel et PHP ainsi que la configuration d’une matrice de tests GitHub Actions.

Développement IA

Patrons de conception