Laravel Chisel — la bibliothèque de scripts post-installation des starter kits

Cet article s’appuie sur une exploration du code source. Il s’agit d’un package en tout début de développement, dont le tag v0.1 vient d’être posé (à la date de mai 2026).

Qu’est-ce que Laravel Chisel ?

Laravel Chisel est un package qui fournit des primitives pour construire des scripts post-installation destinés à supprimer les fonctionnalités inutiles d’un starter kit Laravel. Un starter kit embarque beaucoup de fonctionnalités prêtes à l’emploi, mais selon le projet, certaines d’entre elles peuvent être inutiles. Chisel résout ce problème en proposant, après l’installation, un mécanisme interactif permettant de « ne conserver que les fonctionnalités nécessaires ».

Pourquoi c’est utile

Les starter kits Laravel regroupent beaucoup de fonctionnalités, mais aucun projet n’a besoin de toutes les avoir. Par exemple :

Projets qui n’ont pas besoin de vérification par e-mail
Projets qui n’utilisent pas l’authentification par passkey
Configurations où certains composants Livewire sont superflus

Jusqu’ici, il fallait supprimer manuellement ces fonctionnalités ; avec Chisel, la personnalisation se fait via des prompts interactifs au moment de l’installation.

Définition du script chisel.php

Un starter kit qui utilise Chisel place un fichier chisel.php à la racine du projet. Ce fichier définit « quelles fonctionnalités sont optionnelles ».

<?php

require getenv('LARAVEL_INSTALLER_AUTOLOADER');

use Laravel\Chisel\Chisel;
use Laravel\Chisel\Question;

return Chisel::script(dirname(__DIR__))
    ->questions([
        Question::multiselect(
            name: 'auth_features',
            label: 'Which authentication features would you like to enable?',
            options: [
                'email-verification' => 'Email verification',
            ],
            hint: 'Use space to select, enter to confirm.',
        ),
    ])
    ->selected('auth_features', 'email-verification',
        then: function (Chisel $c) {
            // Cas sélectionné : on retire les marqueurs et on garde le code
            $c->files(
                'resources/js/pages/settings/profile.tsx',
                'app/Providers/FortifyServiceProvider.php',
            )->removeSectionMarkers('email-verification');
        },
        else: function (Chisel $c) {
            // Cas non sélectionné : on supprime les fichiers et fonctionnalités liés
            $c->php('app/Models/User.php')
                ->removeImport('Illuminate\Contracts\Auth\MustVerifyEmail')
                ->removeInterface('MustVerifyEmail');

            $c->file('config/fortify.php')->removeLinesContaining('Features::emailVerification()');

            $c->files(
                'app/Providers/FortifyServiceProvider.php',
                'resources/js/pages/settings/profile.tsx',
            )->removeSection('email-verification');

            $c->files(
                'resources/js/components/email-verification-notice.tsx',
                'resources/js/pages/auth/verify-email.tsx',
                'tests/Feature/Auth/EmailVerificationTest.php',
                'tests/Feature/Auth/VerificationNotificationTest.php',
            )->delete();
        },
    );

Méthodes de définition du script

Méthode	Description
`Chisel::script($directory)`	Crée une définition de script
`Question::multiselect(...)`	Définit une question à choix multiples
`questions([...])`	Configure les questions du script
`questions()`	Récupère les questions enregistrées
`collectAnswers()`	Démarre la collecte des réponses aux questions
`apply($callback)`	Enregistre une étape de mutation inconditionnelle
`selected($key, $value, then:, else:)`	Branche sur une valeur sélectionnée unique
`selectedAny($key, $values, then:, else:)`	Branche si l’une des valeurs est sélectionnée
`selectedAll($key, $values, then:, else:)`	Branche si toutes les valeurs sont sélectionnées
`chisel($answers)`	Exécute les mutations enregistrées

Collecte interactive des réponses

collectAnswers() retourne un collecteur de réponses. Toutes les méthodes sont fluent et peuvent être appelées dans n’importe quel ordre. En environnement non interactif, les valeurs par défaut sont utilisées automatiquement. Une commande Artisan externe affiche les prompts à l’aide de Laravel Prompts et transmet les réponses à Chisel.

use Illuminate\Console\Command;
use Laravel\Chisel\Chisel;
use Laravel\Chisel\Question;
use RuntimeException;

use function Laravel\Prompts\multiselect;

class InstallFeatures extends Command
{
    protected $signature = 'install:features
        {--answers= : JSON string of answers to skip interactive prompts}';

