Introdução

Temma em 3 minutos

Temma é um Model-View-Controller (MVC, em português Modelo-Visão-Controlador), criado para facilitar e acelerar o desenvolvimento de sites.

O framework cuida das requisições recebidas, evitando que você tenha que desenvolver repetidamente as camadas mais básicas das suas aplicações, deixando você livre para se concentrar no "código de negócio", a parte mais importante.

1Instalação

Consulte a página de documentação de instalação para saber como instalar o Temma.

2Princípios básicos

Temma facilita o desenvolvimento de sites compostos por URLs como: 

http://www.site.com/controller/action/p1/p2/p3

As URLs são divididas em 3 partes:

  • O nome do controlador, um objeto que será instanciado ao receber a requisição.
  • O nome da ação, um método desse objeto que será chamado.
  • Um número variável de parâmetros que esse método poderá utilizar.

O seguinte código será então executado: 

Controller::action(p1, p2, p3)

Por padrão, o framework vai gerar uma página interpretando o arquivo de template templates/controller/action.tpl

Obviamente, é possível modificar os comportamentos padrão. Um controlador pode optar por ler dados recebidos via POST em vez de − ou além de − dados recebidos como parâmetro GET. Uma ação pode definir um template específico a usar, ou até mesmo definir um tipo de visão completamente diferente (que vai gerar JSON ou XML em vez de HTML, por exemplo).

3Exemplo de desenvolvimento

Para este exemplo, vamos criar um site bem simples com duas páginas. A primeira vai exibir uma lista de artigos, a segunda vai exibir o artigo solicitado.

3.1Configuração

A primeira coisa a fazer é criar o arquivo de configuração do projeto. É o arquivo etc/temma.php.

Consulte a documentação de configuração para conhecer as diferentes opções.

A instalação do Temma fornece arquivos de exemplo, mas aqui está o conteúdo do que vamos usar: 

<?php

return [
    'application' => [
        'dataSources' => [
            // configuração do banco de dados
            'db' => 'mysql://user:passwd@localhost/mybase'
        ],
        // configuração do controlador raiz
        'rootController' => 'Articles'
    ],
    // limiar de gravação dos logs
    'loglevels' => 'WARN',
    // variáveis de template importadas automaticamente
    'autoimport' => [
        'siteName' => 'Site de demonstração'
    ]
];
  • Linha 7: Configuração da conexão com o banco de dados.
  • Linha 10: A diretiva rootController serve para definir o controlador raiz do site, ou seja, aquele que vai responder quando acessarmos o endereço http://www.monsite.com/.
  • Linha 13: Definimos o nível mínimo de erro que será registrado no arquivo log/temma.log.
  • Linha 16: Definimos uma variável de template contendo o nome do site.

3.2Banco de dados

Antes de mais nada, vamos criar uma tabela no banco de dados. Você precisa executar a seguinte consulta no seu banco: 

CREATE TABLE articles (
    id     INT UNSIGNED AUTO_INCREMENT,
    title  TINYTEXT,
    text   MEDIUMTEXT,
    author TINYTEXT,
    PRIMARY KEY (id)
);

E podemos adicionar dados a ela:

INSERT INTO articles (title, text, author)
VALUES ('Primeiro artigo', 'Texto do primeiro artigo', 'John'),
       ('Segundo artigo',  'Texto do segundo artigo',  'Bob'),
       ('Terceiro artigo', 'Texto do terceiro artigo', 'John');

3.3Controlador

Vamos escrever nosso primeiro controlador. Um controlador é um objeto que recebe conexões e as gerencia para enviar dados de volta.
Controladores têm ações, e cada ação pode receber parâmetros.

Nosso controlador vai se chamar Articles. Ele vai conter dois métodos principais:

  • list(), para exibir a lista de artigos.
  • show(), para exibir um único artigo.

A ele será adicionado o método __invoke(), cujo único papel é receber conexões na raiz do site e redirecioná-las para a lista de artigos.

No diretório controllers/ do seu projeto, crie um arquivo chamado Articles.php. 

<?php

/** Controlador de gerenciamento de artigos. */
class Articles extends \Temma\Web\Controller {
    /** Informa ao framework que ele deve criar automaticamente a DAO. */
    protected $_temmaAutoDao = true;

    /** Ação raiz (nenhuma ação explícita). */
    public function __invoke() {
        // redirecionamento para a lista de artigos
        $this->_redirect('/article/list');
    }

