Thankfully the Kohana Route class comes with a method url() which allows us to generate URLs to routes we have specified in the application. In the first tutorial we defined the following routes in application/bootstrap.php:

Route::set('wiki-edit', 'wiki/<page>/edit')
	->defaults(array(
		'controller'=> 'wiki',
		'action'	=> 'edit_page',
	));

Route::set('wiki-save', 'wiki/<page>/save')
	->defaults(array(
		'controller'=> 'wiki',
		'action'	=> 'save_page',
	));

Route::set('wiki-page', 'wiki/<page>')
	->defaults(array(
		'controller'=> 'wiki',
		'action'	=> 'view_page',
	));

Route::set('default', 'wiki')
	->defaults(array(
		'controller' => 'wiki',
		'action'     => 'view_page',
		'id'		 => 'index',
	));

Before we can generate routes we need to set some configuration options in application/bootstrap.php (line ~82). We need to specify the base_url and index_file attributes in the array passed to Kohana::init(). The application on my local install is located at 127.0.0.1/query7kwiki/index.php, so my Kohana::init() statement would read:

Kohana::init(array(
	'base_url'   => '/query7kwiki/',
	'index_file' => 'index.php'
));

In application/views/edit.php the form action attribute was hardcoded to the value /query7kwiki/index.php/wiki/. That can be replaced by:

<?php echo Route::url('wiki-save', array('page' => $page)); ?>

In application/views/single.php there is a link to the edit that specific page. We can replace the href of the anchor tag with:

<?php echo Route::url('wiki-edit', array('page' => $page)); ?>

In the view application/views/create.php change the href of the create page link to:

<?php echo Route::url('wiki-edit', array('page' => $page)); ?>

The wiki application is now portable and can safely be moved to a different server without functionality breaking.

The wiki application has 3 different pages:

• /wiki/somepage/save – handles the saving of the page
• /wiki/somepage/edit – displays a form that allows the user to edit the page
• /wiki/somepage – displays the page

Configuration

We will be using the ORM module to query the database for our wiki pages so we must load it in the application/bootstrap.php file (Line ~99).

Kohana::modules(array(

	'database'   => MODPATH.'database',   // Database access
	'orm'        => MODPATH.'orm',        // Object Relationship Mapping

	));

We also need to specify our database configuration settings. This is done in application/config/database.php.

<?php

return array
  (
  	'default' => array
  	(
  		'type'       => 'mysql',
  		'connection' => array(
  			'hostname'   => '127.0.0.1',
  			'username'   => 'root',
  			'password'   => 'root',
  			'persistent' => FALSE,
  			'database'   => 'query7kwiki',
  		),
  		'table_prefix' => '',
  		'charset'      => 'utf8',
  		'caching'      => FALSE,
  		'profiling'    => TRUE,
  	),
  );

  ?>

Model

Compared to most ORMs (Django, Doctrine, Propel), Kohana’s ORM is relatively light. You don’t need to specify the fields of your table as the Kohana ORM doesn’t attempt to generate the tables for you. It simply maps attribute names of the model object to field names in the database table. Be sure to check the Kohana Documentation for a detailed explanation of the ORM.

application/classes/model/page.php

class Model_Page extends ORM
{

	protected $_table_name = 'page';

	public function rules()
	{
		return array(

			'title' => array(
						array('not_empty')
							)

		);
	}

}

Execute the following SQL:

CREATE TABLE `page` (
`id` INT( 11 ) NOT NULL AUTO_INCREMENT PRIMARY KEY ,
`title` VARCHAR( 255 ) NOT NULL ,
`content` TEXT NOT NULL
) ENGINE = MYISAM ;

Routing

I define all routes at the bottom of application/bootstrap.php, however if you are working on a large application it may beneficial in the long run to define them in a separate file and then include them into the bootstrap file.

Route::set() accepts 2 parameters. The first is the name of the route and the second is the URI pattern it should match. Because Route::set() returns an instance of Kohana_Route, we can chain the defaults method onto it. There we specify the controller and action that should be executed if the route is matched.

The <page> section of the URI pattern is captured from the URI and automatically passed to the controller method as an argument.

