Snippets - Introduction à Laravel Snippets

Laravel Snippets est un rendu statique de la documentation Laravel 13.x dont chaque bloc de code PHP est exécutable. PHP 8.5 démarre dans un web worker, charge un bundle Laravel 13 et exécute chaque exemple directement dans votre navigateur. Aucun code n'est exécuté sur un serveur.

Pour l'essayer sans plus attendre, rendez-vous sur ce lien.

Laravel Snippets est une démonstration de ce que permettent les snippets PHP.wasm, et non une ressource officielle de Laravel. Un grand merci à l'équipe Laravel pour son travail et sa documentation remarquables.

La documentation de Laravel est un plaisir à lire, et elle regorge de code. Mais ce code est figé. On lit ->groupBy(), on se représente la forme du résultat, et pour la voir vraiment, il faut copier l'exemple dans un projet, l'adapter, l'exécuter, et ce n'est qu'alors qu'on découvre si l'image qu'on s'en faisait était juste. Entre le paragraphe et la réponse, il y a tout un aller-retour.

Il y a deux ans, j'écrivais Lancer Laravel depuis son navigateur avec BrowserPHP et me demandait comment un script PHP pouvait s'exécuter côté client. Laravel Snippets, c'est la même question posée à nouveau, sur une page qu'on consulte déjà chaque semaine : et si chaque exemple s'exécutait là où on le lit ?

Chaque exemple s'exécute

Chaque bloc ```php de la documentation devient un snippet muni d'un bouton Run. Le résultat s'affiche sous le code, en conservant les couleurs de dump() et la mise en forme des erreurs propre au framework. Le premier lancement démarre PHP, tous les suivants sont instantanés.

Les snippets sont modifiables

Le bloc de code se modifie sur place. Changez une valeur, ajoutez un ->map(), relancez, puis cliquez sur reset pour revenir à la version de la documentation. L'exemple devient un petit bac à sable, sans quitter la page.

Un vrai Laravel sous le capot

Au démarrage, le worker décompresse un bundle du framework Laravel 13, si bien que Illuminate\Support\Collection, dump(), Lang::get() et consorts se résolvent comme ils le feraient dans un projet. Le bundle embarque également un jeu de modèles User, Post, Flight, Order car la documentation y fait constamment référence, et un exemple incapable de résoudre App\Models\User ne peut pas s'exécuter.

Toujours à jour

Laravel Snippets suit la documentation au lieu d'en figer une copie. Un workflow planifié réplique chaque jour le dépôt markdown laravel/docs en amont. Un second récupère chaque jour le CSS compilé et les polices de Laravel, afin que les pages conservent la typographie de l'original. Chaque synchronisation réussie republie le site statique sur GitHub Pages.

Le rapport

Une fois chaque exemple rendu exécutable, une seconde question se pose d'elle-même : combien d'entre eux s'exécutent réellement ?

Un workflow y répond. Playwright charge chaque page prérendue, fait passer tous les snippets par le worker PHP.wasm et consigne le résultat dans l'une des six catégories : ran-ok, ran-with-stderr, ran-exit-nonzero, worker-error, no-output, never-completed. Le balayage a lieu chaque semaine, puis de nouveau à chaque modification du runtime ou des sources markdown. Le rapport présente les totaux, un récapitulatif page par page, et chacun des snippets avec son entrée et sa sortie.

Deux tiers s'exécutent sans accroc. Le tiers restant mérite une mise en garde, car une cellule rouge n'est pas un bug de la documentation. Il n'y a pas de base de données derrière le navigateur, pas de clé Stripe, pas de Sanctum, pas de Pennant. Et une grande partie du code de la documentation n'a jamais été conçue pour être exécutée : un tableau de configuration, un corps de classe sans sa classe. Ces blocs échouent par nature.

Par où commencer

Il n'y a rien à installer.

1. Accédez au projet GitHub ou ouvrez la démo en ligne.

2. Choisissez une page dans la barre latérale.

3. Cliquez sur Run sur n'importe quel snippet.

4. Modifiez le code et relancez-le.

5. Ouvrez le rapport pour voir ce qui échoue actuellement, et où.