> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache d'un package et intégration à optimize

> Utilisez optimizes() de Laravel 13 pour intégrer au déploiement la génération et la suppression du cache propre à votre package. À partir de l'implémentation, découvrez les clés d'enregistrement, les exclusions, l'ordre d'exécution et les codes de sortie en cas d'échec.

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](/fr/advanced/package-development) 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 theme={null}
<?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.

<Tip>
  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`.
</Tip>

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

```mermaid theme={null}
flowchart TD
    A["boot() du provider"] --> B["Enregistrement des commandes Artisan avec commands()"]
    A --> C["Enregistrement de la clé et du nom de commande avec optimizes()"]
    B --> D["php artisan optimize"]
    C --> D
    D --> E["Mise en cache standard de la configuration, des événements, des routes et des vues"]
    E --> F["Exécution de courier:cache"]
    C --> G["php artisan optimize:clear"]
    G --> H["Suppression des caches standard"]
    H --> I["Exécution de courier:clear-cache"]
```

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.

<Warning>
  `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.
</Warning>

## 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.

```bash theme={null}
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.

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

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.

```bash theme={null}
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

<Columns cols={2}>
  <Card title="Fusion et cache de la configuration des packages" icon="sliders" href="/fr/advanced/package-config-merging">
    Le complément de la configuration publiée et son lien avec la reconstruction du cache de configuration.
  </Card>

  <Card title="Tester des packages Laravel avec Orchestra Testbench" icon="flask" href="/fr/advanced/package-testing">
    Enregistrer des providers et des commandes Artisan dans l'environnement de test.
  </Card>
</Columns>

## Sources primaires consultées

* [Documentation officielle de Laravel : Optimize commands](https://github.com/laravel/docs/blob/13.x/packages.md#optimize-commands)
* [ServiceProvider : optimizes() et clés d'enregistrement](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Support/ServiceProvider.php)
* [OptimizeCommand : tâches et exclusions](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/OptimizeCommand.php)
* [OptimizeClearCommand : tâches de suppression et ordre d'exécution](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/OptimizeClearCommand.php)
* [Command : valeur de retour de handle() et code de sortie](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Console/Command.php)
* [Task : affichage du résultat et relance des exceptions](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Console/View/Components/Task.php)


## Related topics

- [Développement de packages Laravel](/fr/advanced/package-development.md)
- [Sujets avancés](/fr/advanced/index.md)
- [Enregistrement et cache des routes d'un package](/fr/advanced/package-routes.md)
- [Surcharger et mettre à jour les vues d'un package](/fr/advanced/package-views.md)
- [Publier et mettre à jour les migrations d'un package](/fr/advanced/package-migrations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.