Before doing that, allow me to make a premise.

Back in the old days, we could copy our site structure as many times as the number of languages we had to work on, go deep into the pages and make necessary changes.

This worked well enough for static content, but had its downsides:

• There were problems updating content
• If you wanted to send the text to a translation service, you had to pull it from the pages yourself
• When the text came back from the translator, you had to work again to insert it into the pages
• There isn't a standard way to format the text and many translation services don't understand HTML, so you had to exchange Word documents and manually convert the text into HTML again to preserve code cleaniness
• There are problems with foreign character sets, you have to translate the HTML entities or convert between encodings
• The first page on your site was nothing more than a list of languages and flags, that meant the first and most important page of all the site has no content
• If you made a guess choosing your first page language, your other languages had to be manually selected by the user to make the switch.
• If you positioned certain elements into the text, you had to insert them manually again when you put the new content.
• There was no way for the translators to make the changes their selves without asking the webmaster, if they had not basic design skills.
• If they claimed such skills, you had to trust them enough to give them access the site source files and have faith in the fact they will not screw up anything.

The list can go on forever. Guess what? Dynamic websites are even worse! The problem is that most of the programmers build up websites pulling data from an archive (text files, a database connection, a service on the Intertubes) and put this materials into template pages. When preparing or upgrading a site to be multilanguage, you had to have a way to pull different data from database for each idiom. Then you have to figure out how to translate the text into the templates.

There are many ways to solve these problems.

You could manually change all the tables to hold the data for all idioms, and prepare a very big array that holds the strings you put into the template, put this big array in different files, one array for each language, and include the files as the user switches language.

This would be only the beginning, because then you should mantain all these arrays in sync. If you wanted to change this data from a control panel you have to put all the strings in a database. Manage language fallbacks (what if a string is not translated in a language?). What about caching? Then you had to write the procedures for querying, inserting and modifying such data.

Meet Translation2, the Pear module that does all of this for us, and much more. After installing it from the repository, we initialize it using this code:

require_once 'Translation2.php';

$tr =& Translation2::factory('mdb2',$db, array(
'langs_avail_table'        => 'translation_langs',
'lang_id_col'            => 'id',
'lang_name_col'            => 'name',
'lang_meta_col'            => 'meta',
'lang_errmsg_col'        => 'error_text',
'lang_encoding_col'        => 'encoding',
'strings_default_table'    => 'translation_strings', 
'string_id_col'            => 'ID', 
'string_page_id_col'    => 'page_id', 
'string_text_col'        => '%s', 
'autoCleanCache'        => true 
) );

Translation2 uses MDB2 as an archive foundation, so you have either to create a MDB2 connection, or reuse an existing one by passing the database object. As I presume you already use a database connection, I'll skip this part. Let's assume the database object is called $db.

Next we pass an array of parameters, specifying the gory details of the tables holding out our translation data. The example depicts two tables, translation_langs (that lists all languages) and translation_strings (that contains all the text).

The table that holds all the languages needs a column for the language id (like for example 'it' or 'en' or 'fr'), name (like 'English', or 'Espanol', 'Italiano',' 'Francais'), meta (extended name, like 'American English', usually matches the name), error text (when the string is not translated, for example 'not available','non disponibile','non traduit') and encoding ('iso-8859-1','utf-8' and so on). You can call these columns and tables as you want, you just need to pass the names into the parameters array.

The strings table instead has an ID column (I put there an MD5 hash of the strings I want to be translated, but any text will do), the page ID column (so you separate and query strings for different pages), the text column for each language ('%s' in the example means the columns are called after the language ID) and any other parameter you wish to use.

To set the language ID and page ID, simply issue these two commands:

$tr->setLang("it");
$tr->setPageID("LOGIN_PAGE");

You then start to initialize the so called 'decorators', additional features of the translation system. The most useful ones are the Cache decorator (that uses the Cache Lite Pear module) and the fallback decorator (to provide fallback strings in other languages).

An initialization sample of the Cache decorator follows:

require_once "Cache/Lite.php"; 
$tr =& $tr->getDecorator 'CacheLiteFunction'); 
$tr->setOption('cacheDir', '/cache/lang/'); 
$tr->setOption('lifeTime', 3600);

with getDecorator you call the decorator. As you see we had to require the cache module file. Then we set the options: the time the system has to cache strings and the directory to use for caching. There are other options, feel free to explore.

The fallback system is even easier:

$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'en');
$tr->setOption('fallbackLang', 'it');

