Download the PHP package jonatasrt/template without Composer

Template

Engine de template para PHP 8.0+ que mantém o HTML completamente livre de código PHP.

Esta biblioteca é uma reescrita moderna da clássica raelgc/template (criada por Rael Gugelmin Cunha), com compatibilidade total de sintaxe: as mesmas variáveis, os mesmos blocos, os mesmos modificadores, o mesmo suporte a objetos e comentários.

Você não precisa reescrever nenhum arquivo HTML. Qualquer template que funcionava na versão antiga funciona aqui, sem nenhuma alteração.

Índice

• Requisitos
• Instalação
• Migrando do raelgc/template
• Olá Mundo
• Variáveis
• Checando se variáveis existem
• Variáveis dinâmicas
• Variáveis com modificadores
• Blocos
• Blocos aninhados
• Blocos automáticos por padrão
• Blocos FINALLY
• Blocos com HTML select
• Usando vários arquivos HTML
• Guardando o conteúdo do template
• Usando objetos
• Comentários
• Escapando variáveis
• Criando XML, CSV e outros formatos
• Mensagens de erro
• Precisão e desempenho
• Referência da API
• Licença

Requisitos

• PHP >= 8.0 (testado em 8.0, 8.1, 8.2, 8.3 e 8.4)
• Nenhuma extensão além das padrão (pcre, json)

Não há warnings, notices nem deprecations mesmo com error_reporting(E_ALL).

Instalação

Via Composer

Via download / cópia manual

Baixe o repositório e inclua o arquivo diretamente:

Migrando do raelgc/template

O HTML não muda em nada. No PHP, só existem duas possibilidades:

Opção 1 — trocar o use (recomendado):

Opção 2 — nem mexer no use: crie um alias logo depois de carregar a biblioteca e todo o código antigo continua funcionando sem nenhuma alteração:

A partir daí, use raelgc\view\Template; e new raelgc\view\Template(...) seguem válidos.

Se por algum motivo a versão antiga ainda estiver carregada no mesmo processo, não há conflito: a função global replace() é declarada dentro de um function_exists().

Olá Mundo

hello.html:

hello.php:

Resultado:

Variáveis

Toda variável de template é escrita entre chaves: {NOME_DA_VARIAVEL}.

• São aceitos apenas caracteres alfanuméricos e o underscore (_).
• São case sensitive: {FULANO} é diferente de {fulano}.
• São identificadas automaticamente na leitura do arquivo — não é preciso declarar nada.
• Variáveis não preenchidas são removidas do resultado final (não sobra {VARIAVEL} na tela).

Atribuir uma variável que não existe no HTML lança uma exceção:

Esse comportamento é intencional: ele avisa cedo sobre erros de digitação.

Checando se variáveis existem

Variáveis dinâmicas

Quando o nome da variável só é conhecido em tempo de execução, use chaves:

Variáveis com modificadores

É possível aplicar funções PHP direto no HTML, usando |:

Regras:

• O valor da variável é sempre passado como primeiro argumento da função.
• Parâmetros extras vêm depois, separados por :.
• Modificadores podem ser encadeados (aplicados da esquerda para a direita).
• Qualquer função callable do PHP (ou sua própria função) pode ser usada.

Como str_replace() recebe o texto no terceiro parâmetro, a biblioteca já registra a função global replace(), com o texto em primeiro lugar:

Um modificador inexistente lança BadFunctionCallException.

Blocos

Blocos são trechos do HTML que podem ser repetidos, ou simplesmente omitidos. São delimitados por comentários HTML:

Pontos importantes:

• Um bloco só aparece se block() for chamado. Se nunca for chamado, ele simplesmente não existe no HTML final — é assim que se faz conteúdo condicional.
• Nomes de blocos são identificados automaticamente e devem ser únicos no template (blocos duplicados lançam UnexpectedValueException).
• Chamar block() para um bloco inexistente lança InvalidArgumentException.
• Um bloco mal formado (sem END, por exemplo) lança UnexpectedValueException.

