Les stubs sont des modèles de classe fournis avec Laravel. Ils sont utilisés en coulisses chaque fois que vous créez de nouveaux fichiers dans votre projet. Les stubs sont cachés par défaut, et je ne pense pas qu’ils soient suffisamment appréciés.
Il y a de fortes chances que si vous avez travaillé avec Laravel, vous ayez déjà utilisé une commande artisan make pour créer un nouveau modèle, un contrôleur ou un script de migration. Ce faisant, vous avez utilisé un stub pour créer un nouveau fichier.
Voyons comment fonctionnent les stubs. Comprendre leur fonctionnement interne nous aidera à mieux les utiliser.
Un exemple de stub
Puisqu’une image vaut mille mots, utilisons un simple stub fourni avec Laravel à titre d’exemple. Celui-ci sert de gabarit pour fabriquer de nouveaux modèles dans votre projet. Ce stub particulier est utilisé lorsque vous invoquez la commande artisan make:model.
Comme vous pouvez le voir, la majeure partie est du PHP assez simple.
Les exceptions sont {{ namespace }} et {{ class }}. Ce sont des balises de gabarit qui seront remplacées lorsque Laravel créera un nouveau fichier à partir de votre stub.
Ceux d’entre vous qui connaissent la commande artisan make:model sauront qu’au moins un argument supplémentaire doit être fourni à la commande : le nom du modèle !
Les stubs en action
Lorsque j’exécute la commande artisan make:model Example, le système génère le fichier suivant :
Vous remarquerez qu’il reflète le fichier du stub, mais qu’il a remplacé les balises du gabarit pour l’ namespace
et la class. Laravel a utilisé les informations que nous avons fournies sur la ligne de commande pour non seulement choisir le stub approprié, mais aussi pour calculer les valeurs des balises de gabarit.
Sors, sors, où que tu sois !
Au moment où nous écrivons ces lignes, Laravel est livré avec 43 fichiers stub individuels. Un fichier stub est utilisé à chaque fois qu’une des commandes artisan make est émise. Puisque ces fichiers sont inclus dans votre installation de Laravel, il est logique qu’ils résident par défaut dans notre dossier vendors.
En règle générale, le dossier vendors est l’endroit où sont stockées toutes tes dépendances PHP/Composer. Si vous utilisez un VCS (ex : Git, SVN… ) pour les fichiers de votre projet, c’est une bonne pratique d’exclure tout ce dossier. Les autres développeurs qui travaillent sur votre projet peuvent télécharger ta base de code, et simplement exécuter composer install pour télécharger toutes les mêmes dépendances.
Ceci étant dit, cela signifie que nous ne devrions jamais modifier ces fichiers. Pas d’inquiétude cependant, nous pouvons faire une copie en toute sécurité, stocker notre copie dans un dossier modifiable, et nous assurer que les internes de Laravel utiliseront notre version personnalisée. Pour ce faire, il suffit d’exécuter la commande artisan stub:publish.*
Une fois que vous avez lancé la commande de publication, vous remarquerez que des fichiers stub sont présents dans votre dossier /stubs (dossier qui sera automatiquement créé s’il n’existait pas déjà).
Ces fichiers peuvent être modifiés en toute sécurité et seront désormais utilisés à la place de ceux par défaut qui se trouvaient dans votre dossier /vendor.
Les prochaines mises à jour majeures de Laravel peuvent contenir des modifications des fichiers stub. Cela signifie que si vous mettez à jour votre version de Laravel après avoir publié et modifié les fichiers stub (ou tout autre fichier publié d’ailleurs), vous devriez envisager de republier et de réincorporer toutes les modifications que vous auriez pu faire à l’origine.
Tant de stubs
De nombreux stubs sont fournis avec Laravel. Il en existe pour les contrôleurs, les modèles et d’autres types de classes Laravel, si bien qu’il peut être difficile de savoir exactement quel stub est invoqué par quelle commande. J’ai compilé un tableau qui, je l’espère, vous aidera :
| Fichier stub | Commande artisan make |
|---|---|
| cast.inbound.stub | make:cast |
| cast.stub | make:cast |
| console.stub | make:command |
| controller.api.stub | make:controller --api |
| controller.invokable.stub | make:controller --invokable |
| controller.model.api.stub | make:controller --api --model |
| controller.model.stub | make:controller --model |
| controller.nested.api.stub | make:controller --api --parent=Parent |
| controller.nested.singleton.api.stub | make:controller --api --parent=Parent --singleton |
| controller.nested.singleton.stub | make:controller --parent=Parent --singleton |
| controller.nested.stub | make:controller --parent=Parent |
| controller.plain.stub | make:controller |
| controller.singleton.api.stub | make:controller --api --singleton |
| controller.singleton.stub | make:controller --singleton |
| controller.stub | make:controller |
| event.stub | make:event |
| factory.stub | make:factory |
| job.queued.stub | make:job --queued |
| job.stub | make:job |
| mail.stub | make:mail |
| markdown-mail.stub | make:mail --markdown |
| markdown-notification.stub | make:notification --markdown |
| middleware.stub | make:middleware |
| migration.create.stub | make:migration --create |
| migration.stub | make:migration |
| migration.update.stub | make:migration --update |
| model.pivot.stub | make:model --pivot |
| model.stub | make:model |
| notification.stub | make:notification |
| observer.plain.stub | make:observer |
| observer.stub | make:observer --plain |
| policy.plain.stub | make:policy |
| policy.stub | make:policy --plain |
| provider.stub | make:provider |
| request.stub | make:request |
| resource-collection.stub | make:resource --collection |
| resource.stub | make:resource |
| rule.stub | make:rule |
| scope.stub | make:scope |
| seeder.stub | make:seeder |
| test.stub | make:test |
| test.unit.stub | make:test --unit |
| view-component.stub | make:view-component |
Que faire ensuite ?
Vous savez maintenant ce que sont les fichiers stub, comment les publier et lesquels sont utilisés à quelles fins, mais vous vous demandez peut-être ce qu’il faut faire de ces informations. Bien que je ne puisse pas vous donner de réponse définitive (puisqu’un projet Laravel peut grandement différer d’un autre), je vais vous donner quelques scénarios avec des stubs pour vous inspirer à en faire bon usage.
Conventions d’appellation (de base)
Votre organisation utilise-t-elle des conventions de nommage différentes de celles que Laravel utilise généralement dans sa version prête à l’emploi ? Si c’est le cas, alors je vous recommande de mettre à jour vos stubs avec vos propres conventions de nommage. Chaque fois que vos développeurs créeront de nouveaux fichiers, ils commenceront avec vos conventions de nommage appropriées déjà en place. Si un fichier utilise déjà une convention de dénomination particulière, alors vos développeurs seront plus susceptibles de continuer à suivre le mouvement.
Modifications simples (de base)
J’ai travaillé sur un certain nombre de projets Laravel qui utilisaient le trait SoftDeletes dans à peu près tous les modèles. Il est vraiment facile d’ajouter des suppressions douces à vos modèles, mais c’est aussi quelque chose qu’il est facile d’oublier. Commencez-vous un nouveau projet dans lequel vous aurez besoin que les enregistrements soient supprimés en douceur dans chaque table ? Si c’est le cas, je vous recommande de mettre à jour votre model.stub pour y inclure le code de base pour la suppression douce des enregistrements. Une fois que vous l’aurez fait, tous les modèles ultérieurs créés via artisan make:model seront déjà équipés pour la suppression en douceur.
Nouveaux flux de travail (intermédiaire)
Certains systèmes sur lesquels nous avons travaillé nécessitent une connexion à une API externe, et dans certains de ces cas, nous finissons par créer plusieurs fichiers. Chacun d’entre eux interagissant avec une partie différente de l’API. Souvent, les fichiers séparés que nous créons ont des points communs ; lorsque nous faisons cela, nous finissons par créer notre propre commande artisan, qui, lorsqu’elle est exécutée, utilise notre propre stub personnalisé. Cela permet de gagner beaucoup de temps lorsque l’on collabore avec plusieurs développeurs. Il est généralement préférable que la personne qui connaît le flux de travail et l’API externe soit celle qui crée le nouveau stub et la nouvelle commande. De cette façon, les autres développeurs qui ne comprennent pas encore l’API externe ou le flux de travail peuvent utiliser le code standard d’une manière familière avec Laravel en un rien de temps.
Remplacer Artisan Make (avancé)
Il est même possible de remplacer ce qui se passe lorsqu’une commande artisan make est émise. Discuter de la façon de le faire dépasse le cadre de cet article, mais j’aimerais vous fournir un exemple de la façon dont cela peut être utilisé. Il est assez courant d’utiliser artisan make:model -a. Cela permet de créer un modèle, un contrôleur plein de ressources, une policy, quelques fichiers de request, un seeder, une factory et un script de migration de base de données. Nous avons étendu la commande pour créer également quelques fichiers Vue.js pour nous. L’un représente une vue de liste pour le nouveau modèle, et l’autre, une vue de détails. Ainsi, lorsque nous créons un nouveau module pour un projet sur lequel nous travaillons, nous pouvons avoir une liste fonctionnelle (bien que simple) et une vue détaillée en l’espace de quelques minutes – ce qui devient très intéressant !
Pour conclure
J’espère que vous avez une meilleure compréhension de ce que sont les Stubs et des améliorations qu’ils peuvent vous apporter à vous et votre équipe. Faites-nous savoir comment vous les utilisez dans votre projet et quel impact ils ont eu sur votre organisation.