Construímos um formulário de contacto num .html separado, escrevemos um script de relatório em PHP e o editor do WordPress corrompe o código a cada gravação? Uma dor familiar para quem vai além do construtor de blocos padrão.

O Include Me resolve esta tarefa com uma única linha de shortcode: inclui um ficheiro HTML/PHP externo ou o conteúdo de outro artigo diretamente no corpo do artigo. O plugin está no diretório WordPress.org com mais de 4.000 instalações ativas, uma classificação de 4,8 e atualizações para o WP 6.9.4. O autor, Stefano Lissa, é o criador do Newsletter e do Hyper Cache.

Segue-se uma análise completa: da instalação à passagem de variáveis para scripts PHP e ao modo iframe seguro.

💡 Visão geral rápida:

• Instale o Include Me a partir do diretório WordPress.org (Plugins → Adicionar Novo, pesquise por "Include Me").
• Carregue o seu ficheiro HTML/PHP de destino para a pasta /wp-content/include-me/ no servidor.
• Insira o shortcode [includeme file="your-file.html"] onde precisar, num artigo ou página.
• Para ficheiros PHP: o plugin executará o script e produzirá o resultado. Para HTML, insere tal como está.
• Em alternativa, inclua outro artigo do WordPress através de post_id ou um URL externo através da sintaxe iframe.

O que é o Include Me e quando precisa dele

O Include Me é um plugin leve (apenas algumas linhas de código, segundo o autor) que resolve uma tarefa específica: inserir um ficheiro externo no corpo de um artigo ou página do WordPress através de shortcode.

Quando precisa disto na prática:

• Formulários e calculadoras. Escreveu um formulário HTML com CSS e JS, e o editor de blocos corrompe a marcação sempre que alterna entre o modo visual e o de texto. O Include Me insere o ficheiro byte por byte, sem alterar nada.
• Relatórios PHP. Um script obtém dados da base de dados, constrói uma tabela e gera HTML. O Include Me executa o PHP e mostra o resultado dentro do artigo sem editar o tema.
• Blocos partilhados. O mesmo ficheiro (tabela de preços, aviso legal, bloco de contacto) precisa de aparecer numa dúzia de páginas. Edite o ficheiro uma vez e ele atualiza-se automaticamente em todo o lado.
• Conteúdo de outro artigo. Incluiu texto de outra página através de post_id e este mantém-se sincronizado: edite num local, mostre em todo o lado.

A principal vantagem sobre um template de tema personalizado: quando muda de tema, os seus ficheiros permanecem no lugar. O tema muda, o conteúdo vive de forma independente.

Instalação e primeira execução

A instalação é padrão, através do painel de administração do WordPress:

• Plugins → Adicionar Novo.
• No campo de pesquisa, escreva "Include Me".
• Encontre o plugin de Stefano Lissa, clique em Instalar Agora → Ativar.

Após a ativação, o plugin está pronto a usar, sem ecrãs de configurações. Toda a "configuração" é feita através da sintaxe do shortcode.

Caminho de ficheiro predefinido: /wp-content/include-me/. Carregue os ficheiros que planeia incluir para esta pasta. Se precisar de um diretório diferente, adicione ao wp-config.php:

1
define('INCLUDE_ME_DIR', '/path/to/your/folder');

Se quiser incluir ficheiros de qualquer lugar no servidor, defina um asterisco (mas é mais seguro restringir a uma pasta):

1
define('INCLUDE_ME_DIR', '*');

Limitação de segurança importante: a partir da versão 1.3.0, o shortcode [includeme] só é executado em artigos cujo autor seja um administrador. Os ficheiros são procurados, por predefinição, dentro da pasta raiz do site (ABSPATH e abaixo). Isto não é um bug, mas uma salvaguarda: o Include Me executa código PHP e não deve dar essa capacidade a qualquer pessoa.

Sintaxe básica: incluir ficheiros HTML e PHP

O shortcode principal é [includeme file="filename"]. Funciona em qualquer artigo, página ou widget (via do_shortcode).

