Welcome to my tutorial entitled “Getting started with Kohana”, as a Kohana 1.x veteran, and a former Code Igniter user it’s often difficult to know what users need to know when they’re new to a framework. I’ve done my best, but I can’t coem up with all things to all people in the first sitting, comments, suggestions, aberrations and more welcome in my inbox.

With my first forray into Kohana 2.1 fresh in my mind - I have opted to start out writing a simple tutorial; note - I say writing, I can’t abide video tutorials… I’m a data skimmer, and it’s hard to skim a video; unless of course they’re bookmarked like the videos on TED are, which I understand we can’t do on the Kohana site

For this particular project, I am using the inexpensive and reliable www.hosted-projects.com service, costing a mere $7 a month, and he does daily backups… and offers a pain free set up. A free alternative, if you are so inclined is Assembla, thanks to easylancer for that tip. I won’t however be covering how to use Subversion, at least not in this tutorial/how-to.
Getting Kohana

There are two ways to grab Kohana, the easiest is to use the release package that they provide; there’s a setback though, Kohana is a moving target, bugs are being discovered and fixed (quickly!) all the time, and while you should try to develop on a stable platform (by using the release version) - it is often advantageous to use the subversion, version.
Using The Release Version

To grab the release version it’s easy, just go here, and assemble the package you want, with all the languages you fancy (I happen to use English (UK)) but you can grab whichever you prefer.

You should unpack this archive, and move it to your working directory (that is, in my case ~/Sites/Example/). Assuming that your directory is now laid out as such, you should - if we’re using subversion - add the resources to svn and then continue.

# ls ~/Sites/Example/
drwxr-xr-x 13 leehambley leehambley 442 10 Mar 14:58 application
-rw-r–r–@ 1 leehambley leehambley 3970 10 Mar 14:54 index.php
drwxr-xr-x 5 leehambley leehambley 170 10 Mar 16:26 modules
drwxr-xr-x 12 leehambley leehambley 408 10 Mar 14:52 system

If that’s the case (the values listed will vary considerably depending on your time/date/users/groups/system/preferences) - the only important thing is that

index.php

,

modules

,

system

and application are all present

# svn add system
# svn add modules
# svn add application
# svn add index.php
# svn commit -M “I’m adding the first fer files to svn”

Using the SVN (Subversion) Version (svn:externals)

You can also, if you are using Subversion, check it out from the repository, and benefit from bug fixes, tweaks, and cutting edge changes; this usually isn’t a good idea on a production system though; so I shan’t go into it here.
Understanding MVC

Unless you’ve been living under a rock for the last 18 months or so, it’s pretty unlikely as a web developer you haven’t heard someone throw the term MVC round, so what does it mean; what doesn’t it mean… and why do we care?

Firstly, it may help to explain what MVC really means - it stands for “Model View Controller” - which is just a way of structuring an application.

I’ve outlined a little about Models, Views and Controllers below - I’ve also just linked the wikipedia page - because it really does a better job of explaining than I can be bothered duplicating here

To quote Wikipedia, if you don’t fancy the reading - it sums up MVC as such:
Models

In essence, “models model data” to the common developer, that means a data source of some description - most commonly a database, and Kohana makes it really easy to use Database models, because of a few handy objects that you get built in, such as ORM and the DB layer; but there’s no reason a model can’t represent a flat file, or a web-service.

Controllers typically represent a table in a database
Views

Views, as far as Kohana is concerned, are (x)HTML files, that are used to draw a user interface - there’s nothing magical about them; you can include views within views - to have common headers and footers or other elements, and views, just like regular (x)HTML files can contain all the usual tags and constructs - however they also usually include some PHP tags (often using the alternative php syntax for ease-on-the-eyes)
Controllers

The controllers, as wikipedia explains - are what ties the Models and Views together - controllers and the methods contained within form the url structure of a typical MVC framework, and this is just as true in Kohana.

Controllers, typically represent one area of a system - typical controller names (I’m sure you can figure out what they do) include users, messages,products, etc.

A controller typically contains at least 4 methods, these represent CRUD allowing you to interact with your models in all the ways that make sense.

Controllers, in reality often offer many more functions, for example it’s not unusual to see a users controller with the following methods:

Class Users_Controller extends Controller
{
// Example URL might be:
// http://www.example.com/users/login
public function login()
{
// draw and process a login form
}

// users/register
// http://www.example.com/users/register
public function register()
{
// draw and process a registration form
}

// users/forgotten_password
// http://www.example.com/users/forgotten_password
public function forgotten_password()
{
// draw and process a forgotten password form
}

// users/create
// http://www.example.com/users/create
# public function create()
# {
# // In reality, this method would likely be called
# // Register - and we already have a register method
# }

// users/read
// http://www.example.com/users/read/leehambley
public function read($username)
{
// Read the user from the `data source` using the value passed in $username
}

// users/update
// http://www.example.com/users/update
public function update()
{
// This function would likely expect post variables
// to actually update a user, otherwise you’d expect
// when retrieved with GET, that it would draw the
// profile update form.
}

// users/delete
// http://www.example.com/users/delete
public function delete()
{
// Again, this method is likely to expect post
// variables - it should delete a user, and everyhing
// associated with one — or whatever your app expects!
}
}

In actuality, you’d probably rename a lot of the methods for the standard CRUD operations - read would likely become view for example, but it’s the principles that count.

I’m going to leave MVC alone for now, with a little reading of wikipedia, and looking at some Kohana examples (the modules, are ideal to look at, they’re little self contained bundles of Models, Views and Controllers (and configuration files, amongst other things))
Understanding Application / Modules / System Directories

As you probably gathered when you unpacked the downloaded archive, there are Application, System and Modules directories - I’ll start with the system directory, as it’s the most important - and the others inherit it’s arrangement and purpose - I’ll then explain how this can be wrestled to your benefit to make cleaner code.
System

The system directory is arranged into a series of folders, their names should be pretty self explanatory - so I won’t bore you with running down all the obvious ones; the exceptions here are vendor, i18n and l10n.

Vendor is intended to contain any 3rd party apps that may be bundled with Kohana, in my case that’s SwiftMailer and HTML Purifier.

l10n and i18n are shortcuts, you can read more about them on the wikipedia page for internationalisation and localisation

The rest of the folders here are the first port of call for any requests that go through - they are the basis of everything, the configuration files here are the defaults, controllers and views here are the defaults; and are available throughout the system.
Application

Application is your main place of working, you should be adding new controllers, views and models here. There are a number of tutorials online on the Kohana website that can help you look at developing in this way, and that’s great because it means you can copy a file from the system directory, into the same place in application and it will override the defaults; if you do it this way, then you can always just remove your custom file, and let Kohana default back to the originals.
Modules

Modules are a fantastic concept, it’s basically a mini application directory inside the modules directory, for example modules/ny_module. They’re loaded only if they appear in config/config.php, and are complete stand-alone mini-apps, they’re designed to be pluggable, portable little applications - there really isn’t more to say on them; just take a look at any of the standard modules. The auth module is as good an example as any, since it relates to users, it sort-of touches on the whole user idea that I’ve already tried to familiarise yourself with.
How URLS Work In Kohana

We touched briefly, earlier on the concept of URLS in Kohana, and explained that there are constructed from the controller name, and the method name in question - it is also constructed from a handful of settings from the configuration directory. I’ve tried to draw out how they’re constructed below:

http://www.example.com/index.php/auth/create.html

[ ] [ ] [ ] [ ] [ ] [ ]
| | | | | \___ config.php: $config['url_suffix']

| | | | \__________ controller method name

| | | \_______________ controller name

| | \______________________ config.php: $config['index_page']

| \___________________________________ config.php: $config['site_domain']

\________________________________________________ config.php: $config['site_protocol']

Removing index.php

You can read more on removing index.php form your URLs here on the Kohana tutorials site.
Using Your Database With Kohana
MySQL
Using The Auth Module (Requires Forge)

So further to Dlibs tutorial on hooks, I thought I would help to demonstrate the power of this with a practical example of their usage: whilst reading this entry on PHPIDS I thought that seemed like a prime candidate for an example and so by following along below you should have a nice example of integrating a third party app into Kohana using the hooks/events system!

PHPIDS

From the site..

“PHPIDS (PHP-Intrusion Detection System) is a simple to use, well structured, fast and state-of-the-art security layer for your PHP based web application. The IDS neither strips, sanitizes nor filters any malicious input, it simply recognizes when an attacker tries to break your site and reacts in exactly the way you want it to.”

So we can simply insert PHPIDS into the Kohana system and have it silently monitor requests to our app/page informing us (if we wish) when it detects any potential attacks.