Route::set('wiki-edit', 'wiki/<page>/edit')
	->defaults(array(
		'controller'=> 'wiki',
		'action'	=> 'edit_page',
	));

Route::set('wiki-save', 'wiki/<page>/save')
	->defaults(array(
		'controller'=> 'wiki',
		'action'	=> 'save_page',
	));

Route::set('wiki-page', 'wiki/<page>')
	->defaults(array(
		'controller'=> 'wiki',
		'action'	=> 'view_page',
	));

Route::set('default', 'wiki')
	->defaults(array(
		'controller' => 'wiki',
		'action'     => 'view_page',
		'id'		 => 'index',
	));

Views

Read this tutorial on generating domain-independent, non hardcoded URLs

application/views/single.php

<html>
	<head>
		<title><?php echo $page; ?></title>
	</head>

	<body>

		<h1><?php echo $page; ?></h1>
		<p>
			<?php echo $content; ?>
		</p>
		<hr>
		<p>
			<a href="/query7kwiki/index.php/wiki/<?php echo $page; ?>/edit">Edit</a>
		</p>
	</body>
</html>

application/views/create.php

<html>
	<head>
		<title><?php echo $page; ?> - Create</title>
	</head>

	<body>

		<h1><?php echo $page; ?></h1>
		<p>This page does not exist. <a href="/query7kwiki/index.php/wiki/<?php echo $page; ?>/edit/">Create?</a></p>

	</body>
</html>

application/views/edit.php

<html>
	<head>
		<title><?php echo $page; ?> - Edit</title>
	</head>

	<body>

		<h1><?php echo $page; ?> - Edit</h1>
		<p>
			<form method="POST" action="/query7kwiki/index.php/wiki/<?php echo $page; ?>/save/"">

				<textarea rows="10" cols="60" name="content"><?php echo $content; ?></textarea>
				<br />
				<input type="submit" value="Edit Page" name="submit">
			</form>
		</p>
	</body>
</html>

Controller

The wiki only has one controller, Controller_Wiki, located in application/classes/controller/wiki.php. All of the methods accept one parameter, the name of the page which is automatically passed by the URL Router.

The action_view_page() method will display the wiki page if it exists or a ‘create’ page if it does not exist. $single->loaded() will return true if the ORM returned a result, so if the page exists we load the ‘single’ view and attach the appropriate variables to the view, if it does not exist then we load the ‘create’ view.

public function action_view_page($page)
{

	$single = ORM::factory('page')
			->where('title', '=', $page)
			->find();

	if($single->loaded())
	{
		$v = View::factory('single');
		$v->page = $page;
		$v->content = $single->content;
				}
	else
	{
		$v = View::factory('create');
		$v->page = $page;
	}

	$this->response->body($v);

}

action_edit_page() returns the ‘edit’ page with the correct content field.

public function action_edit_page($page)
{
	$single = ORM::factory('page')
			->where('title', '=', $page)
			->find();

	if($single->loaded())
	{
		$content = $single->content;
	}
	else
	{
		$content = '';
	}

	$v = View::factory('edit');
	$v->page = $page;
	$v->content = $content;

	$this->response->body($v);
}

action_save_page() handles saving the page after the user submits the edit form. It first checks to see if the page exists. If it does exist then we update the content attribute of the model with whatever was posted in the form. If it doesn’t exist then we make a new page by instantiating a new model, assigning the title and content attributes and saving it.

public function action_save_page($page)
{
	$single = ORM::factory('page')
			->where('title', '=', $page)
			->find();

	$content = $this->request->post('content');

	if($single->loaded())
	{
		$single->content = $content;
		$single->save();
	}
	else
	{
		$new_single = new Model_Page();
		$new_single->title = $page;
		$new_single->content = $content;
		$new_single->save();
	}

	$this->request->redirect('http://127.0.0.1/query7kwiki/index.php/wiki/' . $page);

}

Full source code of the application is available on Github.

• Twig downloaded and unarchived
• Twig Autoloader registered

Template Class

The use of the Settings class is self explanatory. Just replaces the instances of Settings with your own configuration system (or just strings). All Twig settings are documented here.

class Template
{

	public $context = array();

	private $template;

