X-Cart:Smarty3 update notes for stores upgrading to X-Cart 4.7.x

X-Cart 4.7.0 is not compatible with Smarty2 and requires Smarty3 for its operation. So, if you are upgrading X-Cart to version 4.7.0 from an earlier version using Smarty2, and the X-Cart being upgraded has customizations or 3rd party modules installed, the Smarty update v2 -> v3 associated with the upgrade may cause compatibility issues for your modules and customizations.

This document outlines the procedures that need to be followed to detect and prevent the compatibility issues that may be caused by the Smarty3 update.

PHP 5.3

X-Cart 4.7.0 is not compatible with PHP 5.2 Ensure that you are using PHP version 5.3.0 or later.

Smarty 3 upgrade

General information

If you have any customizations in tpl smarty plugins, after a regular upgrade with standard means of XC4 (via Main page :: Patch/Upgrade center) you need to validate them against Smarty3 API.

The commands listed further in this document for linux/unix operating systems can help you localize code that is incompatible or invalid for Smarty3
For windows servers you may want to try running the said commands using this utility:
http://www.wingrep.com/download.htm
To search only through your custom code, excluding the default code, do the following:
- Make a diff between your pre-upgrade store and a default X-Cart of the same (old) version
  diff -ru /var/www/default_xcart_ver4.6.3 /var/www/your_shop_ver4.6.3 > dir_to_grep/custom_changes.diff
- Copy the files that are missing from /var/www/default_xcart_ver4.6.3 but are present in /var/www/your_shop_ver4.6.3 to the directory dir_to_grep.
  These files can be found in the file dir_to_grep/custom_changes.diff using the line “Only in /var/www/your_shop_ver4.6.3”
- Search for incompatible code only within the directory dir_to_grep
Smarty var/templates_c
In X-Cart 4.7.0 you no longer have to clean up this directory when customizing your store, like it used to be in 4.6.x
Smarty automatically ensures that the compiled templates are up to date.
There is only one case in which you need to clean up var/templates_c. It is when custom smarty pre/post filters are being developed, or when the internal realization of a custom smarty pre/post filter has been changed.
This document is complementary to the files
- Smarty-3.1.21/README
- Smarty-3.1.21/SMARTY_2_BC_NOTES.txt
- Smarty-3.1.21/SMARTY_3.0_BC_NOTES.txt
- Smarty-3.1.21/SMARTY_3.1_NOTES.txt
  
  from the smarty archive
  http://www.smarty.net/download

'Check the syntax of all templates' tpl syntax validation

Right after the upgrade, run the Check the syntax of all templates tpl syntax validation tool
http://YOUR_SHOP/admin/tools.php?start_tpl_syntax_checking=Y
The validation is a time consuming operation. During the check of each template there will be an attempt at template compilation.This may negatively affect page response time for users currently visiting your website. Some errors may occur if a plugin unknown to Smarty is defined in a module that is disabled. You can resolve this by adding the problematic templates to the array $ignore_tpl_files in the file admin/check_tpl_syntax.php and re-run the operation.For example, a template may reference a custom Smarty function or modifier. During normal operation, this does not cause errors, as this function is defined dynamically in a module or some kind of initialisation php code. During the check via the Admin area this initialisation php code is not executed, which results in a Smarty error. As we know it is not truly an error, we can add the template referencing this function to the exclusions list so it won't be checked.

Validation for PHP code compatibility

Calls to private properties/methods are no longer supported.

Review the command output and make sure that every line of code cited in it is executed properly when the respective page is loaded in browser.
export GREP_COLOR='1;37;41';export GREP_OPTIONS='--color=auto';grep -r --include="*.php" "\->_" include/|grep -v '/lib/'|grep -v "_dir_perms\|_file_perms\|_hashedDirectoryLevel"

Examples of incompatible code:
$smarty->_tpl_webmaster_vars
$smarty->_foreach

Output must be empty
export GREP_COLOR='1;37;41';export GREP_OPTIONS='--color=auto';grep -r ">plugins_dir" *|grep -v "/lib/smarty"
http://www.smarty.net/docs/en/variable.plugins.dir.tpl

grep -r ">compile_dir" * |grep -v "/lib/smarty"
http://www.smarty.net/docs/en/variable.compile.dir.tpl

grep -r ">config_dir" * |grep -v "/lib/smarty"
http://www.smarty.net/docs/en/variable.config.dir.tpl

grep -r ">cache_dir" * |grep -v "/lib/smarty"
http://www.smarty.net/docs/en/api.get.cache.dir.tpl

grep -r ">template_dir" * |grep -v "/lib/smarty"
http://www.smarty.net/docs/en/variable.template.dir.tpl

grep -rl assign_ext skin
http://www.smarty.net/docs/en/language.syntax.variables.tpl
For example, instead of
{assign_ext var="dynamic_states[`$prefix`]" value=$next}
the following syntax should be used:
{$dynamic_states[$prefix]=$next}

grep -r current_resource_name *
Replace
$smarty->current_resource_name with
$smarty->template_resource

grep -r assign_by_ref *|grep -v "SmartyBC.class.php\|Smarty.class.php"
Replace
$smarty->assign_by_ref with
$smarty->assignByRef

grep -r append_by_ref *|grep -v "SmartyBC.class.php\|Smarty.class.php"
Replace
$smarty->append_by_ref with
$smarty->appendByRef

grep -rw _tpl_vars * |grep -v "include/lib/smarty"
Instead of calling _tpl_vars, use calls to $smarty->getTemplateVars()
http://www.smarty.net/docs/en/api.get.template.vars.tpl

grep -rl _current_file * |grep -v "include/lib/smarty"
In prefilter and postfilter, replace
$smarty->_current_file with $smarty->template_resource

