README

Version 1.0.1

Kohana-twig is a Kohana 3.3 module for the popular Twig template engine. It was designed to offer the full capabilities of Twig with a strong focus on operating within the guidelines and best practices of the Kohana framework. This module provides a way to use Twigs exactly as Kohana Views are used, and it uses a custom Twig Loader to locate Twig template files in the Cascading Filesystem.

Looking for a Koseven module?

Take a look at koseven-twig by errotan.

Installation

First, add the package to your composer.json requirements:

"tommcdo/twig"  : "1.0.*"

Then, install using composer php composer.phar update

Then, enable the module in APPPATH/bootstrap.php by adding it to the modules initialization:

Kohana::modules(array(
	// ... all your other modules ...
	'twig'       => MODPATH.'kohana-twig',       // Twig templating engine
));

This module was designed for Kohana 3.3, but can be easily made to work with Kohana 3.2 by changing all filenames within the classes/ directory to lowercase.

Usage

Use Twigs just as you use would use Kohana Views. By default, your Twig files go into the twigs directory anywhere in the cascading filesystem, and have a .html extension. (Both of these settings can be configured.) For example, suppose you have a Twig file at APPPATH/twigs/main.html, with contents:

<p>Hello, {{ name }}</p>

Inside your action, you would attach the Twig as follows:

$twig = Twig::factory('main');
$twig->name = 'Tom';
$this->response->body($twig);

Your Twig files can also reference other templates by name, which will be located using the cascading filesystem. Note that the extension of the twig file is omitted; in the following Twig template example, a file called template.html would be located in the cascading filesystem:

{% extends "template" %}

For more information on Twig templates, see Twig for Template Designers

Configuration

Default configuration is kept in MODPATH/twig/config/twig.php. To override it, you can create a config file at APPPATH/config/twig.php (or in the config/ directory of any module that gets loaded before this one) that specifies values to any options you'd like to change.

Extending

Twig offers many ways to extend the base templating environment. In kohana-twig, this can be achieved by overriding the static Twig::env() method. To do so, you can define the class APPPATH/classes/Twig.php as follows:

class Twig extends Kohana_Twig {

	protected static function env()
	{
		// Instantiate the base Twig environment from parent class.
		$env = parent::env();

		// Customize as needed.
		$env->addExtension(new Twig_Extension_Example);
		// ... do more stuff if you'd like ...

		return $env;
	}

} // End Twig

Contributing

Contributions are always welcome and appreciated. Since this is a Kohana module, the main thing I ask is that the code conforms to Kohana's Conventions and Style. If you're not familiar with them, please read them over thoroughly.