Blocos aninhados

Blocos podem conter outros blocos, sem limite de profundidade:

Sempre que o bloco pai é exibido, os blocos filhos acumulados são "descarregados" e limpos, prontos para a próxima iteração.

Blocos automáticos por padrão

Se um bloco aninhado é exibido, todos os blocos pais são exibidos automaticamente. Ou seja, no exemplo acima basta chamar block("BLOCK_DADOS"): o BLOCK_PRODUTOS aparece sozinho.

Blocos FINALLY

Um bloco FINALLY é exibido apenas quando o bloco correspondente nunca foi exibido. É o "senão" do template — perfeito para mensagens de lista vazia:

Sem if, sem count(), sem código extra.

Blocos com HTML select

O caso clássico de "qual opção está selecionada":

O método clear() é essencial aqui: sem ele, o valor da iteração anterior continuaria valendo.

Usando vários arquivos HTML

Ideal para separar cabeçalho, rodapé e miolo:

base.html:

miolo.html:

As variáveis e blocos do arquivo incluído passam a fazer parte do mesmo template — você continua usando $tpl->VARIAVEL e $tpl->block(...) normalmente.

addFile() também aceita arquivos .php (.php5, .php7, .php8, .phtml, .cgi): nesse caso o arquivo é executado e sua saída vira o valor da variável.

Guardando o conteúdo do template

Usando objetos

Objetos podem ser atribuídos direto às variáveis de template — muito útil com ORMs (Doctrine, Eloquent, etc.):

A ordem de resolução de cada propriedade é:

1. getter (getNome()) — aceita camelCase e snake_case: {OBJ->minha_prop} chama getMinhaProp()
2. método mágico __get()
3. propriedade pública com o nome normalizado
4. propriedade pública com o nome exato
5. getter booleano (isAtivo())
6. ArrayAccess ($obj['chave'])

Se nenhum acessor for encontrado, é lançada BadMethodCallException com a mensagem exata do que falta — em vez do erro fatal de acesso a propriedade privada.

Se o objeto no meio da cadeia for null, o resultado é string vazia (não quebra).

Detalhes:

• Objeto com __toString(): o valor é usado direto em {VARIAVEL} (sem ->).
• Objeto sem __toString() usado como {VARIAVEL}: vira Object: {"json":"do objeto"}, o que ajuda muito na hora de depurar.
• Modificadores funcionam em propriedades: {USUARIO->nome|strtoupper}.

Comentários

Comentários de template usam três traços e nunca chegam ao HTML final:

Comentários HTML normais (<!-- ... -->) são preservados.

Escapando variáveis

Para manter uma variável literal no HTML final (útil quando você gera templates a partir de templates), insira {_} logo depois da chave de abertura:

O resultado final conterá {CONTEUDO}.

Criando XML, CSV e outros formatos

A classe não é específica de HTML — ela trabalha com texto. Você pode usar arquivos .xml, .csv, .txt, .svg, .json ou qualquer outro formato, com a mesma sintaxe de variáveis e blocos (os delimitadores de bloco usam sintaxe de comentário HTML/XML).

Mensagens de erro

Como todas herdam de Exception, dá para tratar tudo junto:

Precisão e desempenho

A biblioteca evita expressões regulares no caminho quente — o trabalho pesado é feito com str_replace(), o que a torna bem mais rápida que engines antigas do estilo PHPLib. Não há cache em disco, e nem é necessário: em praticamente todo sistema real o gargalo é o banco de dados, não o template.

Um efeito colateral disso é que tabulações no início dos blocos são mantidas no HTML final (elas não afetam a renderização). Se você precisa de uma reprodução fiel — por exemplo, dentro de <pre> ou <code> — use o segundo parâmetro do construtor:

Referência da API

Licença

LGPL-2.1-or-later — a mesma da biblioteca original. Você pode usá-la como biblioteca inclusive em projetos comerciais.

Créditos ao autor original: Rael Gugelmin Cunha (raelgc/template).