> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Présentation de laravel/chisel. Un package qui fournit des primitives pour construire des scripts post-installation supprimant les fonctionnalités inutiles d'un starter kit. Publié en v0.1 en mai 2026.

<Info>
  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).
</Info>

## Qu'est-ce que Laravel Chisel ?

[Laravel Chisel](https://github.com/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 ».

```mermaid theme={null}
graph TD
    A["Création du projet avec laravel new"] --> B["Installation du starter kit"]
    B --> C["Exécution du script chisel.php"]
    C --> D{"Questions à l'utilisateur<br>(multiselect)"}
    D --> E["Suppression / édition des fichiers<br>inutiles selon la sélection"]
    E --> F["Configuration finale du projet"]
```

## 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 theme={null}
<?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](https://laravel.com/docs/prompts) et transmet les réponses à Chisel.

```php theme={null}
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](/fr/advanced/php-ast).

| 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.

```php theme={null}
/* @chisel-passkeys */
Fortify::authenticateUsingPasskeys();
/* @end-chisel-passkeys */
```

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

```tsx theme={null}
{
    /* @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.

```mermaid theme={null}
graph LR
    A["/* @chisel-feature */<br>code<br>/* @end-chisel-feature */"] --> B{"L'utilisateur a-t-il<br>sélectionné feature ?"}
    B -->|removeSectionMarkers| C["Ne conserve que le code<br>(marqueurs supprimés)"]
    B -->|removeSection| D["Supprime les marqueurs<br>et le code"]
```

## 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](https://github.com/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.

<Card title="Dépôt laravel/chisel" icon="github" href="https://github.com/laravel/chisel">
  Le code source et la référence d'API la plus récente sont ici.
</Card>

<Card title="Documentation officielle des starter kits Laravel" icon="book-open" href="https://laravel.com/docs/starter-kits">
  Pour l'utilisation des starter kits eux-mêmes, consultez la documentation officielle.
</Card>


## Related topics

- [Installation](/fr/installation.md)
- [Créer un starter kit Laravel](/fr/advanced/starter-kit-creation.md)
- [PHP AST](/fr/advanced/php-ast.md)
- [Introduction à Svelte — bases pour l'utiliser avec Inertia × Laravel](/fr/blog/svelte-introduction.md)
- [Laravel Console Starter](/fr/packages/laravel-console-starter/index.md)