grep -rl __autoload * |grep -v "htmlpurifier4\|AvaTax"
Output must be empty
Smarty 3 does register its own autoloader with spl_autoload_register. If your code has an existing __autoload function then this function must be explicitly registered on the __autoload stack.
See http://us3.php.net/manual/en/function.spl-autoload-register.php for further details.

grep -r "\->security_settings" * |grep -v "include/lib/smarty"
Output must be empty
If not, implement the following change:
-array_push($smarty->security_settings['MODIFIER_FUNCS'], 'substr');
+$smarty->changeSecurity(array('php_modifiers' => array('substr')));

Rule:

No method from
include/lib/smarty3/SmartyBC.class.php
include/templater/templater.php
can be used in smarty plugins/functions.

To plugins/functions a non-global smarty object is passed (which is not inherited from SmartyBC). This does not allow methods of the SmartyBC/XCTemplater classes to be used in plugins/functions.

A complete replacement of deprecated methods guarantees error free operation.

Output must be empty

grep -r get_template_vars *|grep -v "include/lib/smarty"

grep -r _tpls_index *

grep -r '>trigger_error' *|grep -v "include/lib/smarty"

Validation for Tpl code compatibility

http://smarty-php.googlecode.com/svn/trunk/distribution/SMARTY_2_BC_NOTES.txt

== Delimiters and whitespace ==
Delimiters surrounded by whitespace are no longer treated as Smarty tags.

Review the command output
export GREP_COLOR='1;37;41';export GREP_OPTIONS='--color=auto';grep --color=auto -r -i --include="*.tpl" '{\s\+[$a-z0-9_]\+' skin|grep -v ink_css |grep --color=auto '{\s\+[$a-z0-9_]\+'

There should be no such calls to Smarty tags with whitespace:
{ include file="main/product_details_js.tpl"}

However, an output of css/js code similar to the following is acceptable:
http://i.imgur.com/m1WGGiS.png

http://smarty-php.googlecode.com/svn/trunk/distribution/SMARTY_2_BC_NOTES.txt

== Unquoted Strings ==
Smarty 2 was a bit more forgiving (and ambiguous) when it comes to unquoted strings 
in parameters. Smarty3 is more restrictive. You can still pass strings without quotes 
so long as they contain no special characters. (anything outside of A-Za-z0-9_)

Review the command output and make sure that every tpl mentioned in it works properly.
export GREP_COLOR='1;37;41';export GREP_OPTIONS='--color=auto';grep -r --include="*.tpl" ' [a-zA-Z0-9_]\+=[^" }]\+`' skin

This output is correct:
http://i.imgur.com/LlSOIMr.png

Obsolete syntax {%sectionname.varname%} is changed to {$smarty.section.sectionname.varname}
This command must not return anything:
export GREP_COLOR='1;37;41';export GREP_OPTIONS='--color=auto';grep -r --color=auto "%[a-zA-Z0-9_]\+\.[a-zA-Z0-9_]\+%" skin

If anything is returned, rewrite according to the rules:
http://www.smarty.net/docs/en/language.function.section.tpl

For example, like this:
{$smarty.section.cu.iteration}

The rules for calling the XC4 {interline plugin have changed. Now if the name parameter is passed
{interline name=some_name,
then 2 mandatory parameters must be added:
{interline name=some_name foreach_iteration="`$smarty.foreach.some_name.iteration`" foreach_total="`$smarty.foreach.some_name.total`"}

This command must not return anything:
grep -rw interline skin|grep "name="|grep -v iteration

If anything is returned, add these parameters.

Calls to the special variable $smarty.foreach using another variable like $smarty.foreach.$loop_name.total are no longer supported.

Replace with code similar to the following:
$c@iteration
$c@total
http://www.smarty.net/docs/en/language.function.foreach.tpl#foreach.property.iteration

This command must not return anything:
grep -r "smarty\.[a-z]\+.\\$" *

grep -rw "html_select_date\|fetch" skin|grep -v "RSD_\|review\|HTML_Editor\|Feature_Comparison\|ps_paypal_bml_button"
Check every template (if present) for whether the smarty functions
{html_select_date} and {fetch}
are working correctly.

For html_select_date use the approach from skin/common_files/admin/main/tools.tpl for multi-language support.

Static pages

If the option Parse Smarty tags in the content of embedded pages is enabled, review all your static pages and make sure that they can be opened without errors (or disable the 'Parse Smarty tags in the content of embedded pages' option).

What to do if your upgraded store displays wrongly in the browser or if you see a white screen

Enable XC4 dev mode:
https://help.x-cart.com/index.php?title=X-Cart:Config.php#Development_mode_and_debug_mode_settings
Check the logs in the var/log directory.

How to fix Smarty syntax errors

Basically, to fix the errors like these:

'PHP function 'substr' not allowed by security setting'
'PHP function 'strstr' not allowed by security setting'
'PHP function 'explode' not allowed by security setting'

Modify 'init.php' file in your upgraded X-Cart store as follows:

- add the below lines of code:

# Allow 'substr', 'strstr', and 'explode' to be used as smarty modifiers
$smarty->changeSecurity(array('php_functions' => array('substr',  'strstr', 'explode')));

- right after these lines:

if (!include $xcart_dir . '/smarty.php') {
    func_show_error_page("Cannot launch template engine!", '');
}

X-Cart:Smarty3 update notes for stores upgrading to X-Cart 4.7.x

Contents

PHP 5.3

Smarty 3 upgrade

General information

'Check the syntax of all templates' tpl syntax validation

Validation for PHP code compatibility

Validation for Tpl code compatibility

Static pages

What to do if your upgraded store displays wrongly in the browser or if you see a white screen

How to fix Smarty syntax errors

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

entry points

Tools