README

OctoberCMS 的 Twig 扩展插件为您的模板添加新的过滤器和函数。没有其他插件依赖。已在 PHP 8.0 上与最新稳定的 OctoberCMS 3.1.18 版本进行了测试。

版本

此插件有两个版本 - 1.x 和 2.x。对于较旧的 October 1.0.x、1.1.x 或 2.x.x 版本，请使用特殊的 1.x 分支。对于 October 3.1+，请使用主分支。对于旧的 Laravel 5.4 October 版本，请使用特殊的 laravel54 分支。

要在插件版本 1 和版本 2 之间迁移，您可以使用特殊的 UPGRADE.md 指南。

安装

从 CMS 后端或通过 Composer 安装插件

composer require vojtasvoboda/oc-twigextensions-plugin

然后您可以在模板中使用新添加的过滤器和/或函数

<h1 class="heading">{{ article.heading | ltrim }}</h1>
<p class="created">
	Posted at {{ article.date | strftime('%d.%m.%Y %H:%M:%S') }}
</p>
<p class="perex">
	{{ article.perex | wordwrap(80) }}
</p>

可用函数

session、trans、var_dump、template_from_string、country_timezones

session

函数将 Laravel session() 辅助函数的功能移动到 Twig。

{{ session('my.session.key') }}

示例将输出当前存储在 my.session.key 中的值。有关 Laravel 会话辅助函数的更多信息，请参见此处。

您还可以使用 OctoberCMS 函数：{{ this.session.get('my.session.key') }}，但它稍微长一些 :-)

trans

函数将 Laravel trans() 辅助函数的功能移动到 Twig。

{{ trans('acme.blog::lang.app.name') }}

示例将输出存储在虚构博客插件的本地化文件中的值。有关 October CMS 中本地化的更多信息，请参见此处。

您还可以使用 trans 过滤器：{{ 'acme.blog::lang.app.name'|trans }}。

var_dump

输出有关变量的信息。也可以用作过滤器。

<pre>{{ var_dump(users) }}</pre>

您还可以使用 {{ dump(users) }} 函数来输出有关变量的信息。属性是“可点击的”以展开。

template_from_string

函数从字符串加载模板。

{% set name = 'John' %}
{{ include(template_from_string("Hello {{ name }}")) }}
{{ include(template_from_string("Hurry up it is: {{ "now"|date("m/d/Y") }}")) }}

country_timezones

country_timezones 函数返回与给定国家代码关联的时间区名称

{# Europe/Paris #}
{{ country_timezones('FR')|join(', ') }}

可用过滤器

• PHP 函数：strftime、ltrim、rtrim、var_dump、wordwrap
• 自定义函数：revision
• 国际化名称过滤器：country_name、currency_name、currency_symbol、language_name、locale_name、timezone_name
• 本地化格式化过滤器：format_currency、format_number、format_*_number、format_datetime、format_date、format_time

strftime

根据区域设置格式化本地时间/日期。

Posted at {{ article.date | strftime('%d.%m.%Y %H:%M:%S') }}

示例将输出 发布于 04.01.2016 22:57:42。有关更多格式参数，请参见此处。

您还可以使用 {{ carbon(article.date).formatLocalized('%d.%m.%Y %H:%M:%S') }}。

ltrim

从字符串的开始处删除空格（或其他字符）。

Hello I'm {{ ' jack' | ltrim }}

示例将输出从开头开始的空白字符去除后的 Hello I'm jack。

您还可以使用原生 Twig 过滤器 {{ ' I like Twig. '|trim(side='left') }}。

rtrim

从字符串末尾删除空白字符（或其他字符）。

Hello I'm {{ 'jack ' | rtrim }}

示例将输出从末尾开始的空白字符去除后的 Hello I'm jack。

您还可以使用原生 Twig 过滤器 {{ ' I like Twig. '|trim(side='right') }}。

var_dump

输出变量的信息。

<pre>{{ users | var_dump }}</pre>

您还可以使用 <pre>{{ var_dump(users) }}</pre> 或 {{ dump(users) }} 函数。

wordwrap

使用 wordwrap 过滤器将文本分割成等长的行。

{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10) }}

此示例将打印

Lorem ipsu  
m dolor si  
t amet, co  
nsectetur  
adipiscing  

默认分隔符是 "\n"，但您可以通过提供分隔符来轻松更改

{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10, "zz\n") }}

这将得到以下结果

Lorem ipsuzz  
m dolor sizz  
t amet, cozz  
nsectetur zz  
adipiscing  

