PHPackages raelgc/template - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Templating & Views](/categories/templating) 4. / 5. raelgc/template ActiveLibrary[Templating & Views](/categories/templating) raelgc/template =============== PHP Template v2.2.8(5y ago)7533.7k↓33.9%43[1 issues](https://github.com/raelgc/template/issues)[2 PRs](https://github.com/raelgc/template/pulls)1LGPL-2.1-or-laterPHPPHP >=5.3.0CI failing Since Apr 24Pushed 5y ago24 watchersCompare [ Source](https://github.com/raelgc/template)[ Packagist](https://packagist.org/packages/raelgc/template)[ Docs](http://raelcunha.com/template/)[ RSS](/packages/raelgc-template/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (5)Dependencies (1)Versions (9)Used By (1) [![raelgc](https://camo.githubusercontent.com/f4c67031764bbae4e64f9ccf65ca073bd22fff8af3e832c0cd496a1bd01ccace/68747470733a2f2f636972636c6563692e636f6d2f67682f7261656c67632f74656d706c6174652e7376673f7374796c653d737667)](https://app.circleci.com/pipelines/github/raelgc/template) Tutorial de Templates em PHP ============================ [](#tutorial-de-templates-em-php) Uma das coisas que as pessoas mais me perguntam sobre PHP, é sobre o uso de Templates. Ou porque leram em algum livro ou fórum, ou seja porque eu comentei em aula. Através do uso de templates, deixamos toda a estrutura visual (HTML ou XML, CSS, etc) separado da lógica de programação (código PHP), o que melhora e muito tanto a construção quanto a manutenção de sistemas web. Existem vários mecanismo de template para PHP, e há um bom tempo no mercado. Mas qual indicar? Sem dúvida alguma, o Smarty é hoje o mais completo deles. Porém, o mais complexo, e de curva mais demorada. Ele é praticamente uma linguagem a parte do PHP. Com base nisso, eu resolvi colocar criar um tutorial baseado em um mecanismo de template muito mais simples. Ou seja: este não é um tutorial sobre o Smarty. É sobre Templates, mas baseado uma biblioteca que eu mesmo desenvolvi, e uso em meus projetos (mesmo nos maiores deles), na qual gastei bastante tempo desenvolvendo e melhorando, sempre com o foco principal na facilidade de uso. Mas quase todos os conceitos vistos neste tutorial se aplicam a maioria das classes de Template existentes em PHP, portanto, se você entender as idéias explicadas aqui, poderá usar seu mecanismo de Templates favorito. Para criar esta biblioteca (eu uso templates há muitos anos, quando só existia a PHPLib), eu estudei vários mecanismos de templates (PHPLib, Sigma, etc), portanto não estou "reinventando a roda", apenas "me apoiei no ombro de gigantes" para criar algo muito mais fácil de usar, que atendesse minhas necessidades e da empresa que eu trabalhava na época. De fato, atualmente muita gente usa esta biblioteca. Eu inclusive traduzi os comentários dos métodos/funções públicos para facilitar. Você verá que será preciso entender apenas duas idéias básicas: variáveis e blocos. Então, vamos lá. Changelog --------- [](#changelog) Por favor, cheque o arquivo de [CHANGELOG](CHANGELOG.md). Requisitos Necessários ---------------------- [](#requisitos-necessários) É preciso usar qualquer versão do PHP igual ou superior a `5.3`. Instalação ---------- [](#instalação) Você pode escolher instalar a biblioteca: 1. via Composer, 2. via Git, 3. ou fazer o download de um arquivo `.zip`. ### 1. Via Composer [](#1-via-composer) Para baixar a biblioteca via Composer, execute o comando: ``` composer require raelgc/template ``` 1 - Use `require_once` para incluir o autoload e a diretiva `use` para informar o [namespace](http://www.php.net/manual/pt_BR/language.namespaces.rationale.php) da classe Template, da seguinte forma: ``` ``` ### 2. Via Git [](#2-via-git) Para baixar a biblioteca via Git, execute o comando: ``` git clone https://github.com/raelgc/template.git ``` 1 - Crie uma pasta `lib` no seu projeto. 2 - Abra a pasta `template` e copie a pasta `raelgc` (e todo seu conteúdo) para dentro da pasta `lib` do seu projeto. 3 - Use `require_once` para incluir a classe Template e a diretiva `use` para informar o [namespace](http://www.php.net/manual/pt_BR/language.namespaces.rationale.php) da classe, da seguinte forma: ``` ``` ### 3. Via Download [](#3-via-download) Para baixar um arquivo `.zip` contendo a biblioteca, clique [aqui](https://github.com/raelgc/template/archive/master.zip). 1 - Descompacte o arquivo `.zip`. 2 - Crie uma pasta `lib` no seu projeto. 3 - Copie a pasta `raelgc` (e todo seu conteúdo) para dentro da pasta `lib` do seu projeto. 4 - Use `require_once` para incluir a classe Template e a diretiva `use` para informar o [namespace](http://www.php.net/manual/pt_BR/language.namespaces.rationale.php) da classe, da seguinte forma: ``` ``` Exemplo e explicação: Olá Mundo ------------------------------- [](#exemplo-e-explicação-olá-mundo) O funcionamento básico do mecanismo de templates é baseado na seguinte idéia: você tem um arquivo PHP (que usará a biblioteca), e este arquivo não conterá código HTML algum. O código HTML ficará separado, em um arquivo que conterá somente códigos HTML. Este arquivo HTML será lido pelo arquivo PHP. Aliás, tudo será processado no arquivo PHP. Dito isso, vamos ao primeiro exemplo, o já manjado Olá mundo. Vamos criar 2 arquivos: o PHP responsável por toda a lógica, e o arquivo HTML com nosso layout. Então, crie um arquivo HTML, chamado hello.html com o conteúdo abaixo: ``` Olá Mundo, com templates PHP! ``` Agora, crie o arquivo PHP, hello.php: ``` ``` Agora basta executar em seu navegador, o script hello.php, e verificar que ele irá exibir o conteúdo lido de hello.html. Se algo deu errado, consulte a seção sobre as Mensagens de Erro. Variáveis --------- [](#variáveis) Vamos agora a um conceito importante: variáveis de template. Como você pode imaginar, vamos querer alterar várias partes do arquivo HTML. Como fazer isso? Simples: no lado do HTML, você cria as chamadas variáveis de template. Veja o exemplo abaixo: ``` Olá {FULANO}, com templates PHP! ``` Repare na variável `FULANO`, entre chaves. Ela vai ter seu valor atribuído no código PHP. Variáveis só podem contêr em seu nome: letras, números e underscore (`_`). O uso de maiúsculas é apenas uma convenção, pra facilitar a identificação quando olhamos o código HTML. Mas, obrigatoriamente tem que estar entre chaves, sem nenhum espaço em branco. Então, como ficaria o código PHP que atribui valor a ela? Vamos a ele: ``` ``` Execute então novamente o script, e você verá que o código final gerado no navegador será: ``` Olá Rael, com templates PHP! ``` Variáveis de template que não tiverem um valor atribuído, serão limpas do código final gerado. Outra coisa sobre variáveis: você pode repetir as variáveis de template (ou seja, usar a mesma variável em vários lugares). Mas, óbvio, todas mostrarão o mesmo valor. Para ler o valor de uma variável, acesse do mesmo modo: ``` ``` Repare que usando as variáveis de template, você pode continuar editando o arquivo HTML em seu editor favorito: as variáveis de template serão reconhecidas como um texto qualquer, e o arquivo HTML não ficará poluído de código PHP. O contrário também é verdade: seu arquivo PHP ficará limpo de código HTML. Checando se Variáveis Existem ----------------------------- [](#checando-se-variáveis-existem) Caso você queira atribuir valor pra uma variável de template, mas não tem certeza se a variável existe, você pode usar o método exists() para fazer essa checagem. Como é de se esperar, ele retorna `true` caso a variável exista. Caso não, retorna false: ``` ``` Variáveis com Modificadores --------------------------- [](#variáveis-com-modificadores) É possível, dentro do arquivo HTML, chamarmos algumas funções do PHP, desde que elas atendam as duas condições: - A função tem que sempre retornar um valor; - A função deve ter sempre como primeiro parâmetro uma string; Vamos supor o seguinte arquivo PHP, que atribui as variáveis de template `NOME` e `VALOR`: ``` ``` E o seguinte HTML, já fazendo uso dos modificadores: ``` Exemplo - Modificadores Nome: {NOME|replace:Fulano:Rael} Valor: R$ {VALOR|str_pad:5:0:0},00 ``` Explicando: a linha `{NOME|replace:Fulano:Rael}` equivale a chamar no PHP `replace('Fulano Ciclano da Silva', 'Fulano', 'Rael')`. E essa função `replace`? É uma função declarada dentro da classe Template, que basicamente faz a mesma coisa que a função do PHP [`str_replace`](http://php.net/manual/pt_BR/function.str-replace.php) (substitui um texto por outro). A diferença é que ela recebe uma string como primeiro parâmetro. Lembre que essa é uma das condições para uma função poder ser usada dentro do HTML. Já no segundo exemplo, usamos a função interna do PHP, [`str_pad`](http://php.net/manual/pt_BR/function.str-pad.php) (já que ela já recebe como primeiro parâmetro uma string, não precisamos criar uma nova função). Neste caso, estamos usando ela para adicionar zeros à esquerda do valor, para que o valor sempre tenha 5 dígitos (e quando não tiver, que esses dígitos sejam completados com zero). Veja a [documentação desta função](http://php.net/manual/pt_BR/function.str-pad.php) para maiores esclarecimentos. Blocos ------ [](#blocos) Esse é o segundo e último conceito que você precisa saber sobre essa biblioteca de templates: os blocos. Imagine que você gostaria de listar o total de produtos cadastrados em um banco de dados. Se não houver nenhum produto, você irá exibir uma aviso de que nenhum produto foi encontrado. Vamos utilizar então, dois blocos: um que mostra a quantidade total; e outro que avisa que não existem produtos cadastrados, caso realmente o banco esteja vazio. O código HTML para isso é: ``` Quantidade de produtos cadastrados no sistema: Existem {QUANTIDADE} produtos cadastrados. Não existe nenhum produto cadastrado. ``` Repare que o início e final do bloco são identificados por um comentário HTML, com a palavra `BEGIN` (para identificar início) ou `END` (para identificar fim) e o nome do bloco em seguida. As palavras BEGIN e END sempre devem ser maiúsculas. O nome do bloco deve conter somente letras, números ou underscore. E então, no lado PHP, vamos checar se os produtos existem. Caso sim, mostraremos o bloco `BLOCK_QUANTIDADE`. Caso não, vamos exibir o bloco `BLOCK_VAZIO`. ``` ``` Como você pode reparar, blocos podem contêr variáveis de template. E blocos só são exibidos se no código PHP pedirmos isso, através do método `block()`. Caso contrário, o bloco não é exibido no conteúdo final gerado. Outro detalhe importante: ao contrário das variáveis de template, cada bloco deve ser único, ou seja, não podemos usar o mesmo nome para vários blocos. Repare que mesmo com o uso de blocos, podemos continuar editando o arquivo HTML em qualquer editor HTML: os comentários que indicam início e fim de bloco não irão interferir em nada. Agora vamos a outro exemplo usando blocos: imagine que você precisa mostrar os dados dos produtos que existem no seu cadastro. Vamos então, usando blocos, montar o HTML para isso: ``` Produtos cadastrados no sistema: NomeQuantidade {NOME} {QUANTIDADE} ``` Repare que temos apenas uma linha de tabela HTML para os dados dos produtos, dentro de um bloco. Vamos então atribuir valor a estas variáveis, e ir duplicando o conteúdo do bloco conforme listamos os produtos: ``` ``` O comportamento padrão do método `block()` é manter o conteúdo anterior do bloco, somado (ou melhor, concatenado) ao novo conteúdo que acabamos de atribuir. No exemplo acima, os dados dos produtos vieram do array `$produtos`. Caso estes dados estivessem armazenados em um banco de dados, então bastaríamos fazer como no exemplo abaixo: ``` ``` Blocos aninhados ---------------- [](#blocos-aninhados) Vamos agora então juntar os 2 exemplos de uso de blocos que vimos: queremos mostrar os dados dos produtos em um bloco, mas caso não existam produtos cadastrados, exibiremos uma mensagem com um aviso. Vamos fazer isso agora usando blocos aninhados, ou seja, blocos dentro de outros blocos: ``` Produtos cadastrados no sistema: NomeQuantidade {NOME} {QUANTIDADE} Nenhum registro encontrado. ``` E então, caso existam produtos, nós exibimos o bloco `PRODUTOS`. Caso contrário, exibimos o bloco `VAZIO`: ``` ``` Blocos Automáticos por Padrão ----------------------------- [](#blocos-automáticos-por-padrão) Um detalhe muito importante desta nova versão da biblioteca (versão 2.0 em diante) em relação a sua antecessora: agora, se um bloco aninhado é exibido, todos os blocos pais serão automaticamente exibidos. Ou seja, pegando o exemplo anterior, podemos simplificar o código PHP anterior para ficar assim: ``` ``` Ou seja, se existem produtos, e por consequência o `BLOCK_DADOS` foi exibido, o `BLOCK_PRODUTOS` automaticamente será. Mais continue lendo, vamos conseguir fazer mais coisas automaticamente, e com menos código, usando os blocos `FINALLY`. Blocos FINALLY -------------- [](#blocos-finally) No exemplo anterior, usamos o `BLOCK_PRODUTOS` para exibir os produtos, e caso não existam produtos, usamos o `BLOCK_VAZIO` para exibir uma mensagem amigável de que não existem produtos cadastrados. Podemos fazer isso de forma mais automática: usandos os blocos `FINALLY`. Veja como ficaria o arquivo HTML neste caso: ``` Produtos cadastrados no sistema: NomeQuantidade {NOME} {QUANTIDADE} Nenhum registro encontrado. ``` E o arquivo PHP? Bem, ele vai ficar mais simples ainda: ``` ``` Primeiro detalhe importante: o bloco `FINALLY` nunca precisa ser invocado no arquivo PHP. Caso ele exista no HTML, ele sempre será chamado se o bloco relacionado não for exibido. Ou seja, se não houverem produtos, o bloco `FINALLY` exibirá automaticamente o aviso de que não exitem registros encontrados. Prático, né? E segundo detalhe: no arquivo PHP, o bloco `BLOCK_PRODUTOS` nem foi chamado. Mas como o bloco mais interno, `BLOCK_DADOS`, foi chamado, o bloco pai automaticamente será mostrado. Blocos com HTML Select ---------------------- [](#blocos-com-html-select) Uma das dúvidas mais comuns é: como usar a classe Template com o elemento `select` do HTML? Ou melhor: como fazer um elemento `option` ficar selecionado, usando Template? Vamos então montar nossa página HTML com o elemento `select` e os devidos `options`, representando cidades de uma lista: ``` {TEXT} ``` Agora vamos ao respectivo arquivo PHP: ``` ``` Como resultado, o navegador exibirá o seguinte código: ``` Cidade 0 Cidade 1 Cidade 2 ``` Reparou que no arquivo PHP chamamos o método `clear`? Se não chamarmos este método (que limpa o valor de uma variável), todas as opções (`option`) ficariam com a propriedade `selected` (obviamente, efeito não desejado): ``` Cidade 0 Cidade 1 Cidade 2 ``` Usando vários arquivos HTML --------------------------- [](#usando-vários-arquivos-html) Um uso bastante comum de templates é usarmos um arquivo HTML que contenha a estrutura básica do nosso site: cabeçalho, rodapé, menus, etc. E outro arquivo com o conteúdo da página que desejamos mostrar, ou seja, o "miolo". Dessa forma, não precisamos repetir em todos os arquivos HTML os elementos comuns (cabeçalho, rodapé, etc), e as páginas HTML que terão o conteúdo (o "miolo") ficarão mais limpas, menores e mais fáceis de serem mantidas. Como fazer isso com templates? Em primeiro lugar, vamos criar nosso arquivo "base" HTML, o arquivo base.html: ``` Título da Página {FULANO}, seja bem vindo! {CONTEUDO} Deseja maiores informações? Clique aqui para saber ``` Agora, vamos criar o arquivo que contém o "miolo" de nossa página HTML, o arquivo miolo.html: ``` Produtos cadastrados no sistema: NomeQuantidade {NOME} {QUANTIDADE} Nenhum registro encontrado. ``` No arquivo PHP então, usamos o método addFile(), onde informamos duas coisas: em qual variável do template o conteúdo do novo arquivo será jogado, e qual o caminho desse arquivo. Depois disso, basta usar as variáveis e blocos normalmente, independente de qual arquivo HTML eles estejam: ``` ``` Guardando o conteúdo do template -------------------------------- [](#guardando-o-conteúdo-do-template) Até agora exibimos o conteúdo gerado pelo template na tela, através do método `show()`. Mas, e quisermos fazer outro uso para esse conteúdo, como salvá-lo em arquivo ou outra coisa do tipo? Basta usarmos o método `parse()`, que gera o conteúdo final e o retorna: ``` ``` Usando Objetos -------------- [](#usando-objetos) A classe Template suporta a atribuição de objetos para as variáveis de template desde a versão `1.5` (verifique no código fonte da classe sua versão). Isso ajuda bastante caso estejamos usando alguma biblioteca ORM, como [Doctrine2](http://doctrine-orm.readthedocs.org/en/latest/tutorials/getting-started.html), o [ORM do Kohana](http://kohanaframework.org/3.3/guide/orm/using) ou o [Eloquent do Laravel](http://laravel.com/docs/eloquent). Isso faz com que o código nos arquivos PHP fique bastante reduzido (claro, desde que você use objetos), e devido a isso, há uma melhora (quase imperceptível) em desempenho. Para que os exemplos fiquem mais claros, vamos trabalhar com uma suposta página que exibe detalhes de um produto. Os produtos possuem como atributos: `id` e `name`. A classe Template funcionará tanto com classes que usam encapsulamento (`get` e `set` do atributo), quanto para classes que chamam os atributos diretamente (geralmente através dos métodos mágicos do PHP). Primeiro, vamos a um exemplo de classe Produtos retirado diretamente dos [exemplos da Doctrine2](http://doctrine-orm.readthedocs.org/en/latest/tutorials/getting-started.html#starting-with-the-product): ``` ``` Vamos então modificar o arquivo PHP para carregar um produto, e usar o suporte a objetos de Template: ``` ``` O arquivo HTML também deve ser modificado pra exibir as propriedades de Produto: ``` Id: {P->ID} Nome: {P->NAME} ``` A instrução `P->NAME` chamará o método `$p->getName()`, caso ele exista. Se não existir esse método na classe, um erro será disparado. Isso vale para qualquer atributo que tentarmos chamar no HTML: será traduzido para `$meuObjeto->getAtributo()`. Se o nome do método PHP for composto, como por exemplo `$p->getExpirationDate()`, basta usar underscore `_` no HTML como separador dos nomes: no caso do exemplo, ficaria `P->EXPIRATION_DATE`. Se a biblioteca ORM não fizer uso de `get` e `set`, como no Kohana ou Laravel, também funciona: a classe Template vai ver se a classe Produto tem o atributo `$meuObjeto->atributo`, e ainda, se a classe tiver o método mágico `__get`, a classe Template também tentará chamá-lo. Comentários ----------- [](#comentários) A exemplo das linguagens de programação, a classe Template suporta comentários no HTML. Comentários são úteis para várias coisas, entre elas, identificar o autor do HTML, versão, incluir licenças, etc. Diferentemente dos comentários HTML, que são exibidos no código fonte da página, os comentários da classe Template são extraídos do HTML final. Na verdade os comentários de Template são extraídos antes mesmo de qualquer processamento, e tudo que estiver entre os comentários será ignorado. Os comentários ficam entre as tags `\`. Repare que usamos 3 tracinhos, ao invés de 2 (que identificam comentários HTML). A razão é simples: permitir diferenciarmos entre um e outro, e permitir que os editores continuem reconhecendo o conteúdo entre `` como comentários. Veja o exemplo abaixo: ``` Produtos cadastrados no sistema: NomeQuantidade {NOME} {QUANTIDADE} Nenhum registro encontrado. ``` Criando XML, CSV e outros ------------------------- [](#criando-xml-csv-e-outros) O uso mais comum de templates é com arquivos HTML. Mas como essa biblioteca é direcionada ao uso de qualquer tipo de arquivo de texto, podemos usá-la com vários outros formatos de arquivo, como XMLs e arquivos CSVs. Como fazer isso? Mais simples impossível: não muda nada, basta apenas ao invés de indicar um arquivo HTML para o Template, indicar qualquer outro arquivo de texto. E usar variáveis e blocos nele conforme já vimos, exibindo o conteúdo na tela, ou salvando em arquivos. Criando arquivos do Office -------------------------- [](#criando-arquivos-do-office) Se você precisa elaborar um relatório que deve ser exibido em formato do Word (`.doc`) ou do Excel (`.xls`), também podemos usar a classe Template para isso. Em primeiro lugar, crie normalmente no Office seu relatório. Após terminar, escolha a opção "Salvar como", e selecione o formato HTML. Feito isso, abra este arquivo HTML em seu editor PHP (não se assuste, é bastante poluído e cheio de tags estranhas) e use-o conforme visto até agora: crie variáveis, declare blocos, nada de diferente. Se você for salvar o conteúdo em um arquivo, coloque neste arquivo a extensão `.doc` (ou `.xls` no caso de uma planilha). O Office abrirá normalmente este arquivo, convertendo-o automaticamente de HTML para o formato desejado na primeira vez em que for aberto. Se você for exibir o conteúdo no navegador ao invés de salvá-lo num arquivo, você precisa modificar o header para avisar o navegador que se trata de um documento do Office, forçando o navegador a interpretá-lo como tal (o Firefox irá fazer o download do arquivo, o IE irá abrir o Microsoft Office como um plugin e exibir o arquivo dentro do navegador mesmo). Faça isso com a instrução `header()` do PHP: ```