	public function __construct($template)
	{		

		$loader = new Twig_Loader_Filesystem(Settings::get('template_directories'));

		$twig = new Twig_Environment($loader, array(

			'cache' => Settings::get('template_cache_directory'),
			'debug' => Settings::get('debug'),

				)

		);

		$this->template = $twig->loadTemplate($template);

	}

	public function setContext(array $context = array())
	{
		$this->context = array_merge($context, $this->context);

	}

	public function render()
	{
		return $this->template->render($this->context);
	}	

	public function __toString()
	{
		return $this->render();
	}

	public function __set($key, $val)
	{
		$this->context[$key] = $val;
	}

	public function __get($key)
	{
		return $this->context[$key];
	}

}

Simple Example

hello.html

Hey there <strong>{{ name }}</strong> welcome to the website.

Code in controller

$t = new Template('hello.html');
$t->name = 'Frank';
echo $t->render();

Output:

Hey there <strong>Frank</strong> welcome to the website.

Example with Inheritance

base.html

<h3>Welcome to the website<h3>
{% block content %}{% endblock %}

hello.html

{% extends 'base.html' %}
{% block content %}
Hey there <strong>{{ name }}</strong> welcome to the website.
{% endblock %}

Code in controller

$t = new Template('hello.html');
$t->name = 'Joe';
echo $t->render();

Output:

<h3>Welcome to the website<h3>
Hey there <strong>Joe</strong> welcome to the website.

When should I use a framework?

Frameworks should be used when constructing web applications. Any application that involves a database, forms, sessions, cookies or a remote service (such as Twitter or Facebook) will benefit from being powered by a framework. There is no need to use a framework for a website that has only one or two pages, nor for command line utility scripts.

What features do frameworks provide?

• Database abstraction. Frameworks can abstract away SQL-vendor specific features. This allows you to change your SQL database without needing to rewrite any code. For example, switch from MySQL to Postgres or MSSQL. Some frameworks can also handle database relations automatically, which saves you having to write JOIN queries.
• Cache abstraction. Rather than using backend specific caching functions (such as apc_add and apc_fetch), you use a generic caching class which has support for multiple backends such as Memcache, APC and XCache.
• Form management. Symfony2 and CakePHP allow the developer to define forms as PHP code. The framework then handles all HTML widget generation, form validation and CSRF security automatically.
• Authentication. Most frameworks come with a generic user authentication module. They handle logging in and logging out, registration, session management and permissions. They are typically very easy to modify and add your own custom fields.
• Easy Debugging and Profiling. Kohana3 and Symfony2 come with debug toolbars. These allow you to inspect global variables, database queries, logs and load times in the current request.
• Internationalization. Built in translation frameworks let you easily create country specific versions of your website.

What benefits do I get from using a framework?

• Portability. Database and cache abstraction allows your application to be used on many different server setups. If your application is open source, more people will be able to install it.
• Shorter development time. Because your not writing the same boilerplate user authentication, database and form code, development time is shortened dramatically.
• Application security – Security features such as authentication and permissions are handled for you by the framework. Database inputs are automatically sanitised and most frameworks have cross site request forgery (CSRF) protection built in.
• Community supported – Frameworks have forums, mailing lists and IRC channels supporting them. If you encounter a problem with the framework, chances are someone else has and a fix has already been made.
• Plugins and modules. Members of the community release plugins and modules which you can download and use in your application. These would be things such as integration with 3rd party APIs (Facebook, Twitter) and features such as template engine integration.
• Enforces good coding standard. Most frameworks force you to follow the Model, View, Controller principle. This makes you (the developer) think about how your code will be structured before you write it, making it of higher quality.
• Future proof your application. Frameworks are well documented and tested. If another developer was brought in on the project, or you sold your project, the new developer would just need to read up on the framework documentation and then would understand the code. If a framework wasn’t being used then time and money would need to be put into training the new developer.

What framework should I use?

