在 symfony 6.x 中编写安全可用的 twig 扩展必须满足三要素：类继承 abstractextension、服务打上 twig.extension 标签、getfilters() 或 getfunctions() 返回正确包装的 twigfilter/twigfunction 实例；过滤器方法需手动类型校验、避免副作用、防越界，并确保服务配置、路径、命名与缓存清理全部正确。
在 Symfony 6.x 中写 Twig 扩展，不是“写个方法再注册”就完事——必须满足三件事：类继承 AbstractExtension、服务打上 twig.extension 标签、getFilters() 或 getFunctions() 返回正确包装的 TwigFilter / TwigFunction 实例。缺一环，模板里调用就报 Unknown filter 或 Unknown function。
怎么定义一个安全可用的过滤器方法
方法本身要能扛住 Twig 传来的任意类型，不能依赖 PHP 类型声明自动兜底（Twig 不走严格类型检查）：
- 参数用
string $text声明是好的，但还得手动判断：if (!is_string($text)) { return ''; } - 空字符串、
null、数字、数组都可能进来，尤其从表单或 API 接口直接传参时 - 避免在过滤器里做数据库查询、HTTP 请求或文件读写——它被设计为同步、无副作用的数据转换
- 示例截断逻辑要防
substr越界：if (strlen($text) ，否则返回空或乱码
为什么 getFilters() 返回的 TwigFilter 必须用 [$this, 'methodName'] 格式
这是 Symfony 容器绑定实例方法的唯一可靠方式，其他写法会失败：
-
[$this, 'truncateText']✅ 正确：绑定当前扩展实例的方法 -
'truncateText'❌ 错误：PHP 会尝试找全局函数，找不到就报错 -
fn($text) => ...❌ 错误：匿名函数无法序列化，缓存编译时报错 -
[MyCustomExtension::class, 'truncateText']❌ 错误：静态调用不共享实例状态，且 Twig 环境等依赖不可用
另外注意：Symfony 6.2+ 支持 #[AsTwigFilter('truncate')] 注解，但仅限方法级，且类仍需被容器扫描到（即路径在 src/Twig/ 下 + 服务配置没禁用自动发现）。
服务配置漏掉 twig.extension 标签就等于没写
Symfony 不靠 getFilters() 自动识别扩展，而是靠服务标签驱动加载：
- 必须在
config/services.yaml中为该服务显式添加：tags: [{ name: 'twig.extension' }] - 类名空间和物理路径必须严格一致，例如
App\Twig\TextExtension→src/Twig/TextExtension.php - 如果用了自定义目录（如
src/Extension/Twig/），自动发现会失效，必须手动注册服务并打标签 - 验证是否生效：运行
php bin/console debug:container --tag=twig.extension，输出里得有你的类名
调试时最常忽略的缓存与命令验证环节
改完代码不生效？大概率卡在这几个地方：
- 模板中拼写和
TwigFilter构造时第一个参数**完全一致**（区分大小写、下划线位置），比如注册的是'price_format'，就不能写成|priceFormat - 改完 PHP 类或 YAML 配置后，必须清缓存：
php bin/console cache:clear，否则旧编译模板还在用 - 快速验证注册状态：
php bin/console debug:twig | grep truncate，看名字是否出现在列表里 - 在控制器里临时 dump：
dump($this->container->get('twig')->getFilter('truncate'));，有返回值说明已注册成功
真正容易被跳过的点是：Twig 扩展类一旦被容器加载，就会参与所有模板渲染；但如果你在开发中反复删改、重命名类，旧服务定义可能还残留在缓存中，清缓存前先确认 debug:container 输出里没有重复或残留条目。
