ClearSilver PHP Extension


This software is provided as-is; use at your own risk! Neither the author nor his employers can be held responsible for any damages resulting from its use. Having said that, patches are welcome!


The latest version of this document can be found at

Clearsilver is a fast, powerful, and language-neutral template system. It is designed to make it easy to create template driven websites. This extension provides a procedural PHP interface to Clearsilver.

The general idea is that PHP is used to create a Hierarchical Data Format (HDF). The HDF represents the dynamic output of a PHP script. The HDF is then combined with static output in the form of a Clearsilver template to produce the final output. The template is composed of text (usually, but not limited to, HTML) interspersed with Clearsilver tags.

A useful page providing an overview of the Clearsilver software architecture can be found at

Most PHP interaction with Clearsilver involves the creation of the HDF. This can be populated dynamically, read from disk, etc. Many scripts do not output anything[1] to the browser directly, save the output produced through feeding the resulting HDF to the template. However, the flexible design of Clearsilver, specifically its ability to easily work with templates stored as strings, means that this purist approach is not the only use for the technology. For instance, PHP objects which render to strings (e.g. implementing PHP5's __toString method) can internally create an HDF representing their current state. Their output can then be tailored by rendering this data with alternative templates. This provides an elegant solution to those seeking to create applications based on the Model View Controller (MVC) paradigm.

The following steps will enable PHP with support for Clearsilver. Use the first procedure unless you want the extension installed as a built-in module. Both procedures require that Clearsilver is installed[2] and that you have downloaded the PHP Clearsilver distribution.


This extension has been developed on Linux; there is no support yet for any other system.

In the following procedures PHP_CLEARSILVER refers to the version of PHP Clearsilver that you are using (e.g. PHP_CLEARSILVER=php-clearsilver-0.1).

Procedure 1. Installation as external (shared) module

  1. Ensure PHP is installed. The PHP header files must also be available[3].

  2. Run tar -xzvf ${PHP_CLEARSILVER}.tar.gz to extract the downloaded archive.

  3. cd ${PHP_CLEARSILVER} to enter the extracted directory.

  4. Run ./configure --with-clearsilver[4].

  5. Run make to build the Clearsilver extension.

  6. Run make install to install the resulting file in your PHP extensions directory.

Procedure 2. Installation as built-in module

  1. Ensure you have a clean PHP source (>= 4.3.0) available. PHP is available at

  2. Move the downloaded ${PHP_CLEARSILVER}.tar.gz archive to the root directory of the PHP source tree.

  3. cd to the root of the PHP source tree.

  4. Run tar -xzvf ${PHP_CLEARSILVER}.tar.gz to extract the archive.

  5. mv ${PHP_CLEARSILVER} ext/clearsilver

  6. Run ./buildconf --force to make the PHP build system aware of the Clearsilver extension.

  7. Run ./configure --with-clearsilver[4]. If you use --with-clearsilver=shared you will build the extension as a shared module.

  8. Run make to build PHP with Clearsilver support.

  9. Optionally run make test to perform tests which ensure that Clearsilver is working properly.

  10. Run make install to install PHP on the system.

Once installed you can view the output of the phpinfo function to check that PHP Clearsilver is available.

Ensure the extension is loaded, either by altering your PHP INI file or by calling the dl function at the beginning of your script. Then work along the following lines:


Documentation of Clearsilver template syntax can be found at Note that some useful template functions are not documented but can be found in the test examples in the Clearsilver distribution (e.g. subcount).

The HDF is described in detail at, but it is useful to note that it can be derived directly from PHP's array type (see hdf_set_node and hdf_obj_next). Effectively an HDF's node name corresponds to an array's key. Unlike arrays, however, an HDF node can have child nodes as well as a value; in a multi-dimensional array a key's value is either a primitive type (or object) or an array. A PHP implementation of this mapping follows:


This can be accomplished more efficiently by passing an array as the value to hdf_set_node.

Table of Contents

hdf_init — Initialise an HDF data set.
hdf_read_file — Read an HDF data file.
hdf_write_file — Write an HDF data set to disk.
hdf_read_string — Read an HDF string.
hdf_write_string — Serialise an HDF dataset to a string.
hdf_set_value — Set the value of a named node.
hdf_get_value — Return the value of a node in the data set.
hdf_get_node — Return the HDF data set node at a named location, creating it if it does not exist.
hdf_set_node — Set the tree structure of a node
hdf_get_obj — Return the HDF data set node at a named location.
hdf_obj_name — Return the name of a node.
hdf_obj_value — Return the value of a node.
hdf_obj_child — Return the first child of a dataset node.
hdf_obj_next — Return the next node of a dataset level.
hdf_get_child — Return the first child of a named node.
hdf_remove_tree — Delete a subtree of an HDF dataset.
hdf_destroy — Deallocate an HDF data set.
cs_init — Create and initialise a CS context.
cs_parse_string — Parse a CS template string.
cs_parse_file — Parse a CS template file.
cs_render — Render a CS parse tree to a string.
cs_destroy — Clean up and deallocate a CS parse tree.

[1] Except HTTP headers produced by the header function.

[2] Clearsilver is available at

[3] Depending on your system, header files may be distributed separately in a development package.

[4] If Clearsilver is installed in a non default location (e.g. the --prefix option was passed to the Clearsilver configure) or configure complains that Clearsilver cannot be found then pass the Clearsilver installation path as the argument to --with-clearsilver.