# Upgrading from an older version ## Upgrading from v4 to v5 Smarty 5 adds support for PHP8.2 and drops support for PHP7.1. Smarty also adds support for new features such as the ternary operator (`{$test ? $a : $b}` and `{$var ?: $value_if_falsy}`), the null coalescing operator (`{$var ?? $value_if_null}`) and positional parameters for custom tags. Smarty 5 also has a brand-new extension architecture that allows you to write neat extension packs. ### Namespaces All Smarty code has been moved into the `\Smarty` namespace. This reduces the chance of conflicts with other (your) code. For simple use-cases, you only need to add `use Smarty\Smarty;` to your script and everything will work. ```php display('homepage.tpl'); ``` For more information, see [getting started](getting-started.md). If you extend Smarty or use Smarty plug-ins, please review your code to see if they assume specific class or method names. E.g.: `Smarty_Internal_Template` is now `\Smarty\Template\`, `SmartyException` is now `\Smarty\Exception`. ### Variable scope bubbling Template variable scope bubbling has been simplified and made more consistent. The global scope now equals the Smarty scope in order to avoid global state side effects. Please read the [documentation on language variable scope](designers/language-variables/language-variable-scopes.md) for more details. Also, `{config_load}` no longer has a `scope` parameter, which means you can no longer load config from inside your template into the global scope (again, to avoid global state side effects). If you need to set global config, use the [configLoad API method](api/variables/config-files.md) from your PHP code. ### Using native PHP-functions or userland functions in your templates You can no longer use native PHP-functions or userland functions in your templates without registering them. If you need a function in your templates, register it first. The easiest way to do so is as follows: ```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'); ``` But you may want to consider writing a proper [extension](api/extending/extensions.md). #### Passing parameters by reference You cannot use plugins that expect a parameter by reference anymore. PHP-function such as `reset()`, `prev()`, `next()` and `end()` can be registered as plugin, but they won't work because they expect a parameter by reference and Smarty will try to pass it by value. ### Removed undocumented tags Smarty 4 still supported some tags that have been carried over from previous version, but have never been documented. - `{block_parent}` should be replaced with `{$smarty.block.parent}` - `{parent}` should be replaced with `{$smarty.block.parent}` - `{block_child}` should be replaced with `{$smarty.block.child}` - `{child}` should be replaced with `{$smarty.block.child}` - `{make_nocache}` is no longer supported - `{insert}` is no longer supported ### Removed Smarty API properties In Smarty 4, you could make many configuration changes by directly accessing public properties on the Smarty object in PHP. In many cases, these properties have been made private, and you should now use the appropriate setter method: - `$smarty->left_delimiter` should be replaced with `$smarty->getLeftDelimiter()`/`$smarty->setLeftDelimiter()` - `$smarty->right_delimiter` should be replaced with `$smarty->getRightDelimiter()`/`$smarty->setRightDelimiter()` - `$smarty->autoload_filters` should be replaced with `$smarty->registerFilter()` - `$smarty->template_dir` should be replaced with `$smarty->setTemplateDir()` - `$smarty->cache_dir` should be replaced with `$smarty->setCacheDir()` - `$smarty->compile_dir` should be replaced with `$smarty->setCompileDir()` Other public properties have been removed altogether, and you should no longer access them: - `$smarty->_current_file` - `$smarty->allow_ambiguous_resources` (ambiguous resources handlers should still work) - `$smarty->registered_filters` - `$smarty->direct_access_security` - `$smarty->trusted_dir` - `$smarty->allow_php_templates` - `$smarty->php_functions` - `$smarty->php_modifiers` ### Backwards incompatible changes to custom plugins We have dropped support for `$smarty->plugins_dir` and `$smarty->use_include_path`. Use `$smarty->addPluginsDir()` or consider writing a proper [extension](api/extending/extensions.md). The 'insert' plugin type is no longer supported. The `$cache_attrs` parameter for registered plugins is no longer supported. ### Removed Smarty API methods Search your code for the following changes: - `$smarty->getTags()` is no longer supported - `$smarty->appendByRef()` should be replaced with `$smarty->append()` - `$smarty->assignByRef()` should be replaced with `$smarty->assign()` - `$smarty->loadPlugin()` should be replaced with `$smarty->registerPlugin()` ### Removed undocumented magic API methods Smarty v4 allowed setting (internal) properties for which no setter existed by using magic methods that start with either `set` or `get`. This has been removed in Smarty 5. For example, `$smarty->setErrorUnassigned(true);` would set the `error_unassigned` property. Every setter of getter that was ever documented or unit tested has been kept. ### Removed PHP constants The following constants have been removed to prevent global side effects. - `SMARTY_DIR` - `SMARTY_SYSPLUGINS_DIR` - `SMARTY_PLUGINS_DIR` - `SMARTY_MBSTRING` - `SMARTY_HELPER_FUNCTIONS_LOADED` ### Other changes - Smarty now always runs in multibyte mode. Make sure you use the [PHP multibyte extension](https://www.php.net/manual/en/book.mbstring.php) in production for optimal performance. - Generated `