本文基于源代码调查整理。这是刚打上 v0.1 标签的早期开发阶段的包(截至 2026 年 5 月)。
什么是 Laravel Chisel
Laravel Chisel 是一个为构建安装后脚本提供原语的包,用来在 Laravel 启动套件中删除不需要的功能。
启动套件预装了很多功能,但根据项目情况,有些功能可能是多余的。Chisel 通过提供在安装后交互式地“只保留需要的功能”的机制来解决这个问题。
为什么需要它
Laravel 启动套件捆绑了大量功能,但并不是每个项目都需要所有这些功能。举例来说:
- 不需要邮件验证的项目
- 不使用 Passkey 认证的项目
- 不需要某些 Livewire 组件的构成
以前需要手动删除不需要的功能,而使用 Chisel,在安装时通过交互式提示就能完成定制。
chisel.php 脚本定义
使用 Chisel 的启动套件会在项目根目录放置一个 chisel.php 文件。这个文件定义了“哪些功能作为可选项”。
<?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) {
// 被选中时:去掉分段标记,保留代码
$c->files(
'resources/js/pages/settings/profile.tsx',
'app/Providers/FortifyServiceProvider.php',
)->removeSectionMarkers('email-verification');
},
else: function (Chisel $c) {
// 未被选中时:删除相关文件和功能
$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();
},
);
脚本定义方法
| 方法 | 说明 |
|---|
Chisel::script($directory) | 创建脚本定义 |
Question::multiselect(...) | 定义多选问题 |
questions([...]) | 设置脚本的问题 |
questions() | 获取已注册的问题 |
collectAnswers() | 开始收集问题的回答 |
apply($callback) | 注册无条件的变更步骤 |
selected($key, $value, then:, else:) | 按单个选中值分支 |
selectedAny($key, $values, then:, else:) | 任一值被选中时分支 |
selectedAll($key, $values, then:, else:) | 所有值都被选中时分支 |
chisel($answers) | 执行已注册的变更 |
交互式回答收集
collectAnswers() 会返回一个回答收集器。所有方法都是流式的,可以任意顺序调用。在非交互式环境下会自动使用默认值。
外部的 Artisan 命令使用 Laravel Prompts 来显示提示,并把回答传递给 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');
}
}
| 方法 | 说明 |
|---|
onQuestion($callback) | 设置问题提示的处理器 |
interactive($interactive) | 设置交互模式 |
withAnswers($answers) | 提供预先收集的回答以跳过提示 |
文件变更
用 file($path) 处理单个文件,用 files(...$paths) 处理多个文件。
| 方法 | 说明 |
|---|
replace($search, $replace) | 字符串替换 |
removeLinesContaining($content) | 删除包含指定字符串的行 |
removeSectionMarkers($tag) | 去掉分段标记但保留内容 |
removeSection($tag) | 删除分段标记及其中的内容 |
delete() | 删除目标文件 |
基于 PHP AST 的编辑
php($path) 提供基于 PHP AST 的编辑。当对象被销毁时,更改会自动保存。
关于 PHP AST(抽象语法树)基础与 nikic/php-parser 的使用方法,可以参考这里。
| 方法 | 说明 |
|---|
removeImport($class) | 删除 use 语句 |
removeTrait($trait) | 从类中删除 trait 的使用 |
removeInterface($interface) | 删除已实现的 interface |
Section Markers
用一对注释包裹可选的代码。
/* @chisel-passkeys */
Fortify::authenticateUsingPasskeys();
/* @end-chisel-passkeys */
{})包裹的块注释。
{
/* @chisel-passkeys */
}
<PasskeyButton />;
{
/* @end-chisel-passkeys */
}
removeSectionMarkers('passkeys') — 删除标记但保留代码removeSection('passkeys') — 标记和代码一起删除
chisel- 前缀会自动添加。
npm 支持
| 方法 | 说明 |
|---|
npm()->install() | 用检测到的包管理器安装依赖 |
npm()->run($script, ...$arguments) | 执行包管理器的脚本 |
npm()->remove(...$packages) | 用检测到的包管理器删除包 |
npm() 方法会自动检测 npm、yarn、pnpm、bun。
当前开发状态
Chisel 不是终端用户直接安装到 Laravel 应用中的包,而是启动套件内部使用的库。未来 Laravel 官方启动套件预计会基于 Chisel 提供安装后脚本。
laravel/chisel 仓库
源代码和最新的 API 参考请查看这里。
Laravel 启动套件官方文档
启动套件本身的使用方法请参考官方文档。
