# Upgrading from older releases

These are only changes that could affect existing templates/installations. You'll find all those instructions and additional information about changes/features in [release annoucements](http://phptal.org/).

## 1.2.2 → 1.3.0

`metal:fill-slot` used outside `metal:use-macro` is no longer supported (it used to magically pre-fill slots for later use). Make sure you're using slots as described in the manual.

Removed support for custom code generators using the old `PHPTAL_Php_Tree` interface.

## 1.2.0 → 1.2.2

You don't need to `include`/`require` files other than `PHPTAL.php`. You can remove any superfluous `require`s.

In case autoloading causes any problems and/or you want to use your own autoloader *instead of* PHPTAL's built-in one, execute this after loading `PHPTAL.php`:

spl_autoload_unregister(array('PHPTAL','autoload')); // ugly workaround

and then call `PHPTAL::autoload()` from your autoloader.

## 1.1.14 → 1.2.0

You can automatically find most incompatible templates using the [lint tool](lint).

### Entities and encodings

The biggest difference is in handling of entities. Entities are now unescaped before passing to expressions, i.e. `${php:strlen(`')}'' “sees” just the quote character and returns `1`. In previous versions entities were passed as-is to the expressions (and that example would return `6`).

Newly added unescaping of entities can **expose encoding bugs**. Make sure your pages declare document encoding: For XHTML it's best to send `Content-Type:application/xhtml+xml;charset=UTF-8` or `Content-Type:text/html;charset=UTF-8` HTTP headers. 
-  Don't use `text/xml` MIME type, use `application/xml` instead.

    In HTML add appropriate ''<meta>'' tag or send ''Content-Type:text/html;charset=UTF-8'' HTTP header.

-  If you're not using UTF-8 encoding, you must set encoding you use via `$phptal->setEncoding('ISO-8859-…')` (or just switch to UTF-8 already\! :)

-  Only some 8-bit-based encodings are supported. If your encoding is not supported, you may get away with setting ISO-8859-1 instead.

### Constants

-  All constants except `PHPTAL_VERSION` have been removed. Remove any PHPTAL-specific `define()`s and use class methods (available in earlier versions too) for configuration (e.g. `$phptal->setPhpCodeDestination('/tmp/phptal/')` for custom temp directory.)

-  `PHPTAL_DIR` is gone. PHPTAL now temporarily modifies `include_path` (this may change in the future).

-  Don't include any PHPTAL's files before including `PHPTAL.php`.

### XML

-  XML namespace of `phptal:*` attributes has changed from `http://xml.zope.org/namespaces/phptal` to `http://phptal.org/ns/phptal`. 
-  Comments are required to be well-formed (`--` is not allowed in comments.) Comments starting with `<!--!` are stripped from output. 
-  Duplicate attributes are not allowed and they must be separated with space. `<b title=""title="">` is doubly wrong.

### Other issues

-  use `| nothing` instead of `| false` to avoid getting zeros (`false` is now printed as `0`). 
-  `tal:repeat` doesn't “leak” variables to outer scope 
-  Internal DOM classes have been refactored. Your **custom TAL attributes could break** -- if they did, please complain on the mailinglist\!

## 1.1.x → 1.1.14

In 1.1.13 translation key like `<p i18n:translate="'żółw'" />` was interpreted as `<p i18n:translate="'<C197><C188><C195>­<C179><C197><C130>w'">` and you had to use `msgid "<C197><C188><C195>­<C179><C197><C130>w"` in your `.po` files.

PHPTAL 1.1.14 stops doing this and keys are now left unchanged. The example above would simply expect `msgid "żółw"` in the `.po` file.

If you don't want to change your .po files and want to keep old behaviour, then call `setCanonicalize(true)` of `PHPTAL_GetTextTranslator`, e.g.:

$translator = new PHPTAL_GetTextTranslator(); $translator-\>setLanguage(…); $translator-\>setCanonicalize(true); // add this line $phptal-\>setTranslator($translator);

To upgrade templates, change `<Cxxx>` back to bytes. This code snippet will do it: `preg_replace('/<C(\d+)>/e','chr("\1")',$po_file_content)`