Kohana Framework Tutorial

New challenge

2011-08-04T22:01:00.000-07:00

Ok, I'm done with making the Hacker News clone.

If there is any interest, I could make a scif clone in Kohana (SCIF is small anonymous forum, written for Code Igniter).

If you're interested, please leave a comment here.

Lessn 3: Making it pretty

2010-10-16T08:49:00.000-07:00

In this lesson we'll add some style to the page and also make the home page look more complete.

First let's add the CSS. I'm using the CSS reset from YUI which is rather short and gets the job done.

/assets/css/style.css

body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,form,fieldset,input,textarea,p,blockquote,th,td {margin:0;padding:0;}
table {border-collapse:collapse;border-spacing:0;}
fieldset,img {border:0;}
address,caption,cite,code,dfn,em,strong,th,var {font-style:normal;font-weight:normal;}
ol,ul {list-style:none;}
caption,th {text-align:left;}
h1,h2,h3,h4,h5,h6 {font-size:100%;font-weight:normal;}
q:before,q:after {content:'';}
abbr,acronym { border:0;}
#wrapper{margin:0 10%; background-color:#f6f6ef}
#header{background-color:#fcaf3e;padding:.2em;color:#000;margin:1em 0 0}
#header a{color:#000}
#content{background-color:#f6f6ef; padding:1em}
.fr{float:right}
.ar{text-align:right}
body {color:#828282;font-family:Verdana;font-size:10pt;}
.cohead, .cohead a{color:#828282; font-size:9pt}
.comment{padding:.4em}
.comment, .comment a{color:#000; font-size:9pt}
textarea {color:#000000;font-family:Courier;font-size:10pt;}
#cform{padding:1em 0}
table td{padding:.1em}
.vote a{color:#828282; text-decoration:none}
.title span{font-size:8pt}
.nbody{padding:1em 0}

Looks like the views loaded from views doesn't share the variables. That's why for now I'll define the $site_title as global variable in defaulttemplate.php

classes/controller/defaulttemplate.php

public function after() {
    /*
     * Set the page title to $site_title if title is not set,
     * otherwise create title 'path'
     */
    if ($this->template->title){
      $this->template->title = $this->template->title.' » '.$this->site_title;
    } else {
      $this->template->title = $this->site_title;
    }
    View::bind_global('site_title', $this->site_title);
    parent::after();
  }

The header_tpl.php file becomes:

views/blocks/header_tpl.php

<div id="header">
<?php
echo '<b>'.html::anchor('/', $site_title).'</b> | ';
echo html::anchor('submit', __('submit')).' | ';
echo html::anchor('latest', __('latest'));
echo '<span class="fr">';
echo html::anchor('#', 'user');
echo '</span>';
?>
</div>

To make the links work without index.php, change the bootstrap.php file (add empty index_file element):

Kohana::init(array(
    'base_url'   => '/',
    'index_file'   => '',
));

Now the result should look like that:

Let's also change the look and functionality of the news:

views/pages/news/index_tpl

<?php
if ($news) {
  foreach ($news as $row) {
    echo '<table>';
    echo '<tr>';
    echo '<td class="vote">'.html::anchor('#', '&#9652;').'</td>';
    echo '<td class="title">';
    echo html::anchor('news/'.$row['id'], html::entities($row['title']));
    echo '</td>';
    echo '</tr>';
    echo '<tr>';
    echo '<td></td>';
    echo '<td class="cohead">';
    echo $row['points'].' by '.html::anchor('user/'.$row['user_id'], html::entities($row['user_name'])).' '.date('m.d.Y H.y', $row['created']).' | '.html::anchor('news/'.$row['id'], $row['comments'].__(' comments'));
    echo '</td>';
    echo '</tr>';
    echo '</table>';
  }
}
?>

And the result is:

Don't forget that the code for this project can be downloaded from: http://code.google.com/p/kohana-tutorial/

Lesson 2 - Database and Models

2010-10-16T04:01:00.000-07:00

In the previous lesson we created a bunch of files just to show a simple message in the browser. It may seem stupid but all these files will save us a lot of work.

Now it's time to talk database.

Our application will store the news, comments and user data in the database server, and in my case MySQL server. I created an database for the project called 'khn' and an user with access to the database.

Our first table will contain the news:

CREATE TABLE IF NOT EXISTS `news` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `user_id` int(11) NOT NULL,
  `user_name` varchar(100) NOT NULL,
  `title` varchar(255) NOT NULL,
  `body` text NOT NULL,
  `comments` int(11) NOT NULL DEFAULT '0',
  `points` int(11) NOT NULL DEFAULT '1',
  `created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 AUTO_INCREMENT=3 ;

INSERT INTO `news` (`id`, `user_id`, `user_name`, `title`, `body`, `comments`, `points`, `created`) VALUES
(1, 1, 'test 1', 'Test News 1', 'Test Body 1', 0, 1, '2010-10-16 13:45:49'),
(2, 2, 'test 2', 'Test News 2', 'Test Body 2', 0, 2, '2010-10-16 13:45:49');

One table is enough for this lesson. To let Kohana know that we want to connect to a database, we must enable the database module. Open the bootstrap.php file (located in the application directory) and uncomment the following line:

'database'   => MODPATH.'database',   // Database access

Next copy the khn/modules/database/config/database.php file to the application/config/ directory and edit its content according to your configuration. Mine looks like that:

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

return array
(
 'default' => array
 (
  'type'       => 'mysql',
  'connection' => array(
   /**
    * The following options are available for MySQL:
    *
    * string   hostname     server hostname, or socket
    * string   database     database name
    * string   username     database username
    * string   password     database password
    * boolean  persistent   use persistent connections?
    *
    * Ports and sockets may be appended to the hostname.
    */
   'hostname'   => 'localhost',
   'database'   => 'khn',
   'username'   => 'adsms',
   'password'   => 'adsms',
   'persistent' => FALSE,
  ),
  'table_prefix' => '',
  'charset'      => 'utf8',
  'caching'      => FALSE,
  'profiling'    => TRUE,
 )
);

We'll create a model called Model_News, which will handle the news:

application/classes/model/news.php

<?php
/**
 * Description of news
 *
 * @author aquilax
 */
class Model_News extends Model{

}
?>

Let's also add a method to get all the news for the home page:

/*
   * Load the news for the first page
   */
  public function loadFirstPageNews($n){
    return DB::select('id', 'title', 'user_id', 'user_name', 'comments', 'points', new Database_Expression('UNIX_TIMESTAMP(created) AS created'))
      ->from('news')
      ->order_by(new DatabaseExpression('(points - 1) / ((UNIX_TIMESTAMP(CURRENT_TIMESTAMP)-UNIX_TIMESTAMP(created))/3600 +2)^1.5'), 'DESC')
      ->order_by('created')
      ->limit($n)
      ->execute()
      ->as_array();
  }

The order_by section is taken from this Hacker News comment.

The DatabaseExpression class is used in the order_by function to prevent Kohana from escaping the expression, which breaks the resulting SQL.

I'm using the Query_Builder functions because I feel more comfortable with them. You can try to use the ORM class or raw SQL, which in this case shoult look like that:

SELECT id, title, user_id, user_name, comments, points, UNIX_TIMESTAMP(created)
FROM news
ORDER BY (points - 1) / ((UNIX_TIMESTAMP(CURRENT_TIMESTAMP)-UNIX_TIMESTAMP(created))*3600 +2)^1.5 DESC
LIMIT 30

Now we have a function, which returns news for the home page. Let's call it in the home controller's action_index:

application/classes/controller/news

public function action_index(){
    $this->data['news'] = $this->news->loadFirstPageNews(30);
    $this->render();
  }

and change the view to print the news:

application/views/pages/news/index_tpl.php

<?php
if ($news) {
  echo '';   foreach ($news as $row) {     echo '
'.html::entities($row['title']).'

';   }   echo '
';
}
?>

Lesson 1 - Getting started

2010-10-16T03:18:00.000-07:00

Let's get started with the site. This is roughly the structure we are looking for:

First let's configure our application. Kohana's configuration file is located in application/bootstrap.php

The file contains several sections. First are the configurations for the php environment. Set them according to your server configuration. I'll leave the rest untouched for now and will change only the default controller to news as this will be my default controller for this application.

Now the section looks like that:

/**
 * Set the routes. Each route must have a minimum of a name, a URI and a set of
 * defaults for the URI.
 */
Route::set('default', '((/(/)))')
 ->defaults(array(
  'controller' => 'news',
  'action'     => 'index',
 ));

Next I'll enable the .htaccess file. Kohana comes with default .htaccess which is located in the root directory of the framewark and is called example.htaccess

First let's create default controller, which will handle all the template rendering for us:

application/classes/controller/defaulttemplate.php

<?php
defined('SYSPATH') or die('No direct script access.');
/**
 * Description of defaulttemplate
 *
 * @author aquilax
 */
class Controller_DefaultTemplate extends Controller_Template {

  //The webpage title
  private $site_title = 'Kohana Hacker News';
  
  //The default template
  public $template = 'templates/default_tpl';

  //This variable will hold the data passed to the views
  public $data = array();

  public function before() {
    parent::before();

    if($this->auto_render) {
      $this->template->title            = '';
      $this->template->meta_keywords    = '';
      $this->template->meta_description = '';
      $this->template->meta_copywrite   = '';
      $this->template->content          = '';
    }
  }

  public function after() {
    /*
     * Set the page title to $site_title if title is not set,
     * otherwise create title 'path'
     */
    if ($this->template->title){
      $this->template->title = $this->template->title.' » '.$this->site_title;
    } else {
      $this->template->title = $this->site_title;
    }
    parent::after();
  }

  public function render($template = FALSE, $view = FALSE){
    /*
     * Force specific template
     */
    if ($template){
      $this->template = $template;
    }
    /*
     * Use default view logic if $view is not forced
     */
    if (!$view){
      $view = 'pages/'.$this->request->controller.'/'.$this->request->action.'_tpl';
    }
    $this->template->content = View::factory($view, $this->data);
  }
}
?>

Also the news controller:

application/classes/controller/news.php

<?php
/**
 * Description of news
 *
 * @author aquilax
 */
class Controller_News extends Controller_DefaultTemplate{

  public function  __construct($request) {
    parent::__construct($request);
  }

  public function action_index(){
    $this->render();
  }
}
?>

What remains is to create our views structure. Create the following directories in application/views:

application/views/blocks - will contain the partial elements and reusable blocks
application/views/pages - will contain the page views
application/views/templates - - will contain the page templates

We may create perfectly usable webpage without such complex view structure, but this will make our web application easily maintainable.

Now let's populate the directories:
This will be our default template:
application/views/templates/default_tpl.php

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title><?php echo $title ?></title>
  <meta name="description" content="<?php echo $meta_description ?>" />
  <meta name="KEYWORDS" content="<?php echo $meta_keywords ?>" />
  <link rel="stylesheet" href="/assets/css/style.css" type="text/css" />
</head>
<body>
  <div id="wrapper">
    <div id="header">
<?php echo View::factory('blocks/header_tpl')->render(); ?>
    </div>
    <div id="main">
<?php echo $content ?>
    </div>
    <div id="footer">
<?php echo View::factory('blocks/footer_tpl')->render(); ?>
    </div>
  </div>
</body>
</html>

It uses two block: views/blocks/header_tpl.php and views/blocks/footer_tpl.php which we will leave empty for now but make sure the files are created.

Now let's create the folder vews/pages/news/. Every controller with view will have it's own subdirectory in pages and the default view name for the corresponding action will be called [action_name]_tpl.php

In this case we want to create a view for the News controller's action index. The file will be:
views/pages/news/index_tpl.php

<?php
  echo 'First page content goes here';
?>

Now open http://knh.localhost/ and if everything is fine, should be able to see the "First page content goes here" message.

That was rather long and boring lesson but let's hope it will pay off.

The source code for this project can be found at: http://code.google.com/p/kohana-tutorial/

pre-Lesson 2: What is MVC?

2010-10-14T21:16:00.000-07:00

Kohana is MVC framework. In this lesson, we will see what exactly the MVC letters mean and how to they fit in our application.

MVC stands for Model View Controller. The Model-View-Controller concept is often used in in web development. It provides a convinient way to separate logic and interface.

The Controller is the gateway to the application. Depending on the user input (url of the page or submitted data), the controler decides what operation should be performed and what output should be generated.

The Model is the place where data is processed. It is the workforce of the application and gets the things done.

The View is the presentation layer. It handles the output, which will be send back to the browser.

So the tipical workflow of an MVC application is:

User opens page -> the request hits the controller -> the controller decides what action should be performed -> the controller calls the model if necessary (loads data or performs action) -> the controller loads the view -> the view generates the page and sends it back to the browser

There are some basic rules of thumb when dealing with MVC:

Keep your controllers on a diet. The controller gets hit on every request so it should be able to be as light as possible.
Load the model only if you'll interact with it. This will keep the memory usage low.
Don't use the model directly from the view. All the data the view needs should come from the controller.

pre-Lesson: Setting up the development box and installing kohana

2010-10-14T10:39:00.000-07:00

I'll use Ubuntu Desktop for development and the first thing I do when starting a new project is to setup local subdomain for the project.

First let's download the framework and create new directory for the project:

cd /tmp
wget http://kohanaframework.org/download/kohana-latest
unzip kohana-3.0.8.zip
sudo mv kohana /var/www/

The next step is to create the virtual host for the project:

sudo vim /etc/apache2/sites-available/kohana

And paste the following text:

NameVirtualHost khn.localhost

 ServerName khn.localhost
 DocumentRoot /var/www/kohana

Save the file and create symbolic link to it in /etc/apache2/sites-enabled :

sudo ln -s /etc/apache2/sites-enabled/kohana /etc/apache2/sites-enabled/001-kohana

And add the subdomain to the /etc/hosts file

127.0.0.1       khn.localhost

Next reload apache:

sudo /etc/init.d/apache2 reload

Now open your browser and go to http://khn.localhost. You should be able to see the Environment Tests page.

Oops two red lines for errors. Fortunately they are easy to solve. I just have to make the cache and logs directories writable to the web server:

sudo chmod a+w /var/www/kohana/application/logs/
sudo chmod a+w /var/www/kohana/application/cache/

Refresh the page again and we get nice green message saying:

✔ Your environment passed all requirements.
Remove or rename the install.php file now.

Lets delete it and refresh again.

sudo rm /var/www/kohana/install.php

If everything is OK, you should get nice thee welcome mesage:

hello, world!

Ok that was was all for pre-lesson.

Getting to know Kohana

2010-10-14T09:57:00.000-07:00

I've been using CodeIgniter for several years. It's a great framework, which gets the things done quickly without forcing you to change yor programming style.

These days I decided to give Kohana a try. It's a forked version of CodeIgniter so there should be some similarities.

The project, that I'll try to create is a simple Hacker News clone. I'll be using the latest stable downloadable version of Kohana v3.0.8 "großen jäger".

I've never used Kohana before. This tutorial is my way of learning it. If you notice something wrong or something that can be done better, just write a comment and I'll try to fix it.
Also I'll borrow some parts of the code from another excelent Kohana 3 tutorial (http://www.dealtaker.com/blog/2009/11/20/kohana-php-3-0-ko3-tutorial-part-1/)

N.B. English is not my native language. But I'll try to write correctly.