Everyone has their own opinion on which is the “best” framework. I recommend you have a look at all frameworks linked below, they each have different styles of structuring the application. If you have experience with Ruby On Rails then you may want to look at CakePHP and Trax. They both have ActiveRecord implementations and model themselves after Rails. QPHP will seem familiar for those with ASP.NET experience and Symfony2 will make people who know Java feel at home (Symfony2 overview). Also be sure to check out Kohana, Code Igniter, Yii, Lithium, Fuel, Alloy and Akelos before making your decision.

Overview

Symfony2 is a full stack web enterprise framework created by well known PHP guru Fabien Potencier. The framework itself is divided up into several different packages (Bundles) which are tied together with a Kernel object. Being a full stack framework Symfony2 offers almost everything you will need out of the box:

• Model, View, Controller separation
• Database management with Doctrine2
• Templating with either straight PHP templates or Twig
• Testing with a layer built upon PHPUnit
• Emails with SwiftMailer
• Custom form, validation, auth, event and caching systems.

One thing that distinguishes Symfony2 from other frameworks is that it relies heavily on Dependency Injection and as a result alot of configuration needs to take place. The standard of the Symfony2 is top notch, it is clearly set out, commented and tested. The full stack nature of Symfony2 is also a big strength. If you were to start a high upkeep project, you could be sure that in 5 years all components of the stack (forms, validation, templating, testing, database) would still be maintained. An overview of the architecture of a Symfony2 application can be found here.

PHP, XML or Yaml?

One of Symfony2′s unique features is that it allows you configure the majority of your application in either PHP, XML or Yaml. When Symfony2 is running in production mode, all XML or Yaml files are compiled and cached as native PHP files, so there is no performance advantage gained by using straight PHP. Frameworks such as Zend Framework only allow application settings to be defined in XML, Yaml or .ini format, Symfony2 goes a step further and allows you to specify functionality such as validations and url routes in these formats. For example, the following code snippets show how to validate the presence of the $name attribute in the Author object below.

// Sensio/HelloBundle/Author.php
class Author
{
    private $name;
}

PHP

// Sensio/HelloBundle/Author.php
use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Components\Validator\Constraints\NotBlank;

class Author
{
    private $name;

    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addPropertyConstraint('name', new NotBlank());
    }
}

Yaml

# Sensio/HelloBundle/Resources/config/validation.yml
Sensio\HelloBundle\Author:
    properties:
        name:
            - NotBlank: ~

XML

<!-- Sensio/HelloBundle/Resources/config/validation.xml -->
<class name="SensioHelloBundleAuthor">
    <property name="name">
        <constraint name="NotBlank" />
    </property>
</class>

source

Bundles

Bundles are packaged classes and methods which provide functionality for your application. Symfony2 ships with bundles that are required for the framework to run. These are things like DoctrineBundle (database), TwigBundle (templating), SwiftmailerBundle (emails) and ZendBundle (Zend Framework integration). Code inside bundles must follow the defined structure and naming guidelines, specified here so that Symfony2 can automatically know where to find controllers, tests and translations. Bundles are what other frameworks would call plugins, modules or extensions. You can download Bundles developed by the community that provide features like user registration, Facebook integration and blog functionality from symfony2bundles.org.

Testing

As you could expect with any enterprise framework, Symfony2 comes with complete testing functionality. Symfony2 provides a layer on top of PHPUnit for you to define your tests. You can write standard unit tests (as you would with PHPUnit) as well as ‘functional tests’. Functional tests are essentially automated front end testing, Symfony emulates a browser request to a specific URL of your application and you define what output you are expecting to see. This could be a specific HTTP response code or some HTML on the page.

HTTP Caching

Every Symfony2 controller returns an instance of the Response object. The Response object has several methods available that allows the developer to set specific HTTP headers which are then sent to the browser. This allows the developer to have complete control over every header that is being sent back to the browser. The slides below show how powerful this feature can be.

Community

Although Symfony2 is still in pre-beta, the majority of functionality is already in the framework. All official documentation and guides can be found on the Symfony2 website Symfony-Reloaded.org. If your a twitter user than I recommend following @fabpot (creator, developer of Symfony2), @jwage (developer Symfony2, Doctrine) and @symfony (aggregated Symfony news). An RFC was recently posted on the phpBB4 wiki suggesting that phpBB4 be built using Symfony2. If it gets accepted then we could expect the thousands of mod developers for phpBB2 & 3 would learn Symfony2 while developing mods for phpBB4.

