Smarty 2 and Smarty 3 are quite similar in implementation, but do have a few
differences you need to be aware of when upgrading from Smarty 2 to Smarty 3.

= Known incompatibilities with Smarty 2 =

== Syntax ==

The Smarty 3 API has been updated in various places. Some Smarty 2 API calls
need to be updated to comply with Smarty 3. You will get a deprecation notice
with old Smarty 2 API calls, and informed what the new one is. See the README that
comes with Smarty 3 for more information.

The {$array|@mod} syntax has always been a bit confusing, where an "@" is required
to apply a modifier to an array instead of the individual array elements. Normally you
always want the modifier to apply to the variable regardless of its type. In Smarty 3,
{$array|mod} and {$array|@mod} behave identical. It is safe to drop the "@" and the
modifier will still apply to the array. If you really want the modifier to apply to
each array element, you must loop the array in-template, or use a custom modifier that
supports array iteration. Most smarty functions already escape array elements where
necessary such as {html_options}

== PHP Version ==
Smarty 3 is PHP 5 only. It will not work with PHP 4.

== {php} Tag ==
The {php} tag is disabled by default. The use of {php} tags is
deprecated. It can be enabled with $smarty->allow_php_tag=true.

Variables inside {php} blocks no longer share scope with other
{php} blocks on the page, so be aware of this change if you use them.

== Delimiters and whitespace ==
Smarty delimiters {} surrounded by whitespace are no longer treated as Smarty tags.
Therefore, { foo } will be ignored by Smarty, but {foo} is recognized. This change
makes Javascript/CSS easier to work with, eliminating the need for {literal}.
This feature can be disabled by setting $smarty->auto_literal = false;

== 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_) 

For example filename strings must be quoted:

<source lang="smarty">
{assign var=foo value=baz} <-- works ok
{include file="path/foo.tpl"} <-- needs quotes!
</source>

== Extending the Smarty class ==
Smarty 3 follows standard PHP5 constructor rules. When extending the Smarty class,
use __construct() as the class constructor name.  If you implement your own constructor,
be certain to call parent::__construct() first.

<source lang="php">
class MySmarty extends Smarty {
   function __construct() {
       parent::__construct();
    
       // your initialization code goes here

   }
}
</source>

== Autoloader ==
Smarty implements its own autoloader with spl_autoload_register. If you
use an autoloader in your own application, you MUST register yours as well. Using
__autoload() WILL FAIL. This is standard PHP5 autoloader procedure for shared libraries.
See http://us3.php.net/manual/en/function.spl-autoload-register.php 

== Plugin Filenames ==
Since Smarty 3 uses the default spl_autoloader, the plugin filenames are now required to be
lower case. Smarty 2 allowed mixed case plugin names, you must rename them for Smarty 3.

== Scope of Special Smarty Variables ==
In Smarty 2 the special Smarty variables $smarty.section.* and $smarty.foreach.*
had global scope. If you had loops with the same name in subtemplates, you could accidentally 
overwrite values of a parent template.

In Smarty 3 these special Smarty variables now have local scope in the template which 
is defining the loop. In the rare case you need these values in a subtemplate, you have to
pass them as parameters.

<source lang="smarty">
{include file="path/foo.tpl" index=$smarty.section.foo.index}
</source>

== SMARTY_RESOURCE_CHAR_SET ==
Smarty 3 sets the constant SMARTY_RESOURCE_CHAR_SET to utf-8 as the default template charset. 
This is now used with modifiers like escape as the default charset. If your templates use 
another charset, make sure that you define the constant accordingly.

== trigger_error() ==
The API function trigger_error() has been removed. It is still included in the Smarty2 API wrapper.

== Smarty constants ==
The constants 
SMARTY_PHP_PASSTHRU
SMARTY_PHP_QUOTE
SMARTY_PHP_REMOVE
SMARTY_PHP_ALLOW
have been replaced with class constants
Smarty::PHP_PASSTHRU
Smarty::PHP_QUOTE
Smarty::PHP_REMOVE
Smarty::PHP_ALLOW

