Primeiramente, baixe e instale o Subversion.

Caso você utilize Ubuntu/Linux, Debian, ou alguma distribuição parecida, você pode instalar através do terminal, usando o comando:

sudo apt-get install subversion

Caso você utilize outra distribuição, ou Windows, mais informações para download estão disponíveis em http://subversion.tigris.org/getting.html#binary-packages

Após a instalação

Após instalar o Subversion, caso esteja no Linux, abra o terminal.

Caso esteja no Windows, vá em Iniciar > Executar, digite “cmd” e execute.

Crie uma pasta, no lugar que desejar. Aqui eu optei por ~/kohana.

Esta é a pasta onde você baixará os arquivos do site do Kohana, para fazer isso, vá até a pasta e execute o comando abaixo:

svn co http://source.kohanaphp.com/branches/website/application kohana-website

Esse comando baixará somente a pasta application, pois fora dela, não há conteúdo a ser traduzido.

Após o término, você terá os arquivos em sua máquina.

Realizando o primeiro Patch

O Patch, ou Correção, nada mais é que a diferença entre o arquivo antigo e o novo (modificado).

Portanto, você irá modificar o arquivo em questão, e realizar o patch através do SVN mesmo. Ele possui uma ferramenta que faz isso.

Para montar esse Mini How To, eu realizarei um patch, no arquivo: i18n/pt_BR/layout.php

Realizei algumas alterações no arquivo, comparando com a versão atual em inglês i18n/en_US/layout.php, adicionei duas traduções que faltavam: menu_redmine e menu_projects.

Após isso, é bastante simples. Somente fui até a pasta, através do terminal e gerei o patch, com o comando:

svn diff i18n/pt_BR/layout.php > patch_i18n_pt_BR_layout.patch

Eu acho importante manter uma padronização no nome dos patches.

Finalizando, envio do Patch

Foi criado um Ticket no site do Kohana, onde devem ser adicionados os patches, para isso basta se cadastrar no site, ir até o Ticket e enviar o arquivo.

O Ticket criado para isso, foi o #1799.

Espero que esse documento seja de bastante utilidade, e que todos consigam compreender bem.

PHP

O que são Hooks?

Hooks são arquivos que são carregados na inicialização do Kohana, permitindo você adicionar ou modificar funções, chamadas callbacks, que são disparadas pelo Kohana.

Essas funções (ou callbacks) são colocados em uma lista dentro do seu evento específico, chamada Event Queue.

O que são Eventos?

Durante a inicialização, e até mesmo durante a execução, em alguns casos, o núcleo do Kohana dispara vários eventos. Eventos que são definidos pelo próprio núcleo.

Você pode ver a lista completa de eventos disparados pelo Kohana, na documentação: http://docs.kohanaphp.com/general/events

Habilitando os Hooks no Kohana

Para começar a brincar com os Hooks, é necessário habilitá-los. Para isso, basta configurar a opção enable_hooks no config/config.php, para TRUE:

$config['enable_hooks'] = TRUE;

Exemplo de utilização de Hooks

Suponha que tenhamos um site com sistema de autenticação.

Quando um visitante chega, ele é logo direcionado ao controller padrão, definido em config/routes.php, pela seguinte linha:

$config['_default'] = 'site';

O controller site, contém os métodos (páginas): Home (com formulário de autenticação), Quem Somos, Ajuda…

Agora, o que fazer quando este visitante já estava autenticado anteriormente, e retorna ao site?

A solução mais simples a se fazer, é criar uma verificação no controller site, e caso o usuário já esteja autenticado ele será redirecionado à outro controller, chamado painel.

Problema

A cada redirecionamento do controller site ao controller painel, seria realizado outra inicialização do sistema completo.

Solução

Uma solução elegante e correta para isso, é utilizar um Hook para informar ao Router, o controller correto a ser chamado.

O Router é quem define através da URL, qual controller deverá ser chamado, portanto a única coisa que terá de ser feita, é dizer à ele qual controller ele deverá chamar.

Criamos então, o arquivo hooks/site.php, o nome não importa, a não ser por fácil identificação posteriormente.

No arquivo, é especificado que no momento do evento system.routing, uma função (leia-se callback) será chamada, antes do Router::setup.

Esse callback definirá o controller correto à ser carregado.

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