    public function handle(): void
    {
        $script = require base_path('chisel.php');

        $providedAnswers = $this->option('answers') === null
            ? []
            : json_decode((string) $this->option('answers'), true, 512, JSON_THROW_ON_ERROR);

        $answers = $script
            ->collectAnswers()
            ->onQuestion(fn (Question $question) => match ($question->type) {
                'multiselect' => multiselect(
                    label: $question->label,
                    options: $question->options,
                    default: $question->default ?? [],
                    required: $question->required,
                    hint: $question->hint,
                ),
                default => throw new RuntimeException("Unsupported question type [{$question->type}]."),
            })
            ->interactive($this->input->isInteractive())
            ->withAnswers($providedAnswers);

        $script->chisel($answers);

        $chisel = Chisel::in(base_path());

        $chisel->npm()->install();
        $chisel->npm()->run('build');
    }
}

Méthode	Description
`onQuestion($callback)`	Définit le handler des prompts de questions
`interactive($interactive)`	Active/désactive le mode interactif
`withAnswers($answers)`	Fournit des réponses préalables pour sauter les prompts

Mutations de fichiers

file($path) cible un fichier unique et files(...$paths) plusieurs fichiers.

Méthode	Description
`replace($search, $replace)`	Remplace une chaîne
`removeLinesContaining($content)`	Supprime les lignes contenant la chaîne donnée
`removeSectionMarkers($tag)`	Retire les marqueurs de section en conservant le contenu
`removeSection($tag)`	Supprime les marqueurs et le contenu qu’ils délimitent
`delete()`	Supprime le fichier cible

Édition basée sur l’AST PHP

php($path) fournit une édition basée sur l’AST PHP. Les modifications sont sauvegardées automatiquement lorsque l’objet est libéré. Les bases de l’AST PHP (arbre syntaxique abstrait) et l’utilisation de nikic/php-parser sont expliquées ici.

Méthode	Description
`removeImport($class)`	Supprime une instruction `use`
`removeTrait($trait)`	Supprime l’utilisation d’un trait dans une classe
`removeInterface($interface)`	Supprime une interface implémentée

Marqueurs de section

Encadrez le code optionnel avec une paire de commentaires.

/* @chisel-passkeys */
Fortify::authenticateUsingPasskeys();
/* @end-chisel-passkeys */

Dans les fichiers JSX, utilisez des commentaires en bloc avec des accolades ({}).

{
    /* @chisel-passkeys */
}
<PasskeyButton />;
{
    /* @end-chisel-passkeys */
}

removeSectionMarkers('passkeys') — supprime les marqueurs, conserve le code
removeSection('passkeys') — supprime à la fois les marqueurs et le code

Le préfixe chisel- est ajouté automatiquement.

Support npm

Méthode	Description
`npm()->install()`	Installe les dépendances avec le gestionnaire de paquets détecté
`npm()->run($script, ...$arguments)`	Exécute un script du gestionnaire de paquets
`npm()->remove(...$packages)`	Supprime des paquets avec le gestionnaire détecté

La méthode npm() détecte automatiquement npm, yarn, pnpm et bun.

État actuel du développement

Dépôt GitHub : laravel/chisel
Release : v0.1 (publié en mai 2026)
Historique : rendu public après trois mois de développement privé

Chisel n’est pas un package que l’utilisateur final installe directement dans son application Laravel : c’est une bibliothèque utilisée en interne par les starter kits. À terme, on peut s’attendre à ce que les starter kits officiels Laravel proposent des scripts post-installation basés sur Chisel.

Dépôt laravel/chisel

Le code source et la référence d’API la plus récente sont ici.

Documentation officielle des starter kits Laravel

Pour l’utilisation des starter kits eux-mêmes, consultez la documentation officielle.

​Qu’est-ce que Laravel Chisel ?

​Pourquoi c’est utile

​Définition du script chisel.php

​Méthodes de définition du script

​Collecte interactive des réponses

​Mutations de fichiers

​Édition basée sur l’AST PHP

​Marqueurs de section

​Support npm

​État actuel du développement

Dépôt laravel/chisel

Documentation officielle des starter kits Laravel

Qu’est-ce que Laravel Chisel ?

Pourquoi c’est utile

Définition du script chisel.php

Méthodes de définition du script

Collecte interactive des réponses

Mutations de fichiers

Édition basée sur l’AST PHP

Marqueurs de section

Support npm

État actuel du développement