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 quecourier.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.
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.
Distinguer le moment de l’enregistrement de celui de l’évaluation
Dans Laravelv13.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.
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.
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.
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. PourAcme Courier, il s’agit de acme_courier.
courier.enabled vaut true et courier.driver vaut log, le JSON prend la forme suivante.
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.
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 deabout, 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 et dans une véritable application utilisatrice.Pages associées
Développement de packages Laravel
Revoyez les bases des providers et de l’enregistrement des ressources.
Fusion et cache de la configuration des packages
Comprenez la relation entre valeurs par défaut, surcharges des utilisateurs et cache de configuration.
Sources primaires consultées
- Documentation officielle de Laravel : ajouter des informations à about depuis un package
- Documentation officielle de Laravel : about et —only
- Laravel Framework v13.35.0 : AboutCommand : enregistrement, ordre d’évaluation, conversion des clés,
format(),flushState(). - Laravel Framework v13.35.0 : tests de format
- Laravel Framework v13.35.0 : tests d’intégration de la sortie JSON