Switching Smarty¶
Background¶
In CiviCRM, the Smarty templating engine is central building-block. It is used for both:
- Web Pages: Many of the screens in CiviCRM are generated from Smarty templates.
- Email Communication: Email blasts and automated alerts may be customized and fine-tuned using Smarty templates.
Smarty templates come from many places, including CiviCRM (core), third-party extensions, and local CiviCRM customizations (users).
During 2023-2025, the project has been transitioning from Smarty v2 to v5. In the transitional period, CiviCRM (core) is compatibile with multiple versions of Smarty. Site-administrators can choose which version to enable.
Choose a version¶
As an administrator, you can choose the version of Smarty. This decision should be influenced by a few factors:
-
CiviCRM Version:
In CiviCRM v5.78+, primary support is provided for Smarty v5. This is the default for new installations and quality assurance. There is secondary support for Smarty v2 and v4. (These work, but they aren't tested as much.)
Details vary by version. For full details, see the version matrix.
-
Extensions:
If you use third-party extensions, then you should consider their compatibility.
In general, extensions released before 2023 require Smarty v2. Extensions released during the transitional period (2023-2025) will often support newer versions of Smarty. But this is not guaranteed and ultimately depends on the specific extension/version/developer.
-
Email Templates:
If you have customized the "System Message Templates", then you need to assess the customizations yourself. Try changing the Smarty version (to taste) and re-testing the customization.
Eventually, you will need to choose Smarty v5 -- earlier versions will be removed in the future. However, during the transition period, you can consider a few subjective questions like:
- How many extensions or custom templates do you have? With more customizations, you may need a more careful or phased process.
- Do you have a staging system (or development system)? Can you update and test that first?
- Do you prefer to upgrade incrementally? You might find it easier to make one large jump (Smarty v2=>v5) or multiple, smaller jumps (Smarty v2=>v4=>v5).
Configure the version¶
To configure the Smarty version, you must update civicrm.settings.php
. The exact text will depend on your environment. Here are two examples:
Use Smarty v5 on a TAR/ZIP-based system (Backdrop, Joomla, Standalone, WordPress)
if (!defined('CIVICRM_SMARTY_AUTOLOAD_PATH')) {
define('CIVICRM_SMARTY_AUTOLOAD_PATH',
$civicrm_root . '/packages/smarty5/Smarty.php'
);
}
Use Smarty v2 on a Composer-based system (Drupal 9/10/11)
if (!defined('CIVICRM_SMARTY_AUTOLOAD_PATH')) {
define('CIVICRM_SMARTY_AUTOLOAD_PATH',
dirname($civicrm_root) . '/civicrm-packages/Smarty/Smarty.class.php'
);
}
Let's examine how these parts may vary:
-
The base path needs to match your file-layout. This depends on the CMS and deployment method. Typical scenarios:
Scenario Base Path TAR/ZIP deployment
(Backdrop, Drupal 7, Joomla, Standalone, WordPress)$civicrm_root . '/packages/'
Composer deployment
(Drupal 9/10/11)dirname($civicrm_root) . '/civicrm-packages/'
If in doubt, use an absolute path '/var/www/example.com/modules/civicrm/packages/'
-
The sub-path indicates the Smarty version. Possible values include:
Version Sub-Path Comment Smarty v5 smarty5/Smarty.php
Available in CiviCRM 5.71+ Smarty v4 smarty4/vendor/autoload.php
Available in CiviCRM 5.71+ Smarty v3 smarty3/vendor/autoload.php
Available in CiviCRM 5.67 - 5.77 Smarty v2 Smarty/Smarty.class.php
Available in all versions. (End date TBD.) -
The constant
CIVICRM_SMARTY_AUTOLOAD_PATH
is for CiviCRM v5.71+. On earlier versions (5.67-5.70), the analogous constant wasCIVICRM_SMARTY3_AUTOLOAD_PATH
.
Appendix: Milestones¶
- CiviCRM 5.67: Introduce Smarty v3 (opt-in).
- CiviCRM 5.70: Use Smarty v3 on new installations. QA bias toward v3.
- CiviCRM 5.71: Introduce Smarty v4 and v5 (opt-in).
- CiviCRM 5.72: Use Smarty v4 on new installations. QA bias toward v4.
- CiviCRM 5.74: Use Smarty v5 on new installations. QA bias toward v5.
- CiviCRM 5.78: Drop support for Smarty v3.
- CiviCRM 6.5: Use Smarty v5 by default (unless your settings explicitly say otherwise).
- Future (TBD): Drop support for Smarty v2 and v4.
Appendix: Version Matrix¶
For each version of CiviCRM, you can ask a few questions:
- What is the primary Smarty version used for new installations and quality-assurance?
- What is the fallback Smarty version used for older, unconfigured installations?
- What are all the available versions of Smarty?
CiviCRM | Primary | Fallback | Available | |||
---|---|---|---|---|---|---|
CiviCRM <=5.66 | v2 | v2 | v2 | |||
CiviCRM 5.67 | v2 | v2 | v2 | v3 | ||
CiviCRM 5.68 | v2 | v2 | v2 | v3 | ||
CiviCRM 5.69 | v2 | v2 | v2 | v3 | ||
CiviCRM 5.70 | v3 | v2 | v2 | v3 | ||
CiviCRM 5.71 | v3 | v2 | v2 | v3 | v4 | v5 |
CiviCRM 5.72 | v4 | v2 | v2 | v3 | v4 | v5 |
CiviCRM 5.73 | v4 | v2 | v2 | v3 | v4 | v5 |
CiviCRM 5.74 | v5 | v2 | v2 | v3 | v4 | v5 |
CiviCRM 5.75 | v5 | v2 | v2 | v3 | v4 | v5 |
CiviCRM 5.76 | v5 | v2 | v2 | v3 | v4 | v5 |
CiviCRM 5.77 | v5 | v2 | v2 | v3 | v4 | v5 |
CiviCRM 5.78 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 5.79 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 5.80 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 5.81 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 5.82 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 6.0 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 6.1 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 6.2 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 6.3 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 6.4 | v5 | v2 | v2 | v4 | v5 | |
CiviCRM 6.5 | v5 | v5 | v2 | v4 | v5 |
See also¶
- dev/core#4146: Upgrade Smarty to Smarty3+: Geneal discussion. As a discussion, some of its details are transitory. However, it is fairly broad.
- PR #27547: More Smarty 3 prep: Example demonstrating common syntax issues in updating templates from Smarty v2 to v3+.