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

# Ajouter des informations de diagnostic du package à about

> Découvrez comment utiliser AboutCommand dans Laravel 13 pour afficher l'état de configuration de votre package en CLI et en JSON, ainsi que le moment d'évaluation et les points à surveiller pour la maintenance à long terme.

Lorsqu'un utilisateur vous contacte, il est utile de pouvoir vérifier dans un format uniforme si le package est activé ou désactivé et quel driver est sélectionné. Avec `AboutCommand::add()`, vous pouvez ajouter une section dédiée à votre package dans la sortie de `php artisan about` sans implémenter de commande spécifique.

La documentation officielle fournit un exemple de base de l'enregistrement. Cette page examine l'implémentation de Laravel 13 et approfondit le moment où les informations sont collectées, les types JSON, les collisions de noms de section et l'état de l'enregistrement dans les tests.

## Enregistrer le contenu affiché dans le provider

L'exemple suivant suppose que `courier.enabled` et `courier.driver` sont déjà enregistrés dans la configuration du package. Pour savoir comment enregistrer la configuration, consultez [Fusion et cache de la configuration des packages](/fr/advanced/package-config-merging).

```php theme={null}
<?php

namespace Acme\Courier;

use Illuminate\Foundation\Console\AboutCommand;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if (! $this->app->runningInConsole()) {
            return;
        }

        AboutCommand::add('Acme Courier', fn () => [
            'Enabled' => AboutCommand::format(
                (bool) config('courier.enabled', false),
                console: fn (bool $enabled) => $enabled ? 'ENABLED' : 'OFF',
            ),
            'Driver' => (string) config('courier.driver', 'log'),
        ]);
    }
}
```

`runningInConsole()` est une condition qui évite un enregistrement inutile lors des requêtes HTTP. Elle ne détecte pas uniquement l'exécution de `about` : l'enregistrement a aussi lieu pour les autres commandes Artisan. En revanche, la lecture de la configuration dans la closure ci-dessus n'est pas exécutée au moment de l'enregistrement.

<Warning>
  Choisissez explicitement les éléments à afficher. N'affichez pas de clés d'API, de jetons d'accès, d'URL de connexion contenant des identifiants ni de tableaux de configuration entiers. La sortie JSON ne masque pas non plus automatiquement les informations secrètes. Lors d'une demande d'assistance, demandez à l'utilisateur de ne partager que la section du package et de vérifier son contenu avant de la transmettre.
</Warning>

## Distinguer le moment de l'enregistrement de celui de l'évaluation

Dans Laravel `v13.35.0`, `add()` ne collecte pas les données immédiatement : la méthode ajoute une closure d'enregistrement au tableau statique `$customDataResolvers`. Lors de l'exécution de `about`, les données à afficher sont assemblées et les closures de récupération de données enregistrées sont évaluées.

```mermaid theme={null}
flowchart TD
    A["boot() du provider"] --> B["add() conserve l'enregistrement"]
    B --> C["Exécution de about"]
    C --> D["Collecte des informations standard et des sections ajoutées"]
    D --> E["Évaluation des closures de récupération de données"]
    E --> F["Filtrage des sections avec --only"]
    F --> G["Affichage en CLI ou en JSON"]
```

Lire les valeurs de configuration dans la closure permet de refléter l'état au moment de l'exécution de la commande, plutôt que de les lire à l'avance en dehors de `add()` et de les figer dans un tableau. En revanche, le filtre `--only` est appliqué **après** l'évaluation des closures de récupération de données.

```bash theme={null}
php artisan about --only=environment
```

Même si vous ne demandez qu'une section standard comme ici, la closure `Acme Courier` ci-dessus est évaluée. Ne pas être affiché ne signifie pas ne pas être exécuté.

C'est pourquoi les informations ajoutées doivent provenir de valeurs de configuration ou d'un état local léger. Si vous y placez des vérifications de connectivité vers une API externe, des requêtes en base de données ou des modifications de fichiers, même une commande qui consulte une section sans rapport peut devenir lente ou échouer. Placez les vérifications de connectivité et les réparations dans des commandes Artisan dédiées.

<Tip>
  La condition `runningInConsole()` seule ne garantit pas que le `boot()` d'un service provider différé soit exécuté. Si vous voulez que les informations de diagnostic soient toujours enregistrées, placez cet enregistrement dans un provider chargé immédiatement. Pour une configuration où seules les liaisons de services sont différées, consultez [Service providers différés](/fr/advanced/deferred-provider).
</Tip>

## Concilier l'affichage CLI et les types JSON

Pour n'afficher que les informations du package, indiquez le nom de la section converti en minuscules et en snake case. Pour `Acme Courier`, il s'agit de `acme_courier`.

```bash theme={null}
php artisan about --only=acme_courier
php artisan about --only=environment,acme_courier
php artisan about --only=acme_courier --json
```

Avec l'exemple d'enregistrement ci-dessus, lorsque `courier.enabled` vaut `true` et `courier.driver` vaut `log`, le JSON prend la forme suivante.

```json theme={null}
{
  "acme_courier": {
    "enabled": true,
    "driver": "log"
  }
}
```

En CLI, `Enabled` est affiché sous la forme `ENABLED`. `AboutCommand::format()` est un helper qui permet de spécifier `console` pour la CLI et `json` pour le JSON. L'exemple ci-dessus ne spécifie que `console` : le JSON renvoie donc la valeur booléenne d'origine. Il n'est pas nécessaire de réutiliser telle quelle la chaîne affichée en CLI dans le JSON.

