Как написать простейший модуль для Kohana 3?

В процессе разбирания основ работы с PHP-фреймворком Kohana, третьей версии, столкнулся с тем, что далеко не сразу сообразил, как написать модуль для этого фреймворка. Не всё показалось интуитивно понятным, в силу не слишком большого опыта работы с фреймворками.
Исследование имеющихся в дефолтной установке модулей делу помогло, но не сильно, всё равно пришлось использовать метод научного тыка.

Поэтому, решил написать заметки о создании модуля. Вдруг кому-нибудь пригодится.



Итак, приступим.

Базовая структура директорий любого модуля для Ko3 выглядит примерно так:

module_name
|
|--classes
|
|--config
|
 --views

Логично, что в директории classes будут лежать классы, необходимые для работы модуля. В директории config — соответственно файл с конфигурацией модуля. Ну а в директории views — шаблоны отображения.

Для примера напишем какой-нибудь простой модуль. Пусть он не будет нести большой практической пользы, но нам главное — понять принцип работы.

Напишем модуль вывода заголовков. В качестве данных будем передавать строку, а на выходе ожидаем её оформленной в некотором виде.

Создаем в директории modules каталог tester, это будет имя нашего модуля. В нём создадим директории classes, config, views.

Пусть наш модуль в конфигурации хранит:
-размер шрифта, которым будет выводится заголовок;
-цвет заголовка;

создадим в директории config файл tester.php (взяв пример с дефолтными модулями в Ko3, названия файлов сделаем таким же, как и название модуля), со следующим содержимым:

<?php

return array(

    'default' => array(
        'size'    => '20',
        'color'    => '#ff0000',
        'view'    => 'tester/view.php',
    ),

);



В элементе view указываем шаблон вывода наших заголовков. И само собой, нам нужно создать этот шаблон в каталоге views нашего модуля. Это будет выглядеть примерно так:

|--views
   |
    --tester
      |
       --view.php

Содержимое шаблона будет простым:

<div style="clear: both; font-weight: bold;">
    <font style="color: <?php echo $fontColor ?>; font-size: <?php echo $fontSize ?>pt;"> <?php echo $text ?> </font>
</div>


А теперь переходим собственно к написанию нашего класса, который и будет все это создавать. В каталоге classes создаем файл tester.php (да, точно с таким же именем) со следующим содержимым:

<?php 

class Tester
{
    // font size of our header
    protected $fontSize;
    
    // color of our header
    protected $fontColor;
    
    // text of our header
    protected $text;
    
    // merged configuration settings
    protected $config = array();
    
    
    
    public static function factory($text)
    {
        return new Tester($text);
    }

    
    public function __construct($text)
    {
        // Load config file
        $config_file  = Kohana::config('tester');
        $this->config = $config_file->default;
        
        $this->fontColor = $this->config['fontColor'];
        $this->fontSize  = $this->config['fontSize'];
        $this->text      = $text;
    }
    
    
    public function render()
    {
        // Load the view file and pass on the whole Pagination object
        return View::factory($this->config['view'], get_object_vars($this))->render();
    }

}




Обратите внимание на конструктор, в нем происходит загрузка файла конфигурации, и задание свойств обьекта, которые понадобятся нам для вывода заголовка.
Обрабатывать наши заголовки мы будем прямо в шаблонах, следующим образом:

<?php echo Tester::factory('New Module Header')->render(); ?>



Теперь нужно подключить наш модуль в файле bootstrap.php
Открываем, находим следующую секцию:

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



и добавляем в этот список строку с нашим модулем:

Kohana::modules(array(
    // 'auth'       => MODPATH.'auth',       // Basic authentication
    // 'codebench'  => MODPATH.'codebench',  // Benchmarking tool
    // 'database'   => MODPATH.'database',   // Database access
    // 'image'      => MODPATH.'image',      // Image manipulation
    // 'orm'        => MODPATH.'orm',        // Object Relationship Mapping
    // 'pagination' => MODPATH.'pagination', // Paging of results
    // 'userguide'      => MODPATH.'userguide',  // User guide and API documentation
    'tester' => MODPATH.'tester',
    ));



Итоговая структура директорий модуля:

tester
|
|--classes
|   |
|    --tester.php // класс нашего модуля
|
|--config
|   |
|    --tester.php // файл конфигурации
|
 --views
    |
     --tester
        |
         --view.php // шаблон отображения

Вот и всё, после того, как мы прописали наш модуль в bootstrap.php мы можем использовать новые заголовки в шаблонах.

Естесственно, данный функционал во-первых, очень ограничен, а во-вторых — проще и логичнее было бы написать метод в классе-хелпере HTML. Но, тем не менее, принцип организации модулей, я думаю понятен.

Если нужен будет модуль, который мог бы выступать в качестве контроллера для строки запроса (например, будет выдавать результат при запросе site/module/method/param1/param2) то потребуется во-первых создать в директории classes поддиректорию controller, и в ней создать файл с классом нашего контроллера. Во-вторых, нужно будет не только подключить модуль в файле bootstrap.php, но и также надо будет указать маршрут (route) в секции маршрутов, для обработки URL, указывающего на наш модуль.