Exemplo 1: Ficheiro HTML. Preparou price-table.html com o layout e estilos de preços. Carregou-o para /wp-content/include-me/. No artigo, escreve:

1
[includeme file="price-table.html"]

O plugin lê o ficheiro e insere o seu conteúdo exatamente onde o shortcode é colocado. Uma tag <style> dentro do ficheiro funciona. JS inline funciona. Sem "sanitização" de marcação.

Exemplo 2: Script PHP. O ficheiro report.php executa um SELECT da base de dados e gera uma tabela. A extensão .php é o gatilho para o Include Me: o plugin não se limita a ler o ficheiro, mas executa-o via include. O output do script (echo/print) vai para o artigo:

1
[includeme file="report.php"]

Exemplo 3: Caminho relativo. Um caminho sem barra inicial (file="myfolder/data.html") é relativo à raiz do site (ABSPATH). Um caminho absoluto (file="/var/www/external/widget.html") começa na raiz do sistema de ficheiros do servidor. Na maioria dos casos, usa um caminho relativo para um ficheiro dentro de /wp-content/include-me/.

Incluir outro artigo ou página via post_id

Os criadores do Include Me adicionaram sintaxe para obter conteúdo de um artigo WordPress existente. O shortcode:

1
[includeme post_id="42"]

Onde 42 é o ID numérico do artigo ou página desejada. Como encontrar o ID: no painel de administração, passe o rato sobre o link "Editar" do artigo desejado e verá post=42 na barra de estado do navegador.

Esta técnica é conveniente para páginas legais. Políticas de privacidade ou termos de utilização são frequentemente duplicados: uma instância na página "principal", as restantes usam o Include Me com post_id. O advogado edita o texto num local e este atualiza-se em todo o lado.

Nota: apenas o conteúdo do artigo é obtido, não o título. Se também precisar do título, terá de o duplicar dentro do conteúdo ou usar [includeme file="..."] com um script PHP que chame get_post().

Modo iframe: incorporar um URL externo

A terceira sintaxe gera um <iframe> em vez da inclusão direta:

1
[includeme src="https://example.com/widget"]

Quaisquer atributos adicionais são passados para o <iframe> como atributos HTML:

1
[includeme src="https://example.com/widget" frameborder="0" width="600" height="450"]

O resultado é um iframe completo com as dimensões especificadas. Esta é uma alternativa à inclusão direta para casos em que:

• Precisa de mostrar uma página externa como uma "janela" dentro do artigo.
• O conteúdo incluído deve viver num contexto isolado (o seu próprio CSS/JS que não entra em conflito com o tema).
• Precisa de incorporar um widget interativo (calculadora, mapa) que não deve ser executado no contexto do WordPress.

Limitação: o modo iframe não executa PHP; simplesmente mostra o URL numa frame. Para código do lado do servidor, use file="...".

Passar variáveis para scripts PHP

A funcionalidade mais poderosa do Include Me é a passagem de parâmetros do shortcode para o ficheiro PHP incluído. No shortcode, escreve:

1
[includeme file="greeting.php" name="Alexey" plan="Pro"]

Dentro de greeting.php, acede aos atributos através do array global $attrs:

1
<?php
2
$user_name = $attrs['name'] ?? 'Guest';
3
$user_plan = $attrs['plan'] ?? 'Free';
4
 
5
echo "<p>Hello, {$user_name}! Your plan: {$user_plan}.</p>";

Isto transforma o Include Me num mini motor de templates. O mesmo ficheiro PHP gera output diferente dependendo dos atributos do shortcode. Cenários práticos:

• Calculadora de preços. Um único script calc.php recebe base_price e discount do shortcode, mostrando cálculos diferentes em páginas diferentes.
• Bloco personalizado. cta.php aceita heading e button_text, cada artigo tem o seu próprio título e botão, mas o esqueleto HTML é partilhado.
• Painel de cliente. client-stats.php recebe client_id e gera dados para um cliente específico a partir de um CRM externo.

O que o Include Me não faz: limitações