Third party apps in Kohana

Kohana loves third party applications, so much so that it makes it easy for us to integrate them . .meaning we have to write even less code. Kohana provides us with an area to centrally store any such applications (referred to as vendor apps) within the system folder. This folder can be found at <system_path>/vendor and is where any vendor apps we would like to use in our projects should be placed. If you look within that folder now you will see there are allready a number of such applications used within Kohana which you may or may not be familiar with.

If after reading this tutorial you would like more information on integrating other third party apps then you should definitely take a closer look at the email helper ( system/helpers/email.php ) which is a fantastic example of creating a helper to integrate a vendor app (in this case the Swift email library).

1 - Getting PHPIDS

The first step is to get yourself a copy of PHPIDS from here (the version I am working with is 0.5). After downloading this you can then extract the file into the system/vendor directory so that your vendor dir now contains a phpids folder aswell. Within the download we get three directories (tests, docs and lib) we are onlt really interested in lib although leaving the other two there for reference/testing is no bad idea.

We now have access to our third party app!

2 - Registering our hook

As I mentioned above one part of this tutorial was to demonstrate the power or hooks, allthough as a single feature they are actually very well documented within Kohana, for more information on them see the following pages:

• Kohana hooks documentation
• Kohana events documentation
• Learn Kohana Blog on hooks/events

In essence a hook is just a normal piece of code, nothing special at all. The power comes in when we are allowed to execute this piece of code at a number of pre-determined points through the execution process of the Kohana process (see the events docs), we can therefore deploy (in this case) PHPIDS at avery early point the in the page rendering process (prior to our controllers being executed for example), in many cases this is ideal in terms of security, efficiency, speed etc.

So to register our hook simply copy the config file (system/config/hooks.php) into our application config directory (resulting in application/config/hooks.php). We can then enable hooks by changing the contents of the hooks.php (within our application config dir) to:

$config['enable'] = TRUE;

Doing this means Kohana will now scan the application/hooks directory for any files and attempt to include and execute them.

3 - Creating our hook

The final step is creating our hook and configuring PHPIDS. Whilst doing this all code will be fairly PHPIDS specific, I was able to basically follow the included examples (and the examples in the blog posts above) in order to set it up (as I found documentation on their site fairly lacking), the code below represents a simple hook which will get your system running!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

<?php defined('SYSPATH') or die('No direct script access.');

class Phpidsloader
{
   public static function load()
   {
      $path = get_include_path();
      set_include_path($path . ':' . SYSPATH .'vendor/phpids/lib');

      require_once 'IDS/Init.php';

      //Define constants for the ini file (they should be using a dynamic format!)
      define('IDS_FILTER_PATH', SYSPATH.'vendor/phpids/lib/IDS/default_filter.xml');
      define('IDS_TMP_PATH', SYSPATH.'vendor/phpids/lib/IDS/tmp');
      //this file must exist
      define('IDS_LOG_FILE', APPPATH.'logs/phpids_log.txt');
      define('IDS_CACHE_FILE', SYSPATH.'vendor/phpids/lib/IDS/tmp/default_filter.cache');	

      //Run the monitor
      $init = IDS_Init::init(SYSPATH.'vendor/phpids/lib/IDS/Config/Config.ini');
      $ids = new IDS_Monitor($_REQUEST, $init);
      $result = $ids->run();

      if (!$result->isEmpty()) {
         require_once 'IDS/Log/File.php';
         require_once 'IDS/Log/Composite.php';

	 //Log all scores
	 $compositeLog = new IDS_Log_Composite();
	 $compositeLog->addLogger(IDS_Log_File::getInstance($init));
	 $compositeLog->execute($result);
      }

      //reset the include path
      set_include_path($path);
   }
}
Event::add('system.ready', array('Phpidsloader', 'load'));
?>

The above is a simplified version of my final hook (which I will show later), but it demonstrates clearly the power or exactly what we are doing here.

The basic workflow is to set up the system in order that PHPIDS will run (so define include paths etc, define config path constants (for the PHPIDS config file)), run the application and finally return the system back to how we left it (as near as possible), so reset include paths etc . .that is all there is to it

You will need to then setup the PHPIDS config file which you will find in system/vendor/phpids/lib/IDS/Config/config.ini, I left the file as it was except for the paths in there which I ammended with the defined constants above (You can probably get away with using my config file below), another little gotcha is that in this case we will need to create the log file within application/logs (called phpids_log.txt) and make it writeable by the server as PHPIDS doesnt seem to automatically create this file

