后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载在 Twig 模板中处理用户输入、标题或表单数据时经常需要把字符串统一为小写形式。本文以官方文档 lower 过滤器说明 为核心结合 Twig 源码与集成测试完整讲解lower过滤器的用法、字符集charset处理机制、null安全行为以及它在CoreExtension中的注册与编译原理帮助读者既能正确使用该过滤器也能理解其底层调用链。lower 过滤器基本用法lower过滤器将任意值转换为小写字符串这是 lower.rst 中给出的核心示例{{ WELCOME|lower }} {# 输出 welcome #}该过滤器可以作用于字符串字面量也可以作用于模板变量例如{% set title Hello WORLD %} p{{ title|lower }}/p {# 输出 hello world #}文档同时明确指出Twig 内部使用的是 PHP 的mb_strtolower函数而非原生strtolower。这一区别非常关键——mb_strtolower是mbstring扩展提供的多字节安全函数能够正确处理 UTF-8 等多字节字符集中的大小写转换如法语É等带重音字符避免原生strtolower在多字节字符上产生乱码。源码实现null 安全与字符集参数lower过滤器在核心扩展中注册于 CoreExtension::getFilters()// src/Extension/CoreExtension.php new TwigFilter(lower, [self::class, lower], [needs_charset true]),其实际实现是 CoreExtension::lower() 静态方法/** * Converts a string to lowercase. * * param string|null $string A string * * internal */ public static function lower(string $charset, $string): string { return mb_strtolower($string ?? , $charset); }从源码实现可以确认两个行为细节字符集作为第一个参数mb_strtolower的第二个参数是字符集保证多字节字符被正确转换。这个参数并非模板作者传入而是由编译器自动注入详见下文needs_charset机制。null 值被安全地当作空字符串$string ?? 意味着对null执行lower不会报错而是返回空字符串。官方集成测试 tests/Fixtures/filters/lower.test 正是针对这些行为编写的--TEMPLATE-- {{ I like Twig.|lower }} *{{ |lower }}* *{{ null|lower }}* --EXPECT-- i like twig. ** **即普通字符串转小写、空字符串与null均输出空结果三段断言覆盖了文档承诺的全部边界行为。needs_charset 机制字符集从哪里来lower注册的needs_charset true选项是理解其运行环境的关键。在 CallExpression::compileArguments() 中编译器检测到该选项后会在生成代码的参数列表最前面自动插入环境字符集// src/Node/Expression/CallExpression.php if ($twigCallable-needsCharset()) { $compiler-raw($this-env-getCharset()); $first false; }也就是说模板中写的{{ WELCOME|lower }}编译后会生成类似\Twig\Extension\CoreExtension::lower($this-env-getCharset(), WELCOME)的 PHP 调用——模板作者完全不需要关心字符集参数。字符集本身由Environment管理可通过 Environment::setCharset()/getCharset() 读写public function setCharset(string $charset) { if (UTF8 $charset strtoupper($charset ?: )) { // iconv on Windows requires UTF-8 instead of UTF8 $charset UTF-8; } $this-charset $charset; }源码中还对 Windows 平台做了专门处理将UTF8规范化为UTF-8注释说明 iconv 在 Windows 上要求后者。若你的应用不是 UTF-8 环境如 Latin-1 页面可调用$twig-setCharset(latin1)调整lower、upper等所有needs_charset过滤器会随之使用新字符集。同族过滤器与旧版兼容层在 CoreExtension::getFilters() 中lower与一组同样声明needs_charset的字符串过滤器并列实现机制完全一致new TwigFilter(title, [self::class, titleCase], [needs_charset true]), new TwigFilter(capitalize, [self::class, capitalize], [needs_charset true]), new TwigFilter(upper, [self::class, upper], [needs_charset true]), new TwigFilter(lower, [self::class, lower], [needs_charset true]),对比 CoreExtension::capitalize() 可以看到capitalize内部甚至复用了mb_strtouppermb_strtolower的组合来实现首字母大写、其余小写说明mb_*系列函数是整个字符串过滤器族的基础。此外needs_charset选项的默认值为false定义在 AbstractTwigCallable 的选项默认值中。值得一提的是src/Resources/core.php 中还保留了旧版全局函数封装供 3.9 之前生成的模板缓存代码继续调用/** * internal * * deprecated since Twig 3.9 */ function twig_lower_filter(Environment $env, $string) { trigger_deprecation(twig/twig, 3.9, Using the internal %s function is deprecated., __FUNCTION__); return CoreExtension::lower($env-getCharset(), $string); }从这一废弃声明可以确认旧模板缓存中的twig_lower_filter调用最终同样汇入CoreExtension::lower()行为与新版编译输出完全一致只是会触发弃用通知。实战注意事项自动转义不受影响lower注册时未声明is_safe或pre_escape选项对照 TwigFilter 的默认值两者均为null。因此过滤结果被视为不安全内容仍会按模板的转义策略进行 HTML 转义。如果需要在转义后做小写处理应写{{ Foo|escape|lower }}的顺序由实际语义决定。依赖 mbstring 扩展底层调用mb_strtolower运行环境需启用mbstring否则转换将不可用。仅适用于字符串语义的输入过滤器声明的返回类型为string对数字等非字符串输入会由 Twig 先做类型转换再处理对null则按空字符串处理见上文测试断言。字符集全局生效setCharset()改变的是整个Environment的行为调整时请确保与页面实际编码一致否则lower/upper/title/length/slice等所有依赖字符集的过滤器都会受到影响。小结lower过滤器看似只是一个简单的{{ value|lower }}但其背后是一条完整的机制链CoreExtension注册时声明needs_charset→ 编译器在 CallExpression 中注入$this-env-getCharset()→ 运行时调用CoreExtension::lower()执行mb_strtolower($string ?? , $charset)。理解这条链路后你不仅能正确使用lower也能推导出upper、capitalize、title等全部字符集相关过滤器的行为边界并在非 UTF-8 项目中正确配置Environment的字符集。赞分享后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载相关推荐Twig last 过滤器详解从模板语法到 CoreExtension 源码的取值机制Twig last 过滤器详解从模板语法到 CoreExtension 源码的取值机制 last 是 Twig 内置核心过滤器中用于取尾部元素的基本工具后端Twig keys 过滤器详解从模板语法到 CoreExtension 源码实现Twig keys 过滤器详解从模板语法到 CoreExtension 源码实现 本篇指南围绕 Twig 模板语言中的 keys 过滤器展开它如何从序列s后端Twig inky_to_html 过滤器用 twig/inky-extra 将 Inky 邮件模板编译为兼容 HTMLTwig inky_to_html 过滤器用 twig/inky extra 将 Inky 邮件模板编译为兼容 HTML 本文围绕 Twig 官方文档中 in后端上一篇RocketRide audio_player 节点深度解析本地 PCM 音频播放器的实现原理与实战指南下一篇阿里云OSS签名URL终极指南3种方法实现安全文件共享创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Twig lower 过滤器详解：从 `mb_strtolower` 到 `needs_charset` 编译机制
后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载在 Twig 模板中处理用户输入、标题或表单数据时经常需要把字符串统一为小写形式。本文以官方文档 lower 过滤器说明 为核心结合 Twig 源码与集成测试完整讲解lower过滤器的用法、字符集charset处理机制、null安全行为以及它在CoreExtension中的注册与编译原理帮助读者既能正确使用该过滤器也能理解其底层调用链。lower 过滤器基本用法lower过滤器将任意值转换为小写字符串这是 lower.rst 中给出的核心示例{{ WELCOME|lower }} {# 输出 welcome #}该过滤器可以作用于字符串字面量也可以作用于模板变量例如{% set title Hello WORLD %} p{{ title|lower }}/p {# 输出 hello world #}文档同时明确指出Twig 内部使用的是 PHP 的mb_strtolower函数而非原生strtolower。这一区别非常关键——mb_strtolower是mbstring扩展提供的多字节安全函数能够正确处理 UTF-8 等多字节字符集中的大小写转换如法语É等带重音字符避免原生strtolower在多字节字符上产生乱码。源码实现null 安全与字符集参数lower过滤器在核心扩展中注册于 CoreExtension::getFilters()// src/Extension/CoreExtension.php new TwigFilter(lower, [self::class, lower], [needs_charset true]),其实际实现是 CoreExtension::lower() 静态方法/** * Converts a string to lowercase. * * param string|null $string A string * * internal */ public static function lower(string $charset, $string): string { return mb_strtolower($string ?? , $charset); }从源码实现可以确认两个行为细节字符集作为第一个参数mb_strtolower的第二个参数是字符集保证多字节字符被正确转换。这个参数并非模板作者传入而是由编译器自动注入详见下文needs_charset机制。null 值被安全地当作空字符串$string ?? 意味着对null执行lower不会报错而是返回空字符串。官方集成测试 tests/Fixtures/filters/lower.test 正是针对这些行为编写的--TEMPLATE-- {{ I like Twig.|lower }} *{{ |lower }}* *{{ null|lower }}* --EXPECT-- i like twig. ** **即普通字符串转小写、空字符串与null均输出空结果三段断言覆盖了文档承诺的全部边界行为。needs_charset 机制字符集从哪里来lower注册的needs_charset true选项是理解其运行环境的关键。在 CallExpression::compileArguments() 中编译器检测到该选项后会在生成代码的参数列表最前面自动插入环境字符集// src/Node/Expression/CallExpression.php if ($twigCallable-needsCharset()) { $compiler-raw($this-env-getCharset()); $first false; }也就是说模板中写的{{ WELCOME|lower }}编译后会生成类似\Twig\Extension\CoreExtension::lower($this-env-getCharset(), WELCOME)的 PHP 调用——模板作者完全不需要关心字符集参数。字符集本身由Environment管理可通过 Environment::setCharset()/getCharset() 读写public function setCharset(string $charset) { if (UTF8 $charset strtoupper($charset ?: )) { // iconv on Windows requires UTF-8 instead of UTF8 $charset UTF-8; } $this-charset $charset; }源码中还对 Windows 平台做了专门处理将UTF8规范化为UTF-8注释说明 iconv 在 Windows 上要求后者。若你的应用不是 UTF-8 环境如 Latin-1 页面可调用$twig-setCharset(latin1)调整lower、upper等所有needs_charset过滤器会随之使用新字符集。同族过滤器与旧版兼容层在 CoreExtension::getFilters() 中lower与一组同样声明needs_charset的字符串过滤器并列实现机制完全一致new TwigFilter(title, [self::class, titleCase], [needs_charset true]), new TwigFilter(capitalize, [self::class, capitalize], [needs_charset true]), new TwigFilter(upper, [self::class, upper], [needs_charset true]), new TwigFilter(lower, [self::class, lower], [needs_charset true]),对比 CoreExtension::capitalize() 可以看到capitalize内部甚至复用了mb_strtouppermb_strtolower的组合来实现首字母大写、其余小写说明mb_*系列函数是整个字符串过滤器族的基础。此外needs_charset选项的默认值为false定义在 AbstractTwigCallable 的选项默认值中。值得一提的是src/Resources/core.php 中还保留了旧版全局函数封装供 3.9 之前生成的模板缓存代码继续调用/** * internal * * deprecated since Twig 3.9 */ function twig_lower_filter(Environment $env, $string) { trigger_deprecation(twig/twig, 3.9, Using the internal %s function is deprecated., __FUNCTION__); return CoreExtension::lower($env-getCharset(), $string); }从这一废弃声明可以确认旧模板缓存中的twig_lower_filter调用最终同样汇入CoreExtension::lower()行为与新版编译输出完全一致只是会触发弃用通知。实战注意事项自动转义不受影响lower注册时未声明is_safe或pre_escape选项对照 TwigFilter 的默认值两者均为null。因此过滤结果被视为不安全内容仍会按模板的转义策略进行 HTML 转义。如果需要在转义后做小写处理应写{{ Foo|escape|lower }}的顺序由实际语义决定。依赖 mbstring 扩展底层调用mb_strtolower运行环境需启用mbstring否则转换将不可用。仅适用于字符串语义的输入过滤器声明的返回类型为string对数字等非字符串输入会由 Twig 先做类型转换再处理对null则按空字符串处理见上文测试断言。字符集全局生效setCharset()改变的是整个Environment的行为调整时请确保与页面实际编码一致否则lower/upper/title/length/slice等所有依赖字符集的过滤器都会受到影响。小结lower过滤器看似只是一个简单的{{ value|lower }}但其背后是一条完整的机制链CoreExtension注册时声明needs_charset→ 编译器在 CallExpression 中注入$this-env-getCharset()→ 运行时调用CoreExtension::lower()执行mb_strtolower($string ?? , $charset)。理解这条链路后你不仅能正确使用lower也能推导出upper、capitalize、title等全部字符集相关过滤器的行为边界并在非 UTF-8 项目中正确配置Environment的字符集。赞分享后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载相关推荐Twig last 过滤器详解从模板语法到 CoreExtension 源码的取值机制Twig last 过滤器详解从模板语法到 CoreExtension 源码的取值机制 last 是 Twig 内置核心过滤器中用于取尾部元素的基本工具后端Twig keys 过滤器详解从模板语法到 CoreExtension 源码实现Twig keys 过滤器详解从模板语法到 CoreExtension 源码实现 本篇指南围绕 Twig 模板语言中的 keys 过滤器展开它如何从序列s后端Twig inky_to_html 过滤器用 twig/inky-extra 将 Inky 邮件模板编译为兼容 HTMLTwig inky_to_html 过滤器用 twig/inky extra 将 Inky 邮件模板编译为兼容 HTML 本文围绕 Twig 官方文档中 in后端上一篇RocketRide audio_player 节点深度解析本地 PCM 音频播放器的实现原理与实战指南下一篇阿里云OSS签名URL终极指南3种方法实现安全文件共享创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考