自定义 Twig 过滤器需继承 AbstractExtension、打 twig.extension 标签、用 TwigFilter 注册 callable 方法，参数需手动类型校验，模板调用前须验证注册状态并清缓存。
自定义过滤器在 Twig 里不是写个函数就能用，必须让 Symfony 容器识别它、注册进 Twig 环境、且名字对得上模板里的调用——缺一环就报 Unknown filter。
怎么写一个可被 Twig 调用的 PHP 方法
方法本身要干净：参数类型明确、处理空值、不依赖全局状态。Twig 不会帮你做类型转换，传进来 null 或数字，你得自己兜底。
- 参数建议用类型声明（如
string $text），但注意 Twig 传参时可能绕过 PHP 类型检查，所以仍需手动判断：if (!is_string($text)) { return ''; } - 避免在方法里做 I/O 或查数据库——过滤器是同步、轻量的数据转换逻辑
- 示例截断方法要兼容短文本：
if (strlen($text) ，否则 <code>substr可能返回空或乱码
怎么注册成 TwigFilter 并暴露给模板
靠 getFilters() 返回数组，每个元素是 TwigFilter 实例。名字（第一个参数）就是模板里 |xxx 用的标识符，必须和调用时完全一致（区分大小写）。
- 不要直接调用
$twig->addFilter()—— Symfony 环境下这是无效的，容器接管了全部注册流程 -
TwigFilter构造时第二个参数必须是 callable，格式为[$this, 'methodName']，不能写成'methodName'或匿名函数 - Symfony 5.3+ 支持
#[AsTwigFilter('truncate')]注解，但仅限方法级，且仍需类被容器扫描到
为什么模板里还是报 Unknown filter
最常见原因是服务没打标签，或者路径/类名配不上自动加载规则。
- 必须在
config/services.yaml里显式标记：tags: [{ name: 'twig.extension' }]，漏掉这个标签，Symfony 根本不会把它当 Twig 扩展加载 - 类名空间和文件路径要严格对应，比如
App\Twig\TextExtension必须放在src/Twig/TextExtension.php - 确认该类继承
AbstractExtension，而不是自己实现ExtensionInterface——后者容易漏掉getName()等必需方法
怎么验证过滤器是否生效
别等模板报错才排查，先用命令行快速验证逻辑和注册状态。
- 在控制器里临时 dump：
dump($this->container->get('twig')->getFilter('truncate'));，有返回说明注册成功；抛出InvalidArgumentException就是名字错了或没注册 - 运行
php bin/console debug:twig（Symfony 命令），它会列出所有可用过滤器，你的名字必须出现在其中 - 如果用了缓存，改完代码后记得清缓存：
php bin/console cache:clear，否则旧编译结果可能掩盖新注册
真正容易被忽略的是：Twig 过滤器在模板中是“纯函数”，没有上下文访问能力。想读配置、查用户、取请求参数？得换思路——要么提前把数据 assign 进模板，要么写成 Twig 函数（TwigFunction），而不是过滤器。