function hook_define_controller_padrao()
{
	if (!empty(Router::$current_uri)) return;
	if (Session::instance()->get('user'))
		// usuário logado
		Router::$current_uri = 'painel';
}

Você pode também impossibilitar o acesso à página de autenticação, quando o usuário já estiver autenticado, modificação a função callback acima, da seguinte forma:

function hook_define_controller_padrao()
{
	$logado = Session::instance()->get('user');
	if (empty(Router::$current_uri) && $logado)
		// usuário autenticado
		Router::$current_uri = 'painel';
	elseif (Router::$current_uri == 'site/login' && $logado)
		// exibir "página não encontrada"
		Event::run('system.404');
}

Criada a função, é necessário que seja adicionada à lista de eventos a serem realizados, isso pode ser feito logo abaixo da função, ou no final do arquivo Hook.

Event::add_before(
	'system.routing',
	array('Router', 'setup'),
	'hook_define_controller_padrao'
);

Existe também como definir novos eventos, mas isso fica para outro artigo, pois este é somente uma introdução sobre o assunto.

Utilize os Hooks sempre que possível, eles poderão reduzir inúmeras linhas no seu código, tornando-o mais enxuto, legível e organizado.

Serve também para aqueles que estão começando a se familiarizar com o framework e querem aprender um pouco mais sobre as possibilidades que ele oferece.

Singleton

Singleton é um padrão (Design Pattern) que garante que suas classes serão instânciadas somente uma vez, podendo ser acessadas de forma global, evitando a criação de várias instâncias desnecessarias da mesma.

No KohanaPHP isso pode ser aplicado nas bibliotecas, pois todas as bibliotecas tem suporte a Singleton.

Ao invés de criar uma nova instância:

$this->session = new Session;

Você utiliza o método estático instance:

$this->session = Session::instance();

O que o método instance cria uma nova instância, armazena-a em uma variável, e a retorna. Na próxima chamada é feita uma verificação, caso uma variável com a instância já exista, ao invés de criar uma nova, ele retorna a instância contida na variável.

Utilize o Query Builder

Muita gente odeia Query Builders por serem um tanto limitados, porém se você quiser que a sua aplicação seja independente de banco de dados, use-o. Deixe para escrever SQL’s somente quando for realmente necessários.

O Query Builder suporta method chaining, o que pode deixar o código mais elegante.

Exemplos de Method Chaining com Query Builder

$result = $this->db->select('id, nome')
                   ->from('tabela')
                   ->where(array('categoria' => 1))
                   ->limit(10)
                   ->get();

$result = $this->db->select('id')
                   ->getwhere('tabela', array('categoria' => 2));

Contando total de registros em uma tabela

$total_usuarios = $this->db->count_records('usuarios');

Utilize segmentos, de preferência nomeados

Ao invés de usar variáveis $_GET, dê preferência aos segmentos. Além de mais elegantes, são mais fáceis de serem manipulados.

http://meusite/clientes/busca/cidade/Bauru/estado/SP

Onde clientes é o controller, busca é o método, e cidade e estado são segmentos.

$cidade = uri::segment('cidade');

$estado = uri::segment('estado');

Nunca modifique os arquivos do diretório system

Os recursos disponíveis pelo Kohana, são carregados no formato de cascata, ou seja, primeiro ele verifica se o arquivo existe no diretório application, caso não exista, então procura nos diretórios de cada módulo, em seguida no diretório system.

Um bom exemplo são os arquivos de configuração, localizados no diretório system/config/.

O caminho percorrido até ele chegar em qualquer arquivo dentro deste diretório, é o seguinte:

application/config/auth.php
--> modules/archive/config/auth.php
--> modules/flot/config/auth.php
--> modules/auth/config/auth.php (encontrado)

Caso não fosse encontrado, ele continuaria a pesquisar, terminando no diretório system:

system/config/auth.php

Por isso é muito importante transferir todos os arquivos necessários para o diretório application, e nunca modifica-los nos seus diretórios de origem.

Use os helpers e bibliotecas disponíveis

O Kohana disponibiliza uma série de helpers e bibliotecas que podem facilitar e muito o desenvolvimento. Não invente a roda à todo momento.

Exemplo de utilização do helper Upload

$filename = $_FILES['arquivo']['name'];
$tmp_name = $_FILES['arquivo']['tmp_name'];