修订

强制浏览器重新加载缓存的修改/更新资产文件。您可以提供格式参数，以便附加的时间戳可以相应地转换为 PHP date() 函数。

用法

<img src="{{ 'assets/images/image_file.jpg' | theme | revision("m.d.y.H.i.s") }}" alt="an image" />

将返回类似

<img src="https://www.example.com/themes/my-theme/assets/image_file.png?12.03.16.04.52.38" alt="An image" />

见： #25

https://stackoverflow.com/questions/32414/how-can-i-force-clients-to-refresh-javascript-files

https://php.ac.cn/manual/en/function.date.php

country_name

country_name 过滤器根据 ISO-3166 两位字母代码返回国家名称

{# France #}
{{ 'FR'|country_name }}

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# États-Unis #}
{{ 'US'|country_name('fr') }}

currency_name

currency_name 过滤器根据三位字母代码返回货币名称

{# Euro #}
{{ 'EUR'|currency_name }}

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

默认情况下，过滤器使用当前区域设置。您可以显式传递它

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

currency_symbol

currency_symbol 过滤器根据三位字母代码返回货币符号

{# € #}
{{ 'EUR'|currency_symbol }}

{# ¥ #}
{{ 'JPY'|currency_symbol }}

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# ¥ #}
{{ 'JPY'|currency_symbol('fr') }}

language_name

language_name 过滤器根据两位字母代码返回语言名称

{# German #}
{{ 'de'|language_name }}

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# allemand #}
{{ 'de'|language_name('fr') }}

{# français canadien #}
{{ 'fr_CA'|language_name('fr_FR') }}

locale_name

locale_name 过滤器根据两位字母代码返回区域名称

{# German #}
{{ 'de'|locale_name }}

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# allemand #}
{{ 'de'|locale_name('fr') }}

{# français (Canada) #}
{{ 'fr_CA'|locale_name('fr_FR') }}

timezone_name

timezone_name 过滤器根据时区标识符返回时区名称

{# Central European Time (Paris) #}
{{ 'Europe/Paris'|timezone_name }}

{# Pacific Time (Los Angeles) #}
{{ 'America/Los_Angeles'|timezone_name }}

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# heure du Pacifique nord-américain (Los Angeles) #}
{{ 'America/Los_Angeles'|timezone_name('fr') }}

format_currency

format_currency 过滤器将数字格式化为货币

{# €1,000,000.00 #}
{{ '1000000'|format_currency('EUR') }}

您可以通过传递属性来调整输出

{# €12.34 #}
{{ '12.345'|format_currency('EUR', {rounding_mode: 'floor'}) }}

{# €1,000,000.0000 #}
{{ '1000000'|format_currency('EUR', {fraction_digit: 4}) }}

支持选项列表

• grouping_used;
• decimal_always_shown;
• max_integer_digit;
• min_integer_digit;
• integer_digit;
• max_fraction_digit;
• min_fraction_digit;
• fraction_digit;
• multiplier;
• grouping_size;
• rounding_mode;
• rounding_increment;
• format_width;
• padding_position;
• secondary_grouping_size;
• significant_digits_used;
• min_significant_digits_used;
• max_significant_digits_used;
• lenient_parse.

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# 1.000.000,00 € #}
{{ '1000000'|format_currency('EUR', locale='de') }}

format_number 和 format_*_number

format_number 过滤器格式化数字

{{ '12.345'|format_number }}

您可以通过传递属性来调整输出

{# 12.34 #}
{{ '12.345'|format_number({rounding_mode: 'floor'}) }}

{# 1000000.0000 #}
{{ '1000000'|format_number({fraction_digit: 4}) }}

支持选项列表

• grouping_used;
• decimal_always_shown;
• max_integer_digit;
• min_integer_digit;
• integer_digit;
• max_fraction_digit;
• min_fraction_digit;
• fraction_digit;
• multiplier;
• grouping_size;
• rounding_mode;
• rounding_increment;
• format_width;
• padding_position;
• secondary_grouping_size;
• significant_digits_used;
• min_significant_digits_used;
• max_significant_digits_used;
• lenient_parse.

除了普通数字外，该过滤器还可以以各种样式格式化数字

{# 1,234% #}
{{ '12.345'|format_number(style='percent') }}

{# twelve point three four five #}
{{ '12.345'|format_number(style='spellout') }}

{# 12 sec. #}
{{ '12'|format_duration_number }}

支持样式的列表

• decimal;
• currency;
• percent;
• scientific;
• spellout;
• ordinal;
• duration.

作为一个快捷方式，您可以通过用样式替换 * 来使用 format_*_number 过滤器

{# 1,234% #}
{{ '12.345'|format_percent_number }}

{# twelve point three four five #}
{{ '12.345'|format_spellout_number }}

您可以通过传递属性来调整输出

{# 12.3% #}
{{ '0.12345'|format_percent_number({rounding_mode: 'floor', fraction_digit: 1}) }}

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# 12,345 #}
{{ '12.345'|format_number(locale='fr') }}

format_datetime

format_datetime 过滤器格式化日期时间

{# Aug 7, 2019, 11:39:12 PM #}
{{ '2019-08-07 23:39:12'|format_datetime() }}

格式

您可以调整日期部分和时间部分的输出

{# 23:39 #}
{{ '2019-08-07 23:39:12'|format_datetime('none', 'short', locale='fr') }}

{# 07/08/2019 #}
{{ '2019-08-07 23:39:12'|format_datetime('short', 'none', locale='fr') }}

{# mercredi 7 août 2019 23:39:12 UTC #}
{{ '2019-08-07 23:39:12'|format_datetime('full', 'full', locale='fr') }}

支持的值是：none, short, medium, long, 和 full。

为了更大的灵活性，您甚至可以定义自己的模式（请参阅 ICU 用户指南以获取支持的模式）。

{# 11 oclock PM, GMT #}
{{ '2019-08-07 23:39:12'|format_datetime(pattern="hh 'oclock' a, zzzz") }}

区域

默认情况下，过滤器使用当前区域设置。您可以显式传递它

{# 7 août 2019 23:39:12 #}
{{ '2019-08-07 23:39:12'|format_datetime(locale='fr') }}

时区

默认情况下，日期通过应用默认时区（在 php.ini 中指定的或已声明在 Twig 中）来显示，但您可以通过显式指定一个时区来覆盖它

{{ datetime|format_datetime(locale='en', timezone='Pacific/Midway') }}

如果日期已经是 DateTime 对象，并且您想保持其当前时区，请将时区值传递为 false

{{ datetime|format_datetime(locale='en', timezone=false) }}

默认时区也可以通过调用 setTimezone() 全局设置

$twig = new \Twig\Environment($loader);
$twig->getExtension(\Twig\Extension\CoreExtension::class)->setTimezone('Europe/Paris');

format_date

format_date 过滤器格式化日期。它的工作方式与 format_datetime 过滤器完全相同，但没有时间。

format_time

format_time 过滤器格式化时间。它的工作方式与 format_datetime 过滤器完全相同，但没有日期。

删除的函数

插件1.x版本中使用的函数，适用于October 1.0.x、1.1.x、2.0.x版本，并已从本版本中删除

• config() - 自October 3.1.17起为原生函数
• env() - 自October 3.1.17起为原生函数

已删除的过滤器

插件1.x版本中使用的过滤器，适用于October 1.0.x、1.1.x、2.0.x版本，并已从本版本中删除

• uppercase - 使用str_upper或直接使用upper
• lowercase - 使用str_lower或直接使用lower
• ucfirst - 使用str_ucfirst
• lcfirst - 使用str_lcfirst
• str_repeat - 现在是原生过滤器
• plural - 使用str_plural
• truncate - 使用str_limit
• strpad - 使用str_pad_both
• str_replace - 现在是原生过滤器
• strip_tags - 使用html_strip
• leftpad - 使用str_pad_left
• rightpad - 使用str_pad_right
• rtl - 使用str_reverse
• shuffle - 使用collect(songs).shuffle()
• time_diff - 使用carbon(post.published_at).diffForHumans()
• localizeddate - 使用format_date
• localizednumber - 使用format_number
• localizedcurrency - 使用format_currency
• mailto - 使用html_mailto
• var_dump - 使用dump函数
• sortbyfield - 使用collect(data).sortBy('age')或collect(data).sortByDesc('age')

有关更多信息，请参阅UPGRADE.md指南。

贡献

• 默认关闭template_from_string，并在后端添加特殊复选框以允许使用它。
• 添加缺少的单元测试。
• 添加新过滤器ga和gtm，用于添加GA或GTM代码（Heap Analytics）- {{ 'UA-1234567' | ga }}。
• 添加缓存扩展。

请随意发送pullrequest！请将Pull Request发送到master分支。

许可证

Twig扩展插件是开源软件，采用与OctoberCMS平台相同的MIT许可证。