Cache d'un package et intégration à optimize

Lorsque votre package pré-génère ses propres métadonnées, demander simplement aux utilisateurs d’ajouter une commande dédiée à leur procédure de déploiement augmente le risque d’oubli lors des mises à jour. Avec ServiceProvider::optimizes(), vous pouvez intégrer les commandes de génération et de suppression aux commandes optimize et optimize:clear de Laravel. Cette page part des bases du développement de packages et examine l’implémentation de Laravel Framework v13.35.0. Elle ne traite pas du format des fichiers de cache, mais du contrat d’enregistrement et d’exploitation.

Distinguer l’enregistrement des commandes de celui des tâches

commands() enregistre les classes de commande que l’on peut appeler depuis Artisan. optimizes() est un traitement distinct qui enregistre, en tant que tâches d’optimisation, des noms de commandes déjà exécutables. Appeler uniquement la seconde méthode n’enregistre pas les classes de commande. L’exemple suivant suppose que votre package implémente déjà CacheMetadataCommand et ClearMetadataCommand, dont les $signature respectives sont courier:cache et courier:clear-cache.

<?php

namespace Acme\Courier;

use Acme\Courier\Console\Commands\CacheMetadataCommand;
use Acme\Courier\Console\Commands\ClearMetadataCommand;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->runningInConsole()) {
            $this->commands([
                CacheMetadataCommand::class,
                ClearMetadataCommand::class,
            ]);

            $this->optimizes(
                optimize: 'courier:cache',
                clear: 'courier:clear-cache',
                key: 'acme-courier',
            );
        }
    }
}

Tous les arguments de optimizes() sont nullables : vous pouvez donc enregistrer uniquement la génération ou uniquement la suppression. Indiquez toutefois toujours aux utilisateurs par quelle procédure le cache généré est invalidé.

La clé d’enregistrement fait aussi partie du contrat public

ServiceProvider stocke les commandes de génération dans le tableau statique $optimizeCommands et les commandes de suppression dans $optimizeClearCommands. Dans les deux cas, key sert de clé de tableau. Si vous omettez key, un nom est dérivé du nom de classe du provider. Par exemple, CourierServiceProvider donne courier. Comme seul le nom de classe est utilisé, deux providers homonymes situés dans des namespaces différents peuvent entrer en collision. Si vous enregistrez à nouveau la même clé, la commande correspondante est écrasée par la dernière valeur. Pour enregistrer plusieurs tâches, spécifiez des clés distinctes. Évitez également les clés des tâches standard de Laravel comme config ou routes : lorsque les tâches standard et celles des packages sont regroupées, une clé de chaîne identique est elle aussi écrasée.

Indiquez explicitement une clé qui identifie votre package, comme acme-courier, et conservez-la d’une version à l’autre. La clé devient le nom affiché de la tâche ainsi que la valeur que les utilisateurs passent à --except.

Exécution après les tâches standard

Dans l’implémentation examinée, les deux commandes déploient le tableau d’enregistrement des packages à la suite du tableau des tâches standard, puis les appellent dans l’ordre. Si vous utilisez une clé sans collision, les tâches de votre package sont ajoutées après les tâches standard.

Commande	Ordre d’exécution des tâches standard	Traitement suivant
`optimize`	`config:cache` → `event:cache` → `route:cache` → `view:cache`	Commandes de génération enregistrées
`optimize:clear`	`config:clear` → `cache:clear` → `clear-compiled` → `event:clear` → `route:clear` → `view:clear`	Commandes de suppression enregistrées

Compte tenu de cet ordre, votre commande de génération ne doit pas reconstruire les autres caches standard, mais uniquement les données dont votre package est propriétaire. N’utilisez pas optimizes() comme API pour contrôler l’ordre des dépendances entre plusieurs packages : si un ordre strict est nécessaire, enchaînez explicitement les commandes dédiées.

optimize:clear inclut aussi cache:clear, qui supprime les données du store de cache par défaut. Si vous voulez effacer uniquement le cache propre au package, exécutez directement courier:clear-cache. Concevez aussi la commande de suppression de votre package pour qu’elle ne vide pas l’intégralité d’un store partagé et ne supprime que les clés ou fichiers qui lui appartiennent.

Exclure par clé ou par nom de commande

L’option --except des deux commandes accepte des valeurs séparées par des virgules. Les espaces autour de chaque valeur sont supprimés, et les tâches dont la clé ou le nom de commande correspond sont exclues.

php artisan optimize --except=acme-courier
php artisan optimize --except=courier:cache
php artisan optimize:clear --except=acme-courier,cache

Les deux premières lignes excluent la même tâche de génération. La troisième exclut la tâche de suppression du package ainsi que la tâche standard cache:clear. cache est une clé de tâche, pas un nom propre à votre package. L’exclusion ne s’applique qu’à l’exécution en cours. Il ne s’agit pas d’un réglage qui désactive l’enregistrement du provider ou supprime automatiquement un cache de package créé auparavant.

Distinguer le FAIL d’une tâche du code de sortie de la commande parente