$filename_path = upload::save(array
(
	'name' => $filename,
	'tmp_name' => $tmp_name
), $filename);

$filename = basename($filename_path);

Exemplo de utilização da biblioteca Pagination

$this->pagination = new Pagination(array
(
	'base_url'       => 'noticias/page/',
	'uri_segment'    => 'page',
	'total_items'    => $total_num_rows,
	'items_per_page' => $rows,
	'style'          => 'digg'
));

echo $this->pagination;

No exemplo acima, será impressa uma paginação no estilo Digg.

Existem outros estilos de paginação que podem ser conferidos através da documentação:

http://docs.kohanaphp.com/libraries/pagination

Estenda os helpers, sempre que necessário

Uma prática muito encorajada no Kohana é a extensão dos helpers para se adequar as suas necessidades.

Por exemplo, podemos estender o helper format, para formatar também o tamanho de arquivos, criando o arquivo MY_format.php dentro do diretório helpers da sua apliação, geralmente application/helpers.

applications/helpers/MY_format.php

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

class format extends format_Core
{
	public static function filesize($size)
	{
		$sizes = array('B', 'kB', 'MB', 'GB',
		            'TB', 'PB', 'EB', 'ZB', 'YB');
		$c = count($sizes) - 1;
		for ($i = 0; $size > 1024 && $i < $c; $i++)
			$size /= 1024;
		return round($size, 2) . $sizes[$i];
	}
}

echo format::filesize(1024*4); // 4kB

Lembre-se, todo arquivo de extensão deve ser iniciado por MY_, é um padrão definido pelo Kohana.

Internacionalização

Criar uma aplicação multi-idiomas com o Kohana é relativamente simples.

Primeiro crie o diretório i18n dentro de applications, e em seguida crie o diretório pt_BR.

applications/i18n/pt_BR/

Após isso, as strings são divididas entre arquivos, dentro desse diretório, por exemplo:

applications/i18n/pt_BR/caption.php

Dentro de cada arquivo, são especificadas as strings:

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

$lang = array
(
	'submit' => 'Enviar',
	'cancel' => 'Cancelar',
	'confirm' => 'Confirmar',
);

echo Kohana::lang('caption.submit'); // Enviar

Também é permitido a utilização de Arrays:

'confirm' => array
(
	'edit?' => 'Editar texto?',
	'remove?' => 'Remover texto?'
);

echo Kohana::lang('message.confirm.edit?'); // Editar texto?

Algumas dúvidas relacionadas a este material podem ser retiradas através do documentação do próprio Kohana PHP, em http://docs.kohanaphp.com/.

Começando *bem* do começo, o começo do começo..

1. Faça o download do Kohana no site http://kohanaphp.com/
2. Renomeie a pasta Kohana_vX.X.X para agenda.
3. Deixe o diretório application/logs com permissão para escrita.
4. Edite o arquivo application/config.php e altere site_domain para o respectivo caminho onde se encontra o kohana, /agenda/, caso seja http://localhost/agenda/.

E vamos lá..

Primeiro vamos “limpar” o kohana, removendo os exemplos, que nesse tutorial, não serão utilizados.

1. Apague todos arquivos que estão dentro da pasta application/controllers
2. Apague todos arquivos que estão dentro da pasta application/views

Crie um novo arquivo, application/controllers/agenda.php, que será um controller.

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

class Agenda_Controller extends Controller
{

    public function create()
    {
        /* Aqui iremos chamar a view, que esta localizada dentro
         * da pasta "views/", o .php pode ser omitido.
         */
        $view = new View('create');
        $view->render(true);
    }

}

?>

Crie agora, o arquivo application/views/create.php, que será a view chamada pelo método create dentro do controller Agenda.

<form action="<?php echo url::site('agenda/create'); ?>" method="post">
    <label for="name">Nome:</label>
        <input id="name" name="name" type="text" />
    <label for="phone">Telefone:</label>
        <input id="phone" name="phone" type="text" />
    <input type="submit" value="Salvar" />
</form>

Repare, que na view create.php, usamos o método url::site(). O método site, faz parte do helper url, que contém um conjunto de métodos úteis que ajudaram no desenvolvimento de suas aplicações, o método site retorna o caminho site_domain + controller/metodo.

Aqui já podemos chamar a url http://localhost/agenda/index.php/agenda/create

