跳至内容

从旧版本升级

从 v4 升级至 v5

Smarty 5 添加对 PHP8.2 的支持，取消对 PHP7.1 的支持。Smarty 还添加对三元运算符（{$test ? $a : $b} 和 {$var ?: $value_if_falsy}）、空值合并运算符（{$var ?? $value_if_null}）和自定义标签的位置参数等新功能的支持。Smarty 5 还拥有一个全新的扩展架构，允许你编写简洁的扩展包。

命名空间

所有 Smarty 代码已移至 \Smarty 命名空间。这减少了与其他（你的）代码冲突的可能性。

对于简单的用例，你只需要在脚本中添加 use Smarty\Smarty;，其他一切都会正常运行。

<?php
use Smarty\Smarty;
$smarty = new Smarty();

$smarty->display('homepage.tpl');
有关更多信息，请参阅 入门。

如果你扩展 Smarty 或使用 Smarty 插件，请查看你的代码，看看它们是否假设了特定的类或方法名称。例如：Smarty_Internal_Template 现在是 \Smarty\Template\，SmartyException 现在是 \Smarty\Exception。

变量范围冒泡

模板变量作用域冒泡已经得到简化并变得更加一致。全局作用域现在等于 Smarty 作用域，以避免全局状态副作用。请阅读有关语言变量作用域的文档以了解详细信息。

另外，{config_load} 不再有 scope 参数，这意味着您不能再将配置从模板内部加载到全局作用域中（同样，同样为了避免全局状态副作用）。如果您需要设置全局配置，请使用 PHP 代码中的configLoad API 方法。

在模板中使用原生 PHP 函数或用户提供的函数

您不能再在没有注册的情况下在模板中使用本机 PHP 函数或用户空间函数。如果您在模板中需要某项功能，请首先注册它。

最简单的方法如下

// native PHP functions used as modifiers need to be registered
$smarty->registerPlugin('modifier', 'substr', 'substr');

// userland PHP functions used as modifiers need to be registered
$smarty->registerPlugin('modifier', 'my_special_func', 'my_special_func');

但是，您可能需要考虑编写一个适当的扩展。

移除未记录的标签

Smarty 4 仍然支持一些从以前版本继承下来的标记，但从未被记录。

  • {block_parent} 应替换为 {$smarty.block.parent}
  • {parent} 应替换为 {$smarty.block.parent}
  • {block_child} 应替换为 {$smarty.block.child}

  • {child} 应替换为 {$smarty.block.child}

  • {make_nocache} 不再受支持

  • {insert} 不再受支持

移除 Smarty API 属性

在 Smarty 4 中，您可以通过直接访问 PHP 中 Smarty 对象上的公有属性来进行许多配置更改。在许多情况下，这些属性都是私有的，您现在应使用适当的设置方法

  • $smarty->left_delimiter 应替换为 $smarty->getLeftDelimiter()/$smarty->setLeftDelimiter()
  • $smarty->right_delimiter 应替换为 $smarty->getRightDelimiter()/$smarty->setRightDelimiter()
  • $smarty->autoload_filters 应替换为 $smarty->registerFilter()
  • $smarty->template_dir 应替换为 $smarty->setTemplateDir()
  • $smarty->cache_dir 应替换为 $smarty->setCacheDir()
  • $smarty->compile_dir 应替换为 $smarty->setCompileDir()

其他公有属性已被完全删除，您不应再访问它们

  • $smarty->_current_file
  • $smarty->allow_ambiguous_resources（不明确资源处理程序仍应工作）
  • $smarty->registered_filters
  • $smarty->direct_access_security
  • $smarty->trusted_dir
  • $smarty->allow_php_templates
  • $smarty->php_functions
  • $smarty->php_modifiers

自定义插件向后不兼容的更改

我们已弃用对 $smarty->plugins_dir 和 $smarty->use_include_path 的支持。使用 $smarty->addPluginsDir() 或考虑编写一个适当的扩展。

“insert”插件类型不再受支持。

已注册插件的 $cache_attrs 参数不再受支持。

移除 Smarty API 方法

在代码中搜索以下更改

  • $smarty->getTags() 不再受支持
  • $smarty->appendByRef() 应替换为 $smarty->append()
  • $smarty->assignByRef() 应替换为 $smarty->assign()
  • $smarty->loadPlugin() 应替换为 $smarty->registerPlugin()

移除 PHP 常量

为了防止 global 的副作用，已删除下列常量。

  • SMARTY_DIR
  • SMARTY_SYSPLUGINS_DIR
  • SMARTY_PLUGINS_DIR
  • SMARTY_MBSTRING
  • SMARTY_HELPER_FUNCTIONS_LOADED

其他更改

  • Smarty 现在始终以多字节模式运行。确保在生产环境中使用 PHP 多字节扩展，以获得最佳性能。
  • 不再将已弃用的 type="text/javascript" 或 language="Javascript" 属性添加到生成的 <script>
  • Smarty 将抛出编译异常，而不会像以下这样默默地忽略函数调用的修饰符：{include|dot:"x-template-id" file="included.dot.tpl"}
  • 现在，CompilerException 的 ::getFile() 方法将返回被编译模板的完整路径（如果可能）。此路径曾是“file:relative_dir/filename.tpl”。

从 v3 升级至 v4

Smarty 4 几乎与 Smarty 3 完全相同。它最显着的更新是，它添加了对 PHP8 的支持，而放弃了对 PHP7.0 及更低版本的语言支持。此外，已经放弃了一些长期不受鼓励的已弃用功能。

静音 PHP8 警告

如果您同时将 Smarty 升级到 v4 将 PHP 升级到 v8，您可能会注意到错误日志中充满了关于未定义或 null 模板变量的警告，这是因为 PHP 处理这些变量的方式发生了变化。识别错误可能会很有帮助，但如果您觉得这很烦人，可以使用 $smarty->muteUndefinedOrNullWarnings() 使 Smarty 将这些警告转换为通知。

ASP 标签

您不能再在模板中使用诸如 <% %> 和 <%= %> 的 ASP 风格标签。用 {...} 标签替换它们。

SmartyBC

在代码库中检查 SmartyBC。我们已经放弃了仅可通过 SmartyBC 类访问的已弃用 API 调用。

不再支持内嵌 PHP

我们已经完全放弃对 {php} 和 {include_php} 标签以及模板中嵌入式 PHP 的支持。检查模板，重写所有嵌入式 PHP 块，方法是将逻辑移至 PHP 文件或创建一个 自定义标签。

其他更改

在代码中搜索以下更改

  • SMARTY_RESOURCE_CHAR_SET 和 SMARTY_RESOURCE_DATE_FORMAT 常量已被删除
  • Smarty::muteExpectedErrors 和 Smarty::unmuteExpectedErrors API 方法已被删除
  • Smarty::getVariable 方法已被删除。请改用 Smarty::getTemplateVars。
  • Smarty::registerResource 不再接受回调函数的数组