Conclusion

I suspect developers with previous experience in Symfony1, Java and .NET would find Symfony2 perfect and won’t hesitate to use it. Those who use PHP frameworks such as Code Igniter, Kohana, CakePHP and Yii will find Symfony2 very different. The strict naming convention, long namespaces and dependency injection may put them off. If phpBB4 does decide to use Symfony2 then other open source PHP projects may follow and Symfony2 will no doubt become the most popular PHP framework. Regardless of developer preferences or immediate success, Symfony2 is an amazing piece of code and I highly suggest you try it out.

Links

• Symfony2 Homepage
• Symfony2 Documentation
• Symfony2 on Github

This tutorial will cover how to use different types of proxies – SOCKS4, SOCKS5 and HTTP with cURL.

Basic cURL Request

We’ll start by creating a simple cURL script that requests the web page checkip.dyndns.org and displays the result on the screen. The website just displays our current IP address, this is useful when working with proxies. Below is our very basic cURL request.

$url = 'http://checkip.dyndns.org/';

$c = curl_init($url);

curl_setopt($c, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($c);

echo '<pre>';
var_dump($result);
echo '</pre>';

curl_close($c);

As we can expect, the output will be your IP address.

202.183.56.21

Using Proxies with cURL

To use proxies with cURL we need to set 2 additional cURL options: CURLOPT_PROXYTYPE and CURLOPT_PROXY. CURLOPT_PROXYTYPE should be set to either CURLPROXY_SOCKS5 or CURLPROXY_SOCKS4, depending on the type of proxy you are using. CURLOPT_PROXY should be set to the IP address and port of the proxy you are using.

If you are using an HTTP proxy then you only need to set CURLOPT_PROXY to your proxy. CURLOPT_PROXYTYPE automatically defaults to CURLPROXY_HTTP.

As you can expect, the following script displays the IP address of the proxy.

$url = 'http://checkip.dyndns.org/';

$c = curl_init($url);

curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5);
curl_setopt($c, CURLOPT_PROXY, '68.119.83.81:27977');

$result = curl_exec($c);

echo '<pre>';
var_dump($result);
echo '</pre>';

curl_close($c);

Note: You’ll need to use your own proxy. The one supplied is made up.

We would be covering the following topics in this series

1. Installing and Configuring CakePHP
2. Understanding MVC
3. Creating a simple blog
4. Adding advanced features to your blog – Understanding Models, Views, Controllers in Depth
5. Understanding Helpers
6. Ajaxifying comments, adding content summary and Gravatar to your blog
7. Securing your blog

In this article, we’ll just take a look at installing and configuring CakePHP.

Download the latest version of CakePHP framework from CakePHP.org. Make sure to download the stable release and not the release candidate.
Unpack the contents of the Cake archive inside the “www” folder of wamp or mamp directory.You now have a folder in your document root named after the release you’ve downloaded. We will rename this
folder to “newblog” (or you can have any name of your choice) . The directory structure inside this folder should look something like this:

We would be doing all our work inside the app folder. The cake folder stores all the core functions for CakePHP. Make sure that you do not edit anything inside this folder. The vendors folder is where youíll place third-party PHP libraries you need to use with your CakePHP applications.
You will notice that there are several other folders inside the app folder. We will take a look at each of them as we go on developing our blog.

Configuring Cake PHP

Configuring Cake PHP is pretty easy. Go inside the app –> Config folder and open the database.php.default file with your favorite editor. Scroll down to the following array in the file:

 < php 	var $default = array( 	'driver' => 'mysql',
'persistent' => false,
'host' => 'localhost',
'login' => 'username',
'password' => 'password',
'database' => 'databasename',
'prefix' => '',
);
?>

Enter your login, password, database name and save the file as database.php. That’s it!

Open you browser and go to http://localhost/cakephp. You should now see the following success page:

However, you might see a colorless page like this:

It means that rewrite_module is not enabled in your Apache Server. To do so, click on the wampserver icon in your system tray and go to Apache–>Apache modules and click on the rewrite_module in the list to enable it. It should work fine after rewrite_module has been enabled.