E através dessa url você já pode perceber que o formato das url’s é:

index.php/controller/método

Caso queira, você também pode usar subdiretórios dentro da pasta applications/controllers, por exemplo agenda/escola/contatos.php, onde contatos.php é um controller com nome Contatos_Controller, e pode ser acessado através da url agenda/index.php/agenda/escola/contatos. Enfim, isso não vem ao caso agora.

Voltando, vamos dar vida a nossa aplicação. Crie um banco de dados para a agenda:

CREATE DATABASE `agenda` ;

CREATE TABLE `agenda`.`contacts` (
  `id` int(11) NOT NULL auto_increment,
  `name` varchar(255) NOT NULL,
  `phone` varchar(255) NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=2 DEFAULT CHARSET=utf8

Agora, copie o arquivo system/config/database.php para application/config/database.php, na pasta system/config ficam todos arquivos de configuração padrão, como nós não vamos usar uma “base de dados padrão”, então copiamos o arquivo para a pasta da nossa aplicação.

Edite o arquivo application/config/database.php, configurando o acesso ao seu banco de dados:

‘user’ => ‘usuário’,
‘pass’ => ’senha_do_usuario’,
‘database’ => ‘agenda’

E então vamos alterar o método create no nosso controller agenda, para que adicione nossos dados ao banco de dados.

public function create()
{
    if (request::method() == 'post')
    {
        $name  = (string) @$_POST['name'];
        $phone = (string) @$_POST['phone'];

        // aqui inserimos os dados no banco
        $db = new Database;
        $db->insert('contacts', array('name' => $name, 'phone' => $phone));

        // redirecionamos para o metodo "contacts"
        url::redirect('agenda/contacts');
    }
    /* Aqui iremos chamar a view, que esta localizada dentro
     * da pasta "views/", o .php pode ser omitido.
     */
    $view = new View('create');
    $view->render(true);
}

Você já pode testar o formulário, porém ele dará erro, pois ainda não criamos o método contacts, que será criado agora:

public function contacts()
{
    /* Primeiro vamos retornar a lista de contatos do banco de dados
     * e guarda-la na variável $result
     */
    $db = new Database;
    $result = $db->get('contacts');
    /* Aqui iremos chamar a view (views/contacts.php),
     * passando a variável de nome "result".
     */
    $view = new View('contacts', array('result' => $result));
    $view->render(true);
}

E a view contacts.php ficará assim:

<table border="0">
<tbody>
<tr>
<th>ID</th>
<th>Nome</th>
<th>Telefone</th>
<th></th>
</tr>
<?php foreach ($result as $r): ?>
<tr>
<td><?php echo $r->id; ?></td>
<td><?php echo $r->name; ?></td>
<td><?php echo $r->phone; ?></td>
<td>
    <?php
        echo html::anchor('agenda/edit/' . $r->id, 'Editar');
    ?>
</td>
</tr>
<?php endforeach; ?>
</tbody></table>

Observe que foi utilizado mais um helper, html::anchor(), que basicamente cria um link <a href=”">…</a>.

Bom, agora que já temos o método create, o contacts (list) falta o edit, certo?

public function edit($id = null)
{
    $db = new Database;
    $id = (int) $id;
    $result = $db->limit(1)->getwhere('contacts', array('id' => $id));
    if (count($result) == 0)
    {
        /* Caso não exista um contato com este id
         * retorna uma página "not found" do kohana
         */
        Event::run('system.404');
    }
    /* Se chegou até aqui, é porque achou o registro
     */
    $row = $result[0];
    /* Conferimos se é um método http post,
     * se for, salvamos o registro
     */
    if (request::method() == 'post')
    {
        $name  = (string) @$_POST['name'];
        $phone = (string) @$_POST['phone'];

        // aqui inserimos os dados no banco
        $db = new Database;
        $db->update('contacts',
                    array('name' => $name, 'phone' => $phone),
                    array('id' => $row->id));

        // redirecionamos para o metodo "contacts"
        url::redirect('agenda/contacts');
    }
    /* E então, chamamos a view responsável..
     */
    $view = new View('edit', array('row' => $row));
    $view->render(true);
}

E então a view edit.php

<form action="<?php echo url::site('agenda/edit/' . $row->id); ?>"
      method="post">

<label for="name">Nome:</label>
<input id="name"
       name="name"
       type="text"
       value="<?php echo $row->name; ?>" />

<label for="phone">Telefone:</label>
<input id="phone"
       name="phone"
       type="text"
       value="<?php echo $row->phone; ?>" />

<input type="submit" value="Salvar" />

</form>

Deixe o seu comentário. ;)