Additional Extras

So there we have an example of integrating a third party app (PHPIDS) into Kohana, the demonstration so far doesnt really do a great deal however so I went forward and added some extra logic into the hook which made use of some of the power of PHPIDS, using the attatched hook below we now

• Track users actions accross the site, measing their threat level between pages
• Enable actions to be taken at pre-defined threat levels (25 sends us a warning email, 50 kicks them off the site etc)
• Record all registered warnings in the log file
• Use the system to gather forensic evidence on the potential attack

I have included my hook, along with the PHPIDS config file so that you can see exctly how I have them set up, as normal any questions or comments please do not hesitate to ask!

Download here

Statut	Brouillon
A faire	bonjour(avec une vue (M)VC), relecture
Compatibilité	kohanaphp v2.1.2
Mots-clés	tutoriel, installation, configuration

Le tutoriel suivant vous apprendra à installer et configurer KohanaPHP, et vous permettra de réaliser l’applicatif le plus basique qui soit, l’affichage du message “bonjour tout le monde !”.

L’objectif est de vous permettre de faire fonctionner la machine, rien de plus.

Prérequis : Ce tutoriel s’adresse à des personnes ayant déjà connaissance du langage PHP (en particulier de la programmation orientée objet en PHP5). Et disposant (ou sachant installer et configurer) d’un serveur répondant aux prérequis nécessaire au bon fonctionnement du framework KohanaPHP.

---

Même si je vais faire mon possible pour être aussi clair que possible, je n’ai non plus pas l’intention de faire des vues d’écran à chaque clic de souris, donc un minimum de sens pratique et capacité d’adaptation sera indispensable le but n’est pas de faire du copier-coller, mais d’apprendre

Installer le framework

Première application avec kohana

...
/**
 * Kohana website application directory. This directory should contain your
 * application configuration, controllers, models, views, and other resources.
 *
 * This path can be absolute or relative to this file.
 */
$kohana_application = 'bonjour';

/**
 * Kohana package files. This directory should contain the core/ directory, and
 * the resources you included in your download of Kohana.
 *
 * This path can be absolute or relative to this file.
 */
$kohana_system = 'system';
...

<?php defined('SYSPATH') or die('No direct script access.');
/**
 * Domain name, with the installation directory. Default: localhost/kohana/
 */
$config['site_domain'] = 'localhost/Kohana_v2.1.2/';

/**
 * Default protocol used to access the website. Default: http
 */
$config['site_protocol'] = 'http';

/**
 * Name of the front controller for this application. Default: index.php
 *
 * This can be removed by using URL rewriting.
 */
$config['index_page'] = 'bonjour.php';

/**
 * Fake file extension that will be added to all generated URLs. Example: .html
 */
$config['url_suffix'] = '.html';

<?php defined('SYSPATH') or die('No direct script access.');

class Welcome_Controller extends Controller {

  public function index()
  {
    echo 'Bonjour tout le monde !';
  }

}

Ever heard the expression “Pull yourself up by your bootstraps” no? Well essentailly it means sort yourself out - take action to improve or change your current situation. Bootstrap files or programs are found all over the place, they help computers and programs sort themselves out when they are first activated. The index.php file in your ci_tutorial folder, is the CodeIgniter bootstrap. It is the first file to get things done. let’s have a look at it.

Index.php is quite well commented so forgive me for repeating some of what is already written in the file, the first item we arive at in the index.php file is the error reporting:

Error Reporting

error_reporting(E_ALL) - this is a native php function, any php script or program can use this function to set the level of error reporting. This exists so that you can decide what to do when an error is encountered, either display it to the screen (good during development) or try to continue silently (best for production). It’s current setting E_ALL means that all errors and notices will be reported, this should help with your debugging. Set it to 0 if you want to trun error reporting off.

[error_repoting()]

In order to ensure that errors are actually printed to the screen you can add the php ini directive ini_set(’display_errors’, ‘On’) here.

$system_folder

The system folder contains al the Kohana files so your index.php file needs to know where it is. You can leave this variable set to ’system’ becuase we haven’t altered the default layout.

$application_folder

Similarly to the system folder your index.php file needs to know where the application folder is (by default it is inside the system folder) you can leave this setting as it is.

Set server path