So, now that you’ve CakePHP up and running, we’ll move on to the next step in subsequent article. Do leave your comments if you’ve any doubts regarding this article.

The book starts by defining what a content management system is and what features it needs to have. It then gives some background into the Model View Controller and Object Relational concepts as well as the Factory, Singleton, Observer and Command design patterns. If you haven’t used a CMS before and don’t know PHP5 OOP, this chapter prepares you excellently for the rest of the book.

The remaining 13 chapters each cover a feature of the framework. This includes:

• Database abstraction
• Access control, user authentication
• Framework extensions/plugins
• Caching
• Internationalization
• Error handling
• Menus

Brampton has done a great job at explaining each feature before he shows any code. This ensures someone new to content management systems will understand the feature before being bombarded with snippets of code. For example, the chapter on Menus opens by explaining what function a menu has in the context of a CMS (as opposed to a static HTML website). It then talks about how menus can be represented in code and how they can be stored efficiently in a CMS. A screenshot of the database schema is then shown and each field is explained in detail. Finally we are walked through the important methods from the menu class.

Overall I found the book to be a great learning experience. It gives a good insight into how Aliro and other content management systems work under the hood. I feel it is important to emphasis that all implementations of framework features (database abstraction, menus, plugins etc.) are shown as code take directly from the Aliro framework. The book doesn’t teach you how to implement a feature, it shows you how the feature is implemented in Aliro. I found this to be a positive because Aliro is a full featured CMS. In many other books that teach you how to build a web application, the web app that is made has an absolute minimal feature set and you don’t learn a whole lot. Because all code is taken from Aliro, no corners are cut and the detail is superb.

There are a few negative points about PHP5 CMS Framework Development. Unfortunately one comes from the fact that all code snippets are taken directly from Aliro. There are several design decisions Brampton made that now contradict modern day PHP best practice. For example Aliro uses its own style of class naming, not the Zend_Style_Names (namespaces were implemented in PHP a year after this book was published). It also makes very heavy use of singletons which depending on what developer you ask, is a bad thing. There is no chapter on testing which is surprising considering the nature of application that is being built.

If your thinking about writing your own PHP framework or large web application then I recommend you read this book. Brampton does a great job at introducing each framework feature, so even if you have no experience with content management systems, you will be able to understand what he is talking about. Just keep in mind that this book shows and explains one way of implementing a feature, and that way isn’t necessarily the best or only way.

A 2nd edition of PHP5 CMS Framework Developed his since been published.

New for this edition is a chapter discussing the transformation of URLs to turn ugly query strings into readable strings that are believed to be more “search engine friendly” and are certainly more user friendly. This topic is then extended into a review of ways to handle “friendly” URLs without going through query strings, and how to build RESTful interfaces.

The final chapter discusses the key issues that affect a wide range of specific content handlers and explores a practical example in detail. – source

PHP5 CMS Framework Development on PacktPub

The Plan

We will be building a module that replaces Kohana’s own view layer (Kohana_View). It will use the PHP template library Twig. We want our own view layer to be API compatible with Kohana’s view layer. This will ensure that other modules work out of the box and that the only code the developer will need to alter in their application are the templates (so that they are Twig compatible). No code in any controller will need to be modified.

Because Kohana follows HMVC (see beginners introduction to Kohana) we will be calling our class View. This means that all calls in the application to the class of View will be to the View class in our module, not Kohana’s own View class.

Directory Structure

Enabling The Module

The name of any Kohana module is the same name as the directory inside the modules directory. So in this case it is twig. To activate any module, we must add it to the array passed to Kohana::modules in application/bootstrap.php.

application/bootstrap.php – line 88

Kohana::modules(array(
	'twig' => MODPATH.'twig',
	// 'auth'       => MODPATH.'auth',       // Basic authentication
	// 'cache'      => MODPATH.'cache',      // Caching with multiple backends
	// 'codebench'  => MODPATH.'codebench',  // Benchmarking tool
	// 'database'   => MODPATH.'database',   // Database access
	// 'image'      => MODPATH.'image',      // Image manipulation
	// 'orm'        => MODPATH.'orm',        // Object Relationship Mapping
	// 'oauth'      => MODPATH.'oauth',      // OAuth authentication
	// 'pagination' => MODPATH.'pagination', // Paging of results
	// 'unittest'   => MODPATH.'unittest',   // Unit testing
	// 'userguide'  => MODPATH.'userguide',  // User guide and API documentation
	));

