include

A Instrução include do PHP

include importa o conteúdo de outro arquivo PHP para o script atual e o executa no ponto em que a instrução aparece. Conceitualmente, o PHP copia o arquivo incluído no lugar, avalia-o no mesmo escopo e continua. É assim que você evita repetir marcação e lógica compartilhada — cabeçalhos, rodapés, navegação, configuração e funções reutilizáveis — em várias páginas.

Esta página aborda a sintaxe, como o escopo funciona, o que include retorna, como ele difere de require e os erros comuns a evitar.

Sintaxe

include 'filename.php';

O caminho pode ser relativo ou absoluto. include é uma construção de linguagem, não uma função, portanto os parênteses são opcionais — tanto include 'file.php'; quanto include('file.php'); funcionam.

Quando o PHP executa um include, ele procura o arquivo nesta ordem: o caminho fornecido (se relativo, resolvido em relação ao diretório de trabalho atual e à configuração include_path), depois o diretório do script em execução. Para tornar os includes robustos independentemente de onde o script de entrada é chamado, ancore-os ao arquivo atual:

include __DIR__ . '/partials/header.php';

__DIR__ é o diretório do arquivo que contém a instrução, portanto o include é resolvido corretamente mesmo quando o script é executado a partir de outro diretório.

Um exemplo funcional

Como include opera em arquivos separados, a maneira mais clara de vê-lo em ação é criar esses arquivos em tempo de execução. O trecho abaixo escreve um pequeno parcial, inclui-o e imprime o resultado — é totalmente executável como um único script:

<?php
// Create a reusable partial on disk.
file_put_contents(__DIR__ . '/greeting.php', '<?php echo "Hello, " . $name . "!"; ?>');

// Variables defined here are visible inside the included file (shared scope).
$name = "Ada";

echo "Page top\n";
include __DIR__ . '/greeting.php';   // runs greeting.php here
echo "\nPage bottom\n";

// Output:
// Page top
// Hello, Ada!
// Page bottom

O arquivo incluído pode ler $name porque include compartilha o escopo circundante. Essa é a coisa mais importante a entender sobre include: ele não é um sistema de módulos isolado. Quaisquer variáveis que existam antes do include ficam disponíveis para o arquivo incluído, e quaisquer variáveis que o arquivo incluído defina vazam de volta para o chamador.

Retornando um valor de um arquivo incluído

Um arquivo incluído pode return um valor, que se torna o resultado da expressão include. Essa é a maneira idiomática de carregar configuração:

<?php
// Write a config file that returns an array.
file_put_contents(__DIR__ . '/config.php', '<?php return ["env" => "prod", "debug" => false];');

$config = include __DIR__ . '/config.php';

echo $config["env"];        // prod
echo "\n";
var_export($config["debug"]); // false

// Output:
// prod
// false

Se o arquivo incluído não usar return, a expressão include avalia para 1 em caso de sucesso.

include vs require (e as variantes _once)

O PHP possui quatro instruções relacionadas. Todas importam um arquivo; elas diferem em o que acontece em caso de falha e se inclusões duplicadas são ignoradas.

Regras práticas:

• Use require para arquivos sem os quais o script não pode ser executado (um arquivo de configuração, uma definição de classe, uma conexão de banco de dados). Falhar rapidamente com um erro fatal é mais seguro do que continuar em um estado corrompido.
• Use include para partes opcionais, como um widget de barra lateral ou um bloco de anúncio, onde um arquivo ausente não deve derrubar a página inteira.
• Use as variantes _once quando reincluir um arquivo causaria erros — mais comumente quando ele declara funções ou classes, pois redeclará-las é um erro fatal.

Armadilhas comuns

• Confiar em entradas do usuário em um caminho. Nunca passe dados de requisição não filtrados para include (por exemplo include $_GET['page'] . '.php';). Isso abre a porta para ataques de inclusão de arquivo local. Em vez disso, valide contra uma lista de permissão de arquivos conhecidos.
• Caminhos relativos que quebram. Um include 'header.php'; simples depende do diretório de trabalho atual e pode falhar quando o script é invocado de outro lugar. Prefira caminhos ancorados com __DIR__.
• Redeclarar funções ou classes. Se um arquivo que define funções for importado duas vezes via include simples, o PHP lança um erro fatal "Cannot redeclare". Use include_once para esses arquivos.
• Assumir isolamento. Como o escopo é compartilhado, um arquivo incluído pode sobrescrever suas variáveis. Mantenha os includes focados e previsíveis.

Por que usar include

• Reutilização — defina marcação ou lógica compartilhada uma vez e importe-a em cada página que precisar.
• Manutenibilidade — altere a navegação em um parcial e todas as páginas são atualizadas.
• Estrutura — divida uma aplicação grande em arquivos pequenos e focados em vez de um monólito.

Tópicos relacionados

• PHP require e require_once — os equivalentes que falham imediatamente.
• PHP include_once — incluir um arquivo no máximo uma vez.
• PHP Functions — o que você normalmente coloca em arquivos compartilhados e incluídos.
• PHP File Handling — leitura e escrita de arquivos em tempo de execução.

Prática