that means "if you can't find the string in the chosen language, fall back to english. If there isn't an english string, fall back to italian". You can cascade languages as you wish. The function works on a string level, so you can have a complete translated website with only a pair of strings defaulted to another language.

To do queries you use commands like:

$tr->get('PLEASE_LOGIN');

to ask for a translated string,

$tr->getRaw('PLEASE_LOGIN','LOGIN_PAGE');

to ask all translations for a string specifying the Page ID,

$tr->getLangs();

to enumerate all languages, and so on.

You can at this point insert data into the tables yourself, or use the handy administration API that the translation system exposes. Simply initialize it (the parameters array is the same):

$tr_admin = &Translation2_Admin::factory([...continue the same way as the Translation2 constructor...]);

Then you can issue commands like:

$tr_admin ->cleanCache();

to clean the cache

$tr_admin->add("PLEASE_LOGIN', 'LOGIN_PAGE', array("en"=>"Please insert your user name and password in the fields","it"=>"Prego inserire il tuo nome utente e password"));

to insert a new string into the database.

The API enables to easily add, modify and remove languages and strings.

If you want, Translation2 can use as a data source even an XML file or Gettext GNU .po / .mo compiled files. The decorators can also be used to convert between encodings.

That's all, folks!

I hope you liked the article, stay tuned for the next episode of Web localization in PHP: language detection by subscribing to the RSS feed.

I would also be happy to answer to any questions you could have on the Translation2 module. In particular, I've tightly integrated it into a Markdown parser (a PHPBB code like language) and some plugins to provide realtime translations into Smarty templates.

On Windows, instead, there is a layer called Open Database Connectivity (ODBC) that translates the calls from the software to the database, providing a common interface and emulating missing features. Each vendor provides a specific driver, that plugs into the architecture. Via ODBC even a text file or an Excel spreadsheet can be connected and queried like it was a database.

It has been natural to me to start searching the net for a PHP equivalent of that layer. Shortly after starting I found the de facto standard for database abstraction in PHP, called MDB2. Even if it has not the flexibility of a real ODBC layer, it's lack of complexity made it very popular among fellow web programmers at first, just to find out it's ability to grow via extensions and performing in a relatively easy way a set of very powerful and demanding operations.

MDB2 is a Pear library, so you need to follow a procedure to install it. Refer to the Pear website for details.

Just after including the MDB2 scripts into your PHP file

<?

require_once ("MDB2.php");

?>

you need to  create an instance of the database class, like this

<?

$dsn = "your database type://your user name:your password@your server/your database name";

$db = MDB2::factory($dsn);

?>

so you have a connection string that explains how to connect to the database, and an object with multiple methods to perform database operations. You don't need to know other details about the database apart from the ones you put in the Data Source Name (DSN), everything else is handled by the MDB2 object.

After that, you perform vendor agnostic queries like this

$result = $db->queryAll ($sql);

But, as said, the real power behind MDB2 is it's extensions system, for example

$db->loadModule('Extended');

$tablename = "customers";

$data = array("name"=>"Bob","surname"=>"Michael");

$result= $db->extended->autoExecute($tablename,$data, MDB2_AUTOQUERY_INSERT);

I've effectively inserted a new customer into my table without writing a single word of SQL, and without worrying of the actual table structure.

The same applies to interrogation queries, like this

$tablename = "customers";

$where = "`NAME` = 'BOB' AND `SURNAME` = 'MICHAEL'";

$result= $db->extended->autoExecute($tablename,null,
MDB2_AUTOQUERY_SELECT,
$where,null,true,true);

the only SQL here is the where clause, everything else is managed by the library.

You can even store an XML backup of your entire database with a few commands

$db_schema_options = array(
'use_transactions' => true,
'log_line_break' => '<br>',
'idxname_format' => '%s',
'debug' => true,
'quote_identifier' => true,
'force_defaults' => true,
'portability' => true
);

$schema = MDB2_Schema::factory($dsn, $db_schema_options);

$definition = $schema->getDefinitionFromDatabase();

$schema_dump = $schema->dumpDatabase($definition, array(
'output_mode' => 'file',
'output' => $dumpfile
), MDB2_SCHEMA_DUMP_ALL);

where $dumpfile is the file name you want your backup to go to.

The notion of schemas enables your application to seamless update the database across updates. The MDB2 can made automatic modifications of your table definitions to match the ones into the schema.

The library enables to use complex database functions, like transactions, to make your web applications secure and overcome stability problems when delicate procedures are performed, like the cart checkout on a e-commerce website, a money transfer, or any other situation where a power outage or a software interruption can lead to an partial update. Transactions group the operations so that any error will lead to a rollback, preserving the state your data was prior to updating.

If later in the process you want to change your database, for example from MySQL to Microsoft SQL server? Simply change your DSN from mysql to mssql and you are ready!

Did you like this article? Subscribe to my transactional feeds and leave a comment!

Ok, last time we examined the goods and bads of using Smarty, this time we'll install it.

First, make sure you got the right PHP version, it needs at least the 4.0.6. This can be seen by writing an empy page and writing in it, then calling that page.

Next, download the latest stable release from the smarty web site.

I prefer to have all my external libraries and programs in the /lib folder, I strongly racommend it, so decompress the source in the /lib/smarty folder.

I group all my site files in the /site folder, that's very useful too, so create a site folder and put a php file in it, let's call it page.php.

First line in you should configure and initialize smarty, then put your commands to produce some data, and at the end call smarty to output the data in the templates.

The reduced minimal sample is

<?
require ('/absolute/path/to/your/website/root/lib/smarty/Smarty.class.php');
$smarty = new Smarty;
?>

Keep an eye on capitals, as the code is case sensitive! This sample initializes adds the smarty code on top of your php file by inclusion. You'll need the absolute path to your smarty class, substitute as needed.

The smarty code defines a class, it explains to php what a "Smarty" is.
Second line actually defines a variable, called $smarty. This variable points to a new object called Smarty. An object is an "istantiation" of a class, speaking simple an "item" made by following the "instructions". You can have more than a Smarty object in a php file, but rarely you need to.
This Smarty item (let's call it object again and from now on) has properties (attributes) and can execute commands.

Now let's configure a thing or two. As I find it boring to always go checking out the document and site root and substituting, before going on let's write some code to autodetect this.

add this code on top

define('DR', $_SERVER['DOCUMENT_ROOT']);

Now the constant DR contains our document root, we can then modify the subsequent line this way:

require (DR . '/lib/smarty/Smarty.class.php');

each time you need the absolute path to your document root, you can refer to it by using DR.

Ok, this is all good, but if you load the script in the browser, it spits out a blank page.

What remains to do? Configure and execute some commands with the smarty object, of course! But before going on, I need to make a break for a security advice: templates doesn't "need" to be in your document root, they can stay everywhere, and it's highly suggested moving them outside this folder because they could be accessible from the web directly otherwise! Also, you'll need to set some permissions, if you're too loose it's possible you enable complete strangers to write their files everywhere, compromising your hosting server.

Now that I did some information technology terrorism, we can go on!

To give Smarty a command, you use the PHP syntax

$smarty -> command(argument [...]);

while to set a property we use

$smarty -> property = value;

We'll need to set up at least two directories, better three, and two of them should be writable by the web server (not the web users!).

So we create the /templates, /templates_compiled and /templates_cache folders, have templates_compiled and templates_cache writable (you can chmod them 770 from shell or even from the majority of the ftp clients, including the one in Dreamweaver!). Then we make smarty aware of the presence of these directories by adding these lines on bottom of the php file:

$smarty->template_dir = DR . '/templates';
$smarty->compile_dir = DR . '/templates_compiled';
$smarty->config_dir = DR . '/site';
$smarty->cache_dir = DR . '/templates_cache';

Perfect, and we added en passant the config_dir, that tells the Smarty object where to find auxiliary configuration files. We set it to the /site folder itself.

Now, to assign some templates variables, use this

$smarty->assign('firstname','Giancarlo');
$smarty->assign('lastname','Di Massa');

to load, parse and output a template, use

$smarty->display('page.tpl');

This will make the Smarty object go fetch the page.tpl file in the templates directory, so better have something here. Create a page.tpl file and put in it

Hi {$firstname} {$lastname}, how are you?

Save and reload the page.php file. It should output

Hi Giancarlo Di Massa, how are you?

Smarty substituted the two tags with the assigned variables in the page.php file!

If you are a programmer, go study the smarty syntax for programmers, it tells all the commands you can issue on the smarty object. If you're a designer instead, there is a list of all the tags you can use in the templates, you can edit them as if they were static HTML files sprinkled with "programmer's magic".

Most of the other template engines work the same way, for example the VlibTemplate or the RainTPL libraries.

One last word is about the MVC architectures. MVC stays for Model-View-Controller, is a way of separating content (the model) from the code (the controller) and the html (the view). A complete MVC system that takes care of all the aspects of data fetching and manipulation, from database queries to the output, is often called a framework. Smarty can be part of a MVC framework but it's not itself one. Some good PHP frameworks are CakePHP and Symfony.

I use a MVC framework I did myself called Presenza.

Next time we'll better organize our php code and start having something more complex of an Hello World template, so stay tuned.

Programming in PHP without separating content and code can lead to unwanted results, low mantainability and slower production. Even nowadays you can find tons of scripts written by filling HTML pages with chunks of code.

If you do that,

• Web designers with no programming skills will not be able to customize easily your script's appearance.
• If you want to change a site, for example a festivity or a redesign, you will need to face a big amount of work adding again all the PHP code to the new HTML pages.
• You will not be able to focus on the project because you'll have to manage yourself all the aspect of HTML production, from loops to file inclusion.

At my first web works I had these problems too. Building a new site required more work that I expected, because it was also difficult to reuse the code built for preceding customers. Then I started putting all my HTML in separate files, reading it with PHP and doing substitutions where needed. That was really better, I was able to change HTML when I wanted, but nothing more. Data that needed to be presented by "looping" the same HTML needed to be built in PHP, and in some situations I needed some sort of conditional programming in these so called 'template files'. I started to write a full fledged 'template engine' myself when a project saved me. I customized an e-commerce script for a project, and that script used an open source template engine. At first I was... how to say? Puzzled! As I looked over the template files I saw heaps of strange code.. it wasn't PHP so I tought that It was a really bad idea to push the things so further. Half of the script functionality lied in the template files themselves, and I was even a bit angry because I tought I had to learn a new language... inside the language!
But as I was changing the look and feel of that site, so was my opinion of that system. It's not bad after all... no, it's good indeed.. wait, it's great! I never went back and used that engine myself for all my other projects: it's name is Smarty.
Here are some interesting functions:

• You can edit the template files as if they are HTML documents and separe them from the code with a little effort, if you don't want to learn the Smarty language.
• Smarty language is much natural and template oriented than PHP, some things like iterate an array and outputting the same HTML code with the array data inside are very easy to do.
• You can include other files from your templates, these files will be parsed too.
• There's support for variables and constants
• You can produce a piece of HTML, then save it into a variable and reuse it later in the page, even modify it.
• You can put decisional code in the templates, do math operations and store results in new variables.
• Smarty has a plugin system with a very good repository, it's easy to write new plugins and they are autoloaded after you put them into their folder.
• Has an advanced cache system that builds already decoded chunks of templates for speed purposes, so you actually can go even faster than mixing PHP with HTML.
• There are many output buffering functions that give you abilities to change the whole page after it is generated and before is sent to the client, just for example you can with a single line change all your website and tell the system to add target="_new" to all external links.
• You can "skin" your site as you want, it's really possible to do a complete makeup of a whole web project in a day or two, even change skins in realtime!
• There's a template debugger to show data being passed to the engine!

So, by now you would think that Smarty is the best thing after chocolate milk, but it has some negative aspects worth exploring:

• All the HTML is sent at the same time, while with PHP you can send the page in chunks. However that required special attention when you wanted to set cookies, because these need to be sent before everything else.
• Smarty is written in PHP itself. A C++ templating engine maybe would be faster (there are some out there), but then you would need to write new plugins in C++ too. You use smarty by actually loading it entirely in memory each time you need to access template files. If you need to output really simple HTML code in little pieces of code, and these pieces are in separate pages, don't use it. Just an example, if your script just outputs "OK" after the computations, it's better to use echo for the text.
• You will need to learn a new language. It's simple and everything, but it's not rich as PHP itself, it's only a template language. The thing I miss more is the switch conditional construct, you need a series of if..elseif...elseif to emulate it. However this language is always used only to produce the presentation, you'll end up moving everything related to visualization to the templates, never using echo again if not for debug purposes.
• It's not always easy to upgrade an existing project to using a template engine.
• If you use an aggressive caching mode and make changes to the templates, those will not reflect online until you clean the template cache directory.
• Smarty adds memory to your requirements, better have a look at the PHP memory_limit setting.
• It has some good builtin plugins to produce drop downs listboxes, radio buttons and dates inputs in forms, but these elements require formatting the data in a certain way.
• If you dive other scripts directly into the page, some symbols, like the curly braces, can collide with Smarty, that will think you are initiating a template command sequence, so you'll need to surround these pieces of code with literal tags, that tell Smarty not to parse them.

As this argument is very long, I decided to cut it in parts. Next part will be about installing Smarty and starting using it. We'll also have a look at other template engines, and talk about full PHP frameworks that use the MVC paradigm, but don't worry about that right now.