企业官网建设流程全解析

• 后端

currency_name过滤器是 Twig 国际化扩展（twig/intl-extra包中的IntlExtension）提供的基础设施之一，它接收一个 ISO 4217 三位货币代码（如EUR、JPY），返回符合目标语言环境的货币名称（如Euro、yen japonais）。读完本篇，你将掌握它的模板用法、locale参数规范、完整的安装与注册流程，并能从源码层面理解它在空值、未知代码、ICU 资源缺失时的降级行为，从而在电商价格展示、多语言结算页等场景中放心使用。

一、模板中的基本用法

currency_name过滤器将一个 ISO 4217 货币代码转换为该货币的本地化名称。默认情况下使用当前 locale（即 PHP 进程通过Locale::getDefault()生效的区域设置），也可以显式传入 locale：

{# Euro #} {{ 'EUR'|currency_name }} {# Japanese Yen #} {{ 'JPY'|currency_name }}

显式指定 locale 后，输出语言随之切换。例如以法语环境渲染日元：

{# yen japonais #} {{ 'JPY'|currency_name('fr_FR') }}

参数说明：

二、安装与扩展注册

currency_name过滤器不属于 Twig 核心，而是IntlExtension的一部分，默认并不安装。仓库文档doc/filters/currency_name.rst给出的安装步骤如下：

1. 先安装 intl 扩展包：

$ composer require twig/intl-extra

2. 如果是 Symfony 项目，接着安装twig/extra-bundle，它会自动装配该扩展：

$ composer require twig/extra-bundle

3. 非 Symfony 项目则需要在 Twig 环境上显式注册扩展：

use Twig\Extra\Intl\IntlExtension; $twig = new \Twig\Environment(...); $twig->addExtension(new IntlExtension());

从 composer.json 可以确认该包的适用前提：要求 PHP 8.1 及以上，依赖twig/twig ^3.13|^4.0和symfony/intl ^5.4|^6.4|^7.0|^8.0。货币名称的数据来源正是symfony/intl组件提供的 ICU 数据（Currencies类），这也是过滤器能够按 locale 返回不同语言名称的底层原因。

三、源码级实现：降级策略与容错设计

过滤器在 IntlExtension.php 中注册，getFilters()方法内将其映射到getCurrencyName方法：

new TwigFilter('currency_name', [$this, 'getCurrencyName']),

核心实现非常短，但包含了三层容错逻辑（见 IntlExtension.php）：

public function getCurrencyName(?string $currency, ?string $locale = null): string { if (null === $currency) { return ''; } try { return Currencies::getName($currency, $locale); } catch (MissingResourceException $exception) { return $currency; } }

逐层解读：

1. 空值安全：输入为null时直接返回空字符串，不会抛出类型错误。这意味着模板里写{{ item.currency|currency_name }}时，即使currency字段缺失也不会导致页面崩溃。
2. 正常路径：调用Symfony\Component\Intl\Currencies::getName()，由 symfony/intl 组件根据 ICU 数据返回对应 locale 下的货币名称。
3. 资源缺失降级：如果symfony/intl的 ICU 资源无法覆盖该代码（抛出MissingResourceException），则原样返回输入的货币代码，而不是抛出异常。这是一种“优雅降级”设计：即使翻译资源不完整，页面仍然能展示一个对用户有辨识度的占位符（如XXX），便于快速定位数据问题。

同一文件中，getCountryName、getLanguageName、getCurrencySymbol、getTimezoneName等方法采用完全相同的结构（null 检查 + try/catch 降级），说明这是整个IntlExtension命名查询类方法的统一范式。

四、测试用例验证实际行为

仓库自带集成测试夹具 currency_name.test 覆盖了五种典型输入，可以把它当作该过滤器行为契约的权威说明：

{{ 'UNKNOWN'|currency_name }} {# UNKNOWN（未知代码原样返回） #} {{ null|currency_name }} {# 空字符串 #} {{ 'EUR'|currency_name }} {# Euro #} {{ 'JPY'|currency_name }} {# Japanese Yen #} {{ 'EUR'|currency_name('fr') }} {# euro #} {{ 'JPY'|currency_name('fr_FR') }} {# yen japonais #}

该夹具由 IntegrationTest.php 驱动——它继承 Twig 核心的IntegrationTestCase，并在getExtensions()中注册new IntlExtension()，与生产环境的注册方式一致。从测试期望输出可以印证两点：其一，当前默认 locale（英文环境）下EUR渲染为Euro；其二，传入fr/fr_FR后分别输出euro（法语中货币名小写）和yen japonais（日语“yen”的法语借词带拼写），验证了 locale 参数确实切换了 ICU 的命名资源。

五、在整个 IntlExtension 中的位置与相关能力

currency_name只是IntlExtension国际命名能力的一块拼图。查看 IntlExtension.php 的getFilters()与getFunctions()可以看到完整清单：

• 命名类过滤器（与本文同族）：country_name、currency_name、currency_symbol、language_name、locale_name、timezone_name；
• 命名类函数（返回完整映射数组）：country_names、currency_names、locale_names、language_names、script_names、timezone_names、country_timezones；
• 本地化格式化过滤器：format_currency（把金额格式化为货币）、format_number、format_date、format_time、format_datetime、format_list。

在实际项目中常见的组合用法是：用currency_name/currency_names做货币下拉框的本地化标签，用format_currency渲染价格本体。例如模板中可以同时写出货币名称与格式化金额（format_currency同样接受locale参数，机制与本文一致）。另外，README.md 中对本包的官方描述是：“returns the currency name given its three-letter code”，与本文用法一致。

六、小结与注意事项

• currency_name的输入是ISO 4217 三位代码，locale参数遵循RFC 5646格式，省略时使用进程默认 locale。
• 该过滤器来自twig/intl-extra的IntlExtension，不在 Twig 核心中；Symfony 项目需额外安装twig/extra-bundle，独立项目需手动addExtension(new IntlExtension())。
• 行为契约（以仓库源码与测试为准）：null输入返回空字符串；未知代码或 ICU 资源缺失时原样返回输入代码，不抛异常。
• 运行环境要求 PHP >= 8.1，且货币名称数据依赖symfony/intl组件所封装的 ICU 数据集。

相关文档与源码入口：currency_name 官方文档、currency_symbol 文档、过滤器实现、行为测试夹具。

• 后端