    /** Ação que exibe a lista de artigos. */
    public function list() {
        // recuperação da lista de itens no banco de dados
        $articles = $this->_dao->search();

        // a lista é disponibilizada para o template
        $this['articles'] = $articles;
    }

    /**
     * Ação que exibe o conteúdo completo de um artigo.
     * @param  int  $id  Identificador do artigo.
     */
    public function show(int $id) {
        // recuperação do conteúdo do artigo no banco de dados
        $article = $this->_dao->get($id);

        // verificamos se o item solicitado existe ou não
        if (!$article) {
            // ele não existe, redireciona para a lista
            $this->_redirect('/article/list');
        } else {
            // ele existe, os dados são enviados para o template
            $this['article'] = $article;
        }
    }
}
  • Linha 4: Controladores devem herdar do objeto \Temma\Web\Controller.
  • Linha 6: O controlador contém um atributo protegido chamado _temmaAutoDao, que informa ao Temma que ele deve criar automaticamente uma DAO (Data Access Object), que será usada para ler ou gravar no banco de dados. Esse objeto é configurado automaticamente para acessar a tabela articles (com base no nome do controlador).
    Por enquanto, basta saber que esse objeto oferece um método search() que retorna a lista de todos os registros da tabela articles, e um método get() que retorna um elemento a partir do seu identificador.
  • Linha 9: A ação raiz é executada quando nenhuma ação é solicitada especificamente. Como esse controlador foi definido como o controlador raiz (rootController no arquivo etc/temma.php), esta é, portanto, a ação que será chamada ao acessar a raiz do site.
    • Esta ação responde às duas URLs seguintes:
      http://www.my-site.com/
      http://www.my-site.com/articles
    • Linha 11: O internauta é redirecionado para a página que exibe a lista de artigos.
  • Linha 15: A ação list, que exibe a lista de itens.
    • Esta ação responde à URL: http://www.my-site.com/articles/list
    • Linha 17: O objeto DAO é usado para recuperar os dados de todos os itens.
    • Linha 20: Copiamos o valor da variável $articles para a variável de template articles. O template usado será (implicitamente) o arquivo templates/article/list.tpl.
  • Linha 27: A ação show, que exibe o conteúdo de um artigo cujo identificador é fornecido como parâmetro na URL.
    • Esta ação responde à URL: http://www.my-site.com/articles/show/2
    • Linha 29: O objeto DAO é usado para recuperar os dados do item a partir do seu identificador.
    • Linha 31: Se o artigo não existir, redirecionamos para a lista de artigos.
    • Linha 34: Se o artigo existir, salvamos como uma variável de template. O template usado será (implicitamente) o arquivo templates/article/show.tpl.

3.4Templates

Temma usa o motor de templates Smarty, que é muito popular e tem uma sintaxe muito fácil de entender.

Para a página que exibe a lista de artigos, vamos criar o arquivo templates/article/list.tpl: 

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    <ul>
        {* loop pela lista de artigos *}
        {foreach $articles as $article}

            {* adiciona um link para o artigo *}
            <li>
                <a href="/articles/show/{$article.id}">
                    {$article.title}
                </a>
            </li>

        {/foreach}
    </ul>
</body>
</html>
  • Linha 3: O nome do site é colocado na tag <title>. Ele é escapado, para converter eventuais caracteres especiais em entidades HTML.
  • Linha 8: Loop pelos itens da lista de artigos.
  • Linhas 11 a 15: Criação do link para a página de um artigo. O título do artigo é escapado automaticamente, para converter caracteres especiais em entidades HTML.

Para a página que exibe um artigo, vamos criar o arquivo templates/article/show.tpl: 

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    {* exibe o título do artigo *}
    <h1>{$article.title}</h1>

    {* exibe o autor do artigo *}
    <h2>por {$article.author}</h2>

    <p>
        {* exibe o conteúdo do artigo *}
        {$article.text|raw}
    </p>
</body>
</html>
  • Linha 3: O nome do site é colocado na tag <title>, e seus caracteres especiais são escapados automaticamente.
  • Linha 7: O título do artigo é colocado em uma tag H1, e seus caracteres especiais são escapados automaticamente.
  • Linha 10: O nome do autor é colocado em uma tag H2, e seus caracteres especiais são escapados automaticamente.
  • Linha 14: O texto do artigo é colocado em um parágrafo (tag P), e solicitamos explicitamente que seu conteúdo não seja escapado (já é HTML).

4Para saber mais

Documentação completa do Temma