Kohana perfoms some php magic here to determine the full server path to your Kohana installation. It then uses this path to generate paths to important files. You do not need to edit this section.

The strpos($system_folder, ‘/’) function checks for the position of ‘/’ in the $system_folder variable that you set earlier, it retuns a value of FALSE if ‘/’ is not found.

[strpos()]

String functions are some of the most useful, and commonly used fuctions in php, they can be used to search and edit strings in all sorts of ways, check the php manual for more string functions.

Define Application Constants

A constant in php is a varaible that does not change (so it’s not variable at all) once set a constant is available all over your scripts, they can only store simple data, like a pth to file or a name, but they are ver useful when bootstrapping an application becuase they enable you to create stores of datya that you can later rely on.

Kohana sets constants that hold the file extension you are using (.php), and a number of paths that will be helpfull later.

Kohana are created using the php define() function like this: define(’MY_CONSTANT’, ’some simple data here’);Constants are always all in upper-case.

[PHP constants]

Load the front controller

At this stage the index.php file has done all it needs to spark (or perhaps ignite?) CodeIgniter into action, so it now includes the Kohana core file with this statement:

require_once BASEPATH.’codeigniter/CodeIgniter’.EXT;

require_once tells php to go and get another file, if it has not already been gotten and include in the current run of things, think of this as including one file in another. Notice that the BASEPATH constant is used to give require_once the full path to the Kohana .php file.

In a later tutorial I will walk through the CodeIgniter.php file (and others), but I think that is is probably enough for now. The next section deal with editing and creating views.

This gallery uses BD gallery backend for album management and offers a smoothgallery option additionally to the default options

Actually we will start a new one from scratch but I played a liitle with BD gallery plugin which is very interesting in order to become more familiar with FrogCMS plugin approach since we have been using since this week end only.

Here are the additions we made:

• album ($id) became album ($id, $limit)
  • $id - album category $id
  • $limit - the number of photos to be displayed

• I created a new function named album_random ($id, $limit) which selects random picture from a specific album.
• In both functions parameters can be ignored by setting them to -1. I that case photos from all albums will be taken into account.
• Finally I added smoothgallery support to the album which enable to show a slideshow of the pictures from the album you like

TODO

- Enable the selection of several album vs one or all
- Enable category tree
- Upgrade administration panel to control album tree and ajax reorganisation
- Upgrade Photo edition pannel in order to set validity from which the user will receive a message to confirm picture disabling…for example.
- Update the control panel to add more slide show control from the panel and less from the code

Requirements

• A Frog v0.9.3 working install or superior
• A MySQL connection, with or without PDO. SQLite is not supported(yet) .
• PHP 5.x.x
• Some photos to upload

Installation

Follow BD gallery instrauctions: http://frog.bebliuc.ro/articles/2008/08/18/bd-gallery.html

Usage

Activate the gallery

• Now, you have the settings all done, but there is no gallery displayed, no? So you have to create or modify a page, and place the following function in it :
  <?php gallery(); ?>That should do the trick
• If you want to show only an certain album on a page, place this function in your page’s content :
  <?php album('1',0); ?>Where 1 is the id of the album shown in the Gallery administration panel.
• album(A,B) : affiche les photos d’un album ou de l’ensemble des albums
  • A: Identifiant de l’album (0 pour afficher tous les albums)
  • B: Nombre d’images à afficher (0 limite ignorée)
• album_random (A,B) affiche de façon aléatoire photos d’un album ou de l’ensemble des albums
  • A: Identifiant de l’album (0 pour afficher tous les albums)
  • B: Nombre d’images à afficher (0 limite ignorée)

Activate the smoothgallery

• place the following function in it :<?php gallery_style(); gallery_script_start();
  smooth_album(3,0); ?>
• smooth_album(A,B)
  • A: Identifiant de l’album (0 pour afficher tous les albums)
  • B: Nombre d’images à afficher (0 limite ignorée)

WARNING

1. This release does not intend to replace the “official” gallery plugin and was build for a personal project.
2. This version cannot be installed on top of the above since 98% of the code and reference are similar
3. This release is for
   1. Fresh installation of the gallery (or reinstallation after removal)
   2. Upgrade of the gallery by using the enable_upgrade.php script or executing manually the instruction it contains

Demo

http://www.sensfield-design.com/cms-sample00/?external0.html

Thanks to

http://smoothgallery.jondesign.net/download/

Download

Version beta