Symfony 8.1 Console：剪贴板图片当命令入参、参数解析器、无 HTTP 内核

Symfony 8.1 稳定版于 2026 年 5 月底发布，最低要求 PHP 8.4。官方材料：

• New in Symfony 8.1: Improved Console Input
• New in Symfony 8.1: Console Argument Resolvers
• Console CHANGELOG（8.1 分支）
• PR #63293（图片输入）

1. 从终端粘贴图片作为命令入参

PR #63293，作者 Robin Chalas。当命令参数类型为 InputFile 且带 #[Ask] 属性时，question helper 会切换到文件输入模式：不再要求你敲路径，而是直接读终端里的图片粘贴事件。

支持的终端协议分两类：

• Kitty Graphics 协议：Kitty、Ghostty、Warp、Konsole、WezTerm、iTerm2
• iTerm2 inline images 协议：iTerm2、Windows Mintty、Rio 等

不支持图形协议的终端不会报错，而是优雅回退为只接受文件路径。Sixel 没有实现：多数 Sixel 终端同时支持 iTerm2 格式，而后者字节更少、全彩、无线程重处理。

新增的类与 API：

• InputFile
• FileQuestion
• InputFileValueResolver
• SymfonyStyle::askFile()
• InvalidFileException
• FileInputHelper
• Terminal/Image/ 下的 KittyGraphicsProtocol、ITerm2Protocol、ImageProtocolInterface

用法上，参数注入即可：

#[AsCommand('app:analyze')]
class AnalyzeCommand
{
    public function __invoke(
        #[Argument, Ask('Provide an image (paste it or enter a path):')]
        InputFile $image,
    ): int {
        // $image 来自粘贴的二进制或文件路径
        echo $image->getFilename();
        echo $image->getMimeType();
        echo $image->getHumanReadableSize();
        return 0;
    }
}

已知问题：PHPStorm 集成终端下不可用，这属于 PHPStorm 自身的问题，见 IDEA-127494、IJPL-196803。

2. Console 参数解析器

Console 8.1 引入了 argument resolvers，机制与 controller 的 argument resolver 相同，只是作用对象换成命令的参数与选项。内置解析器覆盖 backend enum、UUID/ULID 等类型；需要自定义时实现 ValueResolverInterface 即可。

#[AsCommand(name: 'app:report:generate')]
final class GenerateReportCommand
{
    public function __invoke(
        #[Argument, MapEntity] User $user,                        // 按主键解析实体
        // #[Argument, MapEntity(mapping: ['user' => 'email'])] User $user,
        #[Option, MapDateTime(format: 'Y-m-d')] \DateTimeInterface $date,
    ): int { /* ... */ }
}

执行：

php bin/console app:report:generate 42 --date=2026-05-08

42 会被 MapEntity 拿去数据库解析成 User，--date 选项则由 MapDateTime 转成 DateTimeInterface。除了实体和日期，__invoke() 还支持直接注入服务，并可用 #[Autowire]、#[Target] 控制注入行为。

8.1 的 Console 还包含 method-based commands、HTTP-less Symfony 应用、console argument resolvers 等改动。

3. 无 HTTP 内核

构建消息队列消费者、定时任务、AI 后台服务时，可以剥离 HTTP 组件启动应用。常驻进程不必加载完整的 HTTP 请求处理链路，启动更快、内存占用更低——这类进程本来也不处理请求。

同一版本还新增了多后端锁机制、RateLimit 注解、cURL 导出等。

BC BREAK

Console 的 #[Argument]、#[Option] 等属性在 8.1 有调整，升级前需要对照 CHANGELOG 检查现有命令的属性声明。