Skip to content

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 was CIVICRM_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:

  1. What is the primary Smarty version used for new installations and quality-assurance?
  2. What is the fallback Smarty version used for older, unconfigured installations?
  3. What are all the available versions of Smarty?
CiviCRM Primary Fallback Available
CiviCRM <=5.66 v2v2 v2
CiviCRM 5.67 v2v2 v2v3
CiviCRM 5.68 v2v2 v2v3
CiviCRM 5.69 v2v2 v2v3
CiviCRM 5.70 v3v2 v2v3
CiviCRM 5.71 v3v2 v2v3v4v5
CiviCRM 5.72 v4v2 v2v3v4v5
CiviCRM 5.73 v4v2 v2v3v4v5
CiviCRM 5.74 v5v2 v2v3v4v5
CiviCRM 5.75 v5v2 v2v3v4v5
CiviCRM 5.76 v5v2 v2v3v4v5
CiviCRM 5.77 v5v2 v2v3v4v5
CiviCRM 5.78 v5v2 v2v4v5
CiviCRM 5.79 v5v2 v2v4v5
CiviCRM 5.80 v5v2 v2v4v5
CiviCRM 5.81 v5v2 v2v4v5
CiviCRM 5.82 v5v2 v2v4v5
CiviCRM 6.0 v5v2 v2v4v5
CiviCRM 6.1 v5v2 v2v4v5
CiviCRM 6.2 v5v2 v2v4v5
CiviCRM 6.3 v5v2 v2v4v5
CiviCRM 6.4 v5v2 v2v4v5
CiviCRM 6.5 v5v5 v2v4v5

See also