| Élément | Conversion et traitement dans l'implémentation |
| - | - |
| Valeur de `--only` et nom de section | Comparés après conversion en minuscules puis en snake case |
| Clé de section JSON | Nom de section converti en snake case |
| Clé d'élément JSON | Nom d'élément converti en minuscules puis en snake case |
| Valeur de `format()` | `console` en CLI, `json` en JSON. Valeur d'origine si non spécifié |

Utiliser, comme dans l'exemple, des noms composés de mots anglais ordinaires séparés par des espaces facilite la manipulation des filtres et des clés JSON. Les clés utilisées par des traitements automatisés peuvent changer si vous modifiez le nom affiché : vérifiez la compatibilité à chaque version.

## Donner aux sections un nom propre au package

`add()` ajoute des éléments à la même section. Indiquer une section du même nom ne remplace pas l'intégralité du contenu enregistré précédemment.

Choisissez un nom qui se distingue des autres packages, comme `Acme Courier`, et limitez les ajouts aux sections standard de Laravel `Environment`, `Cache`, `Drivers` et `Storage` aux cas où ils sont nécessaires.

Si vous enregistrez plusieurs fois un élément du même nom dans une même section, il peut subsister sur plusieurs lignes en CLI, tandis qu'en JSON les entrées sont regroupées sous la même clé et seule la dernière valeur est conservée. Évitez également des noms qui, bien qu'écrits différemment, aboutissent à la même clé après conversion en snake case. Regroupez l'enregistrement en un seul endroit et concevez des éléments uniques aussi bien en CLI qu'en JSON.

## Gérer l'état d'enregistrement statique dans les tests

Au début de l'exécution de `about`, les données d'affichage `$data` sont réinitialisées, mais la liste des enregistrements d'informations ajoutées `$customDataResolvers` est conservée. Cela permet de recollecter les informations à partir des mêmes enregistrements à chaque fois, mais si le `boot()` du provider est exécuté plusieurs fois dans le même processus PHP, les enregistrements peuvent s'accumuler.

`AboutCommand::flushState()` est une méthode qui efface **les enregistrements de tous les packages** ainsi que les données d'affichage. Ne l'appelez pas dans un provider de production pour éviter les doublons dans votre propre section : vous perdriez aussi les informations de diagnostic des autres packages.

Si vous reconstruisez l'application avec votre propre infrastructure de test, déterminez à qui revient la responsabilité de réinitialiser l'état entre les tests. Si vous réinitialisez, faites-le avant de démarrer le provider concerné, puis effectuez tous les enregistrements nécessaires. Vérifiez également si votre infrastructure de test existante réinitialise déjà cet état.

### Points à vérifier avant une version

Vérifiez les combinaisons suivantes avec [Tester des packages Laravel avec Orchestra Testbench](/fr/advanced/package-testing) et dans une véritable application utilisatrice.

| Opération à vérifier | Résultat attendu |
| - | - |
| `about --only=acme_courier` | Seule la section du package est affichée, sans éléments en double |
| `about --only=acme_courier --json` | `enabled` est obtenu sous forme de booléen et `driver` sous forme de chaîne |
| `about --only=environment` | La collecte d'informations du package n'effectue aucune communication externe ni effet de bord, et la commande se termine normalement |
| Modification de l'activation ou du driver | Les valeurs affichées et les valeurs JSON correspondent à la configuration au moment de l'exécution de la commande |
| Deux exécutions dans la même application | Les éléments ne s'accumulent pas et les informations sont recollectées à chaque exécution |
| Reconstruction de l'application dans le même processus PHP | L'état d'enregistrement ne fuit pas entre les tests et les informations des autres packages ne disparaissent pas |
| Avec un cache de configuration | Les valeurs affichées sont celles réellement utilisées par l'application, et non le contenu du fichier de configuration publié |

## Pages associées

<Columns cols={2}>
  <Card title="Développement de packages Laravel" icon="box" href="/fr/advanced/package-development">
    Revoyez les bases des providers et de l'enregistrement des ressources.
  </Card>

  <Card title="Fusion et cache de la configuration des packages" icon="sliders" href="/fr/advanced/package-config-merging">
    Comprenez la relation entre valeurs par défaut, surcharges des utilisateurs et cache de configuration.
  </Card>
</Columns>

## Sources primaires consultées

* [Documentation officielle de Laravel : ajouter des informations à about depuis un package](https://github.com/laravel/docs/blob/13.x/packages.md#about-artisan-command)
* [Documentation officielle de Laravel : about et --only](https://github.com/laravel/docs/blob/13.x/configuration.md#the-about-command)
* [Laravel Framework v13.35.0 : AboutCommand](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/AboutCommand.php) : enregistrement, ordre d'évaluation, conversion des clés, `format()`, `flushState()`.
* [Laravel Framework v13.35.0 : tests de format](https://github.com/laravel/framework/blob/v13.35.0/tests/Foundation/Console/AboutCommandTest.php)
* [Laravel Framework v13.35.0 : tests d'intégration de la sortie JSON](https://github.com/laravel/framework/blob/v13.35.0/tests/Integration/Foundation/Console/AboutCommandTest.php)


## Related topics

- [Développement de packages Laravel](/fr/advanced/package-development.md)
- [Laravel Doctor — l'outil de diagnostic d'application](/fr/blog/laravel-doctor-introduction.md)
- [Présentation du package Blaze](/fr/blog/blaze-introduction.md)
- [Analyse statique de packages (PHPStan / Larastan)](/fr/advanced/package-static-analysis.md)
- [Fonctionnement interne de la découverte automatique des packages](/fr/advanced/package-discovery.md)


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