Twig

We will be using Fabien Potencier’s Twig project as a replacement templating engine for Kohana. The Twig files themselves will be stored in modules/twig/Twig/. If you are familiar with git you could create a git submodule of Twig so you can update Twig independently from our twig Kohana module. However for the sake of this tutorial it is easier just to download the tarball and extract it.

Rather than including all Twig files explicitly (using include or require statements) we will use Twig’s own autoloader. We could call it either in application/bootstrap.php or modules/twig/init.php. Since the autoloader is specific to the twig module (and not to the application) it is better to put it in modules/twig/init.php. Every init.php file in every enabled module is called automatically every request by Kohana.

modules/twig/init.php

require 'Twig/Autoloader.php';

Twig_Autoloader::register();

Configuration

Each developer that uses our twig module will have a different template directory and will want to pass different options to the Twig library when it’s instantiated (such as whether Twig runs in debug mode). Rather than hard coding these options into our module (which would force every developer using it to alter module code) we can use Kohana’s configuration system.

Because the configuration for our module is application specific, create application/config/twig.php

application/config/twig.php

// http://www.twig-project.org/book/03-Twig-for-Developers

return array(

	//Edit these per app.
	'template_dir' => 'C:/wamp/www/kohanaresources/application/views/',
	'cache_dir' => 'C:/wamp/www/kohanaresources/application/cache/',

	//Set to false in production application
	'auto_reload' => true,
	'debug' => true,

	//Misc settings. Don't touch unless you know what your doing.
	'trim_blocks' => false,
	'charset' => 'utf8',
	'base_template_class' => 'Twig_Template',
	'strict_variables' => false,

);

To access these array parameters that the developer sets, its a simple matter of:

Kohana::config('twig.template_dir');

The View Class

modules/twig/classes/view.php is going to contain our class, View. It will handle the rendering of the template using Twig. As discussed above, we want our View class to have the same API as Kohana_View, so we will copy system/classes/kohana/view.php and make a small alteration to it. Most of the methods in Kohana_View provide different ways to set variables to the instance of Kohana_View. For example all three of these essentially do the same thing:

$v = new View('some/template');

$v->website = 'Query7';
$v->set('website', 'Query7');
$v->bind('website', 'Query7');

All loading and parsing of the template file is done in View::capture(). This is the only method from the original Kohana_View class that we will need to alter. Here is our new method in full:

modules/twig/classes/view.php – View::capture

protected static function capture($kohana_view_filename, array $kohana_view_data)
{
	if (isset(View::$_global_data))
	{
		$data = array_merge($kohana_view_data, View::$_global_data);
	}
	else
	{
		$data = $kohana_view_data;
	}

	$loader = new Twig_Loader_Filesystem(Kohana::config('twig.template_dir'));

	$twig = new Twig_Environment($loader, array(

		'cache' => Kohana::config('twig.cache_dir'),
		'debug' => Kohana::config('twig.debug'),

		'auto_reload' => Kohana::config('twig.auto_reload'),
		'trim_blocks' => Kohana::config('twig.trim_blocks'),
		'charset' => Kohana::config('twig.charset'),
		'base_template_class' => Kohana::config('twig.base_template_class'),
		'strict_variables' => Kohan::config('twig.strict_variables')
	));

	$template = $twig->loadTemplate($kohana_view_filename);

	return $template->render($data);
}

Our function first combines all data to be passed to the template in a single array, $data. It then instantiates Twig_Loader_Filesystem and passes the location of the template directory to it. Twig_Enviroment is then instantiated and the different configuration options are passed there. Finally the template is loaded and rendered.

Example of twig in use

some method in a controller

$v = new View('colors.html');

$v->colors = array('red','blue','yellow','purple');

$this->request->response = $v->render();

colors.html

{% for c in colors %}
    {{ c }},
{% endfor %}

