Cette page complète Développement de packages Laravel, Tester des packages Laravel avec Orchestra Testbench et Gestion de la compatibilité de versions de package. Ajouter de l’analyse statique à votre stratégie d’implémentation, de tests et de versionnage rend le package plus facile à maintenir sur le long terme.
Qu’est-ce que l’analyse statique
L’analyse statique consiste à détecter les incohérences de types et les bugs potentiels sans exécuter le code. Comme les packages Laravel utilisent beaucoup de mécanismes dynamiques (service container, façades, Eloquent), l’analyse statique attrape tôt des problèmes que les seuls tests d’exécution laissent passer. L’introduction de l’analyse statique offre en particulier les bénéfices suivants :- Sûreté de typage améliorée — les arguments ou valeurs de retour incorrects sont détectés avant la revue.
- Détection précoce des bugs — les appels à des méthodes inexistantes ou les oublis de nullable sont repérés avant les tests.
- Meilleure auto-complétion IDE — un PHPDoc soigné et l’usage des Generics améliorent la précision.
- Stabilité de la maintenance longue durée — plus facile de repérer ce qui casse à chaque montée de Laravel ou PHP.
Installer PHPStan
Commencez par mettre en place une base d’analyse avec PHPStan seul. PHPStan 2.x est plus strict qu’auparavant surmixed et les nullables, ce qui est aussi l’occasion de nettoyer l’API publique de votre package.
Analyser d'abord les répertoires ciblés directement
Pour un package, on commence souvent par
src et tests.Installer Larastan
Avec PHPStan seul, les spécificités Laravel (résolution via le container, façades, relations Eloquent) sont mal comprises. Utilisez donc Larastan, l’extension Laravel de PHPStan, en complément.Ajouter Larastan
Le package actuel s’appelle
larastan/larastan. Dans d’anciens articles, on trouve encore nunomaduro/larastan.Pour du développement de package, installer aussi Testbench
Larastan démarre le conteneur d’application Laravel pour résoudre les types. Pour analyser un package Laravel isolément,
orchestra/testbench peut être nécessaire.Configurer phpstan.neon
phpstan.neon centralise le niveau d’analyse, les chemins ciblés, les exclusions et les règles d’exception. Pour un package Laravel, plutôt que de viser 100 % dès le départ, il est plus réaliste de mettre en place une configuration que vous pourrez faire progresser.
Voici un exemple de phpstan.neon.
Choisir un niveau entre 0 et 9
PHPStan se met en place graduellement. Commencez par le niveau que votre code base peut supporter, puis augmentez-le au fur et à mesure des corrections.| Niveau | Étape adaptée |
|---|---|
| 0-3 | Réduire d’abord les appels de classes / fonctions / méthodes inconnues |
| 4-6 | Fiabiliser les arguments, valeurs de retour et types de propriétés de l’API publique |
| 7-9 | Traiter strictement nullable, union et mixed en phase de maintenance longue durée |
paths
paths déclare explicitement les répertoires à analyser. Pour un package, il est efficace d’inclure tests en plus de src, car les types y sont facilement bancals.
excludePaths
N’excluez que les endroits à faible valeur pour l’analyse statique : fichiers générés, caches, Workbench de vérification. Une exclusion trop large masque des erreurs que vous voudriez pourtant voir.
ignoreErrors
ignoreErrors est un dernier recours. Filtrez le message par regex et associez toujours un path pour limiter la portée. Cela facilite le retour arrière quand Laravel ou Larastan s’améliorent.
Annotations de type courantes
La précision de PHPStan et Larastan dépend beaucoup de la manière d’écrire les PHPDoc. Dans un package Laravel, il est particulièrement rentable de bien renseigner@param, @return, @var et les Generics (@template).
@param class-string<TModel>— indique que la chaîne n’est pas quelconque mais un nom de classe Model.@return TModel|null— indique quefind()retourne le type concret du modèle.@var Collection<int, TModel>— précise les types de clé et de valeur de la collection.@template TModel of Model— exprime un repository générique réutilisable.
Points d’attention propres à Laravel
La « magie pratique » de Laravel ne se transmet pas telle quelle à l’analyse statique. Il faut ajouter côté package des informations de type que l’outil peut comprendre.Façades
Pour une façade personnalisée, décrire les méthodes appelées par les utilisateurs en PHPDoc profite à la fois à l’IDE et à l’analyse statique.Méthodes magiques
Les API qui reposent sur__call() ou Macroable sont pratiques, mais fragiles pour le typage. Pour une API publique, ajouter des méthodes wrapper explicites — dont les arguments et le retour sont connus — est plus sûr.
Typage des modèles Eloquent
Pour les relations et propriétés dynamiques d’Eloquent, combiner@property et les Generics des relations est efficace.
Exécution automatique en CI
Exécutez l’analyse statique non seulement en local, mais toujours en CI. Pour un package qui prend en charge plusieurs versions de Laravel, appliquer la même approche que la matrice de tests de Gestion de la compatibilité de versions de package permet de surveiller simultanément la compatibilité et la sûreté de typage. Voici un exemple de.github/workflows/static-analysis.yml.
Faux positifs fréquents et comment les traiter
Face à un avertissement de l’analyse statique, demandez-vous d’abord s’il ne manque pas d’information de type. Ce qui ressemble à un faux positif n’est souvent qu’un PHPDoc incomplet.@phpstan-ignore-next-line
Utilisable comme contournement temporaire, mais réservez-le aux lignes dont vous pouvez expliquer la raison.
ignoreErrors
À considérer uniquement quand la même erreur apparaît à plusieurs endroits. Limitez toujours la portée avec un path et n’utilisez pas d’expression régulière trop lâche qui étoufferait tout.
Ordre de priorité des corrections
- Ajouter des PHPDoc.
- Déclarer explicitement les types de retour des façades et relations.
- Remplacer les
mixedpar des types concrets. - Ignorer seulement les faux positifs que vous pouvez expliquer.
Pages associées
Développement de packages Laravel
Passez en revue les fondations d’un package, service providers et ressources publiées.
Tester des packages Laravel avec Orchestra Testbench
Découvrez l’infrastructure de test à combiner avec l’analyse statique.
Gestion de la compatibilité de versions de package
Passez en revue la table de compatibilité Laravel / PHP et la stratégie de matrice GitHub Actions.