OptimizeCommand et OptimizeClearCommand appellent chaque tâche avec callSilently() et transmettent à l’affichage de la tâche le fait que le code de sortie vaut 0 ou non. La sortie normale des commandes enfants n’étant pas affichée, exécutez directement la commande dédiée pour enquêter sur la cause d’un problème. Dans Laravel v13.35.0, les deux méthodes handle() ne renvoient pas comme valeur de retour du parent le code non nul d’une commande enfant. Même si FAIL s’affiche à l’écran, la boucle continue et, en l’absence d’exception, le code de sortie de la commande parente est 0. En revanche, une exception levée est relancée par le composant d’affichage des tâches : le comportement n’est donc pas le même.

Ne considérez pas que la génération du cache de votre package a réussi au seul motif que php artisan optimize s’est terminé avec le code 0. Ce comportement repose sur l’implémentation de la version examinée : vérifiez-le à nouveau lorsque vous mettez à jour les versions de Laravel prises en charge.

Si la génération de votre package est une condition indispensable du déploiement, adoptez une procédure qui permet de vérifier directement le code de sortie de la commande enfant. Par exemple, la commande suivante exclut la tâche du package de l’exécution groupée et l’exécute directement une seule fois après les tâches standard.

php artisan optimize --except=acme-courier && php artisan courier:cache

Cet exemple répercute l’échec de courier:cache dans le code de sortie, mais n’agrège pas les codes non nuls des tâches standard. Pour un déploiement qui doit aussi détecter strictement les échecs des tâches standard, exécutez individuellement les commandes nécessaires et vérifiez leurs codes de sortie.

Concevoir et vérifier un cache robuste aux mises à jour

Au-delà de l’enregistrement, définissez aussi les responsabilités des commandes et du code qui lit le cache.

La génération, même répétée, aboutit au même état à partir des mêmes entrées, et un échec en cours de route ne doit pas activer des données incomplètes.
La suppression se termine normalement même si le cache n’existe pas, et ne supprime ni la configuration publiée par l’utilisateur ni les données persistantes.
Une commande dont la génération échoue signale l’erreur et renvoie un code non nul. Le code de lecture ne doit pas non plus considérer inconditionnellement un cache corrompu comme valide.
Si vous modifiez le format du cache, informez les utilisateurs de la nécessité de le régénérer et envisagez aussi de redémarrer les processus de longue durée.

En plus des tests du package, vérifiez les points suivants dans une application qui l’utilise. Les tableaux d’enregistrement étant statiques, faites aussi attention à l’état d’enregistrement qui persiste entre les tests d’un même processus.

Opération à vérifier	Critère de réussite
Exécuter directement les commandes dédiées de génération et de suppression	`0` en cas de succès, non nul en cas d’échec de la génération. Exécuter la suppression deux fois réussit
Exécuter `optimize` / `optimize:clear`	Les tâches du package sont appelées une fois chacune et l’état après génération ou suppression est correct
Spécifier `--except` avec la clé et le nom de commande	Seule la tâche ciblée n’est pas exécutée
Faire échouer la commande de génération avec un code non nul	Vous pouvez distinguer l’affichage `FAIL` du code de sortie de la commande parente dans la version examinée
Régénérer après une mise à jour du package	La génération utilise le nouveau code et la nouvelle configuration, et l’ancien format n’est plus lu

Pages associées

Fusion et cache de la configuration des packages

Le complément de la configuration publiée et son lien avec la reconstruction du cache de configuration.

Tester des packages Laravel avec Orchestra Testbench

Enregistrer des providers et des commandes Artisan dans l’environnement de test.

Développement IA

Patrons de conception

Développement de packages

Structure d'application

Nouveautés Laravel 13

Eloquent approfondi

Extension de la validation

Extension de l'authentification

Sécurité

Files d'attente

Tests

Temps réel

Cache d'un package et intégration à optimize

Distinguer l’enregistrement des commandes de celui des tâches

La clé d’enregistrement fait aussi partie du contrat public

Exécution après les tâches standard

Exclure par clé ou par nom de commande

Distinguer le FAIL d’une tâche du code de sortie de la commande parente

Concevoir et vérifier un cache robuste aux mises à jour

Pages associées

Fusion et cache de la configuration des packages

Tester des packages Laravel avec Orchestra Testbench

Sources primaires consultées

​Distinguer l’enregistrement des commandes de celui des tâches

​La clé d’enregistrement fait aussi partie du contrat public

​Exécution après les tâches standard

​Exclure par clé ou par nom de commande

​Distinguer le FAIL d’une tâche du code de sortie de la commande parente

​Concevoir et vérifier un cache robuste aux mises à jour

​Pages associées

Fusion et cache de la configuration des packages

Tester des packages Laravel avec Orchestra Testbench

​Sources primaires consultées

Distinguer l’enregistrement des commandes de celui des tâches

La clé d’enregistrement fait aussi partie du contrat public

Exécution après les tâches standard

Exclure par clé ou par nom de commande

Distinguer le FAIL d’une tâche du code de sortie de la commande parente

Concevoir et vérifier un cache robuste aux mises à jour

Pages associées

Sources primaires consultées