output

red,blue,yellow,purple,

Finishing Up

After you have finished any Kohana module you should write the necessary documentation and tests. Kohana has it’s own module that integrates PHPUnit with the Kohana framework. The majority of Kohana modules are open source on Github, with repositories named kohana-*modulename*. Finally you will want to promote your module. Announcing it on the Kohana forum and on Twitter are good ways to get it some attention.

If you have any questions or feedback please leave them in the comments below.

Installation

Installing Kohana is very straight forward, just download the latest stable version of Kohana and unzip it. No need to mess around with yaml or xml files like other frameworks. Navigating to the directory on your web server should give you a page similar to…

Filesystem

The filesystem plays a big part in the operation of the Kohana framework. Kohana follows the HMVC pattern (hierarchical model view controller). This means that the same filesystem structure exists at multiple locations in the framework. The following directories exist in the application, system and in all module directories:

• classes
• config
• i18n
• messages
• tests

When calling a class in Kohana, the autoloader checks if the class exists first in application/classes/ , then in each of the installed modules, classes subdirectory and finally in system/classes/. If the file cannot be found then an exception is thrown. Kohana follows the Zend_Class_Naming style. For example, if you instantiated a class named Hello_World, Kohana would look at each of the following locations in this order. If it finds that it exists, it will return.

• application/classes/hello/world.php
• modules/*moduleName*/classes/hello/world.php (it would check every installed module)
• system/classes/hello/world.php

Configuration

All configuration is stored in the config directory (Because of the HMVC filesystem, there are multiple config directories and the specific configuration file you specify can exist in any of them). Configuration files return an array. For example if we made the file application/config/hello.php and set the contents as

return array(

    'website' => 'Query7',
    'url' => 'http://www.query7.com'

);

If we wanted to access the properties of this configuration file we would use the Kohana::config() method.
Calling

Kohana::config('hello')

would return

return array(
    'website' => 'Query7',
    'url' => 'http://www.query7.com'

);

and calling

Kohana::config('hello.website')

would return

Query7

Modules

Modules provide additional features and can be easily added to your application. Kohana3 ships with some modules including database, orm and userguide (which contains documentation). To enable modules in your project open application/bootstrap.php and scroll to around line 78. There you will see:

Kohana::modules(array(
    // 'auth'       => MODPATH.'auth',       // Basic authentication
    // 'cache'      => MODPATH.'cache',      // Caching with multiple backends
    // 'codebench'  => MODPATH.'codebench',  // Benchmarking tool
    // 'database'   => MODPATH.'database',   // Database access
    // 'image'      => MODPATH.'image',      // Image manipulation
    // 'orm'        => MODPATH.'orm',        // Object Relationship Mapping
    // 'oauth'      => MODPATH.'oauth',      // OAuth authentication
    // 'pagination' => MODPATH.'pagination', // Paging of results
    // 'unittest'   => MODPATH.'unittest',   // Unit testing
    // 'userguide'  => MODPATH.'userguide',  // User guide and API documentation
    ));

To enable a module, just uncomment the line (remove the initial //). To install your own modules, put the un-archived module in your modules directory, and add a line to the array above. For example if you were installing the hive module (an ORM for Kohana), you would put the hive directory into your modules directory and add the following line to the array passed to Kohana::modules()

'hive' => MODPATH.'hive'

Now that the hive module is installed, the Kohana autoloader will add modules/hive/ to it’s path so it will check in that directory for classes and configuration files (if necessary).

Most modules come with their own configuration scripts. Because of the way the Kohana3 file system is structured, you can copy the default configuration script from modules/*name*/config/*script*.php and paste it in application/config/*script*.php and Kohana will immediately start using the configuration file located in your application directory. A good example of this is with the database module. The file modules/database/config/database.php contains all of the database connection information. Because this information is specific to our application it should be copied over to application/config/database.php and values edited appropriately. You do not need to delete the old modules/database/config/database.php because Kohana looks for application/config/database.php first and as soon as it finds it, it will return. Nothing in modules directory should contain anything specific to your application.

Modules can contain a file called init.php in the root directory (modules/*moduleName*/init.php). If the module is installed, this file is called every request.