O plugin resolve uma tarefa restrita e não tenta ser um canivete suíço. Desvantagens que vale a pena conhecer antes da instalação:

• Apenas administradores. O shortcode funciona apenas em artigos cujo autor seja um administrador. Autores e editores não podem usar o Include Me; esta é uma restrição de segurança intencional (versão 1.2.2+).
• Sem editor visual. Sem IU no painel de administração: o plugin não adiciona uma metabox para seleção de ficheiros. Tudo é feito manualmente via shortcode.
• A extensão .php é necessária para execução. Um ficheiro chamado script.inc com código PHP NÃO será executado; o plugin irá inseri-lo como texto. Renomeie-o para script.php.
• Sem cache. Cada chamada de shortcode lê o ficheiro do disco ou executa o PHP de novo. Para páginas de alto tráfego com scripts pesados, faça a cache do output você mesmo (via API de Transients ou um plugin de cache ao nível da página).

⁉️🤔 Perguntas frequentes

O Include Me funciona com versões modernas do WordPress?

Sim, o plugin está testado até ao WordPress 6.9.4 e requer a versão 6.1 ou superior. A última atualização (1.3.7) foi lançada em fevereiro de 2026 e o autor mantém a compatibilidade com cada grande lançamento do WP.

É seguro incluir ficheiros PHP via shortcode?

Desde a versão 1.2.2, o plugin executa ficheiros PHP apenas a partir de uma pasta dentro da raiz do site e apenas para artigos cujo autor seja administrador. Isto impede a execução de código arbitrário via XSS ou substituição de URL. Adicionalmente, restrinja a pasta via define('INCLUDE_ME_DIR', '...') e evite usar '*' a menos que seja absolutamente necessário.

Como é que o Include Me difere do plugin Insert Pages?

O Insert Pages foca-se em inserir conteúdo de outros artigos; tem um conjunto rico de opções de formatação e wrapper. O Include Me é mais simples e concebido para trabalhar com ficheiros: HTML, PHP, TXT. Se a sua tarefa é apenas obter outro artigo, o Insert Pages é mais conveniente. Se precisa de scripts PHP e ficheiros externos, o Include Me é a escolha.

Posso inserir o mesmo ficheiro em dez páginas?

Sim, é exatamente para isso que o plugin foi concebido. Um ficheiro em /wp-content/include-me/ é incluído via o mesmo shortcode em qualquer número de páginas. Edite o ficheiro e o conteúdo atualiza-se em todo o lado instantaneamente, sem regravar cada artigo.

Porque é que o meu ficheiro PHP não produz output nenhum?

Três razões comuns: (1) o ficheiro não está na pasta INCLUDE_ME_DIR e o caminho está incorreto; (2) existe um erro fatal no código PHP (verifique WP_DEBUG e os logs do servidor); (3) o ficheiro foi gravado com uma extensão .html ou .inc em vez de .php (o Include Me só executa .php).

E se o plugin deixar de receber atualizações?

O Include Me consiste em apenas algumas linhas de código (segundo o autor) e não depende de serviços externos. Mesmo sem atualizações, continuará a funcionar durante anos; a sua lógica não está ligada à WP REST API, blocos ou funcionalidades específicas do Gutenberg. O mecanismo básico de shortcode do WordPress não mudou desde a versão 2.5.

O que fazer se precisar de mais: alternativas e próximos passos

Se o Include Me não cobre as suas necessidades, aqui estão duas direções para expansão:

• Inserir artigos com formatação: o plugin Insert Pages obtém conteúdo de outros artigos com definições de exibição flexíveis (título, excerto, wrapper personalizado).
• Motor PHP completo: o plugin WPCode (anteriormente Insert Headers and Footers) permite inserir snippets PHP globalmente ou condicionalmente, com realce de sintaxe e controlo de erros.

Comece com o Include Me: para a tarefa típica de "inserir um ficheiro externo num artigo", é mais do que suficiente. E se já usou este plugin ou resolveu uma tarefa semelhante de forma diferente, partilhe nos comentários qual a ferramenta que escolheu.