Conheci o Kohana após desenvolver por um bom tempo em cima do framework, bem conhecido, Code Igniter, no qual o Kohana foi baseado.

Dizendo “por cima” (não é o foco do artigo), resolvi trocar o Code Igniter pelo Kohana, basicamente devido ao uso estrito da orientação a objetos disponibilizada no PHP 5, e também ao fato de que o Kohana é mantido pela sua própria comunidade, o contrário do Code Igniter, que todos sempre tiveram que esperar a boa vontade do pessoal da Ellislab para o lançamento de novas versões, features, etc… Enfim, isso é assunto para outra discussão, em breve.

O que quero explicar aqui, é uma coisa bem básica de se fazer no Kohana, a criação de Múltiplas Aplicações, apenas com uma instância do Kohana.

Infelizmente não tive a oportunidade de fazer o mesmo no Code Igniter, por falta de necessidade mesmo. Então *não* vou falar aqui, qual framework é mais fácil de se fazer isso, se difere (já que o Kohana é baseado no Code Igniter), etc… Se alguém souber como funciona no CI (acredito que da mesma forma do Kohana), pronuncie-se! :-)

Lembrando que isso esse é só um exemplo de como você pode utilizar o conceito de múltiplas aplicações no Kohana.

Baseando-se em uma instalação limpa do Kohana, após a extração dos arquivos, você terá uma estrutura assim:

application/
system/
index.php

Neste exemplo, vou criar duas aplicações: app_index e app_admin. Onde app_index será a aplicação principal (site) e a app_admin será a aplicação responsável pela administração do site.

Portanto, você deve fazer uma cópia do diretório application, no mesmo local, e renomear as duas pastas para: app_index e app_admin. Tendo assim a estrutura abaixo:

app_admin/
app_index/
index.php

O próximo passo é a criação do .htaccess que vai nos auxiliar nessa “arte”. Personalize o código abaixo conforme a sua necessidade.

Este .htaccess, tem a função de direcionar as URL’s para o arquivo especifico de cada uma. Ou seja:

http://127.0.0.1/dir_instalacao_kohana/admin -> admin.php
http://127.0.0.1/dir_instalacao_kohana/(qualquer outra coisa que nao seja admin/) -> index.php

Grande parte do .htaccess abaixo, foi retirado da própria documentação do Kohana.

# Turn on URL rewriting
RewriteEngine On

# Put your installation directory here:
# If your URL is www.example.com/, use /
# If your URL is www.example.com/kohana/, use /kohana/
RewriteBase /dir_instalacao_kohana/

# Do not enable rewriting for files or directories that exist
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

RewriteCond %{REQUEST_FILENAME} /dir_instalacao_kohana/admin(/|$)
RewriteRule ^admin/(.*)$ admin.php/$1 [PT,L]

RewriteRule ^(.*)$ index.php/$1 [PT,L]

Podemos perceber que a regra (RewriteRule) ^admin/(.*)$ aponta para o arquivo admin.php, o qual eu vou explicar de onde vem agora.

O arquivo admin.php, nada mais é que a cópia do arquivo index.php, porém ele precisa ser configurado para apontar para o diretório app_admin, assim como o index.php precisa ser configurado para apontar para o diretório app_index também, como abaixo.

index.php

$kohana_application = 'app_index';

admin.php

$kohana_application = 'app_admin';

Após isso, vem a parte da configuração especifica de cada aplicação. Uma dessas configurações, que com certeza você vai precisar é o routes.php, que fica por padrão localizado no system/config/routes.php.

Se você não tiver o arquivo routes.php, dentro da pasta config da sua aplicação, ele vai pegar o arquivo padrão que é o próprio system/config/routes.php. Portanto faça uma cópia do routes.php para cada uma de suas aplicações, no nosso caso, para app_index/config/routes.php e app_admin/config/routes.php.

De aqui pra frente é só com você, a estrutura esta montada, e espero que a explicação esteja simples e fácil de compreender.

Não deixe de comentar sua própria experiência.