PHP Include

Introdução

As instruções include e require do PHP permitem inserir o conteúdo de um arquivo PHP em outro antes de o servidor executá-lo. Essa é a base da reutilização de código em PHP: em vez de copiar uma barra de navegação, uma conexão de banco de dados ou um conjunto de funções auxiliares em cada página, você o escreve uma única vez em um arquivo separado e o importa onde for necessário.

Este capítulo aborda as quatro instruções de inclusão (include, require, include_once, require_once), como elas diferem, como variáveis e funções de arquivos incluídos se comportam, armadilhas comuns e as boas práticas que mantêm projetos maiores sustentáveis.

Por que usar inclusão de arquivos

Dividir o código em arquivos reutilizáveis traz três ganhos concretos:

1. Menos repetição. Escreva um cabeçalho, rodapé ou bloco de configuração uma vez e inclua-o em quantas páginas precisar. Edite em um único lugar e todas as páginas são atualizadas.
2. Manutenção mais fácil. Uma correção de bug ou alteração de design na marcação compartilhada acontece em um único arquivo, e não em dezenas de páginas.
3. Melhor organização. Dividir um script grande em arquivos menores com nomes por propósito (header.php, db.php, functions.php) torna o código mais fácil de ler e navegar.

As quatro instruções de inclusão

O PHP oferece quatro instruções. Todas copiam o conteúdo de um arquivo para o script atual, mas diferem em como lidam com um arquivo ausente e se permitem a re-inclusão.

Regra geral: use require (ou require_once) para arquivos sem os quais a página não funciona — uma conexão de banco de dados ou a definição de uma classe. Use include para partes opcionais, como um espaço de anúncio ou uma barra lateral que é útil ter, mas não é crítica.

Sintaxe básica

<?php
// Include a file relative to the current script
include __DIR__ . '/header.php';

// Stop the page if a critical file is missing
require __DIR__ . '/db.php';

// Guarantee a file is loaded at most once
require_once __DIR__ . '/functions.php';
?>

__DIR__ é uma constante mágica que resolve para o diretório do arquivo atual. Construir caminhos a partir dela faz com que as inclusões funcionem independentemente do diretório a partir do qual o script é executado — veja PHP Constants para mais informações sobre constantes mágicas.

Por que _once é importante

Se você incluir duas vezes um arquivo que define uma função ou classe, o PHP lança um erro fatal "Cannot redeclare" na segunda passagem. include_once e require_once rastreiam quais arquivos já foram carregados e ignoram silenciosamente as duplicatas, portanto são a opção segura padrão para qualquer arquivo que declare funções ou classes.

<?php
require_once __DIR__ . '/functions.php'; // loads it
require_once __DIR__ . '/functions.php'; // skipped — no redeclare error
?>

Escopo de variáveis em arquivos incluídos

Um arquivo incluído é executado no escopo da linha onde foi incluído. Variáveis definidas antes do include ficam disponíveis dentro do arquivo incluído, e variáveis que o arquivo incluído define ficam disponíveis depois.

<?php
// config.php
$siteName = "My Site";
$year = 2026;

<?php
// index.php
include __DIR__ . '/config.php';
echo "Welcome to $siteName ($year)";
// Output: Welcome to My Site (2026)
?>

Dentro de uma função, porém, as variáveis de um arquivo incluído são locais a essa função. Isso pega as pessoas de surpresa — um arquivo de configuração incluído dentro de uma função não vazará suas variáveis para o escopo global.

Retornando um valor de um arquivo incluído

Um arquivo incluído pode return um valor, o que é útil para arrays de configuração:

<?php
// settings.php
return [
    'debug'   => true,
    'timezone' => 'UTC',
];

<?php
// app.php
$config = include __DIR__ . '/settings.php';
echo $config['timezone']; // Output: UTC
?>

Tratando arquivos ausentes com elegância

Com include, um arquivo ausente apenas aciona um aviso, então o restante da página ainda é renderizado. Se um arquivo for opcional, verifique sua existência primeiro:

<?php
$sidebar = __DIR__ . '/sidebar.php';

if (file_exists($sidebar)) {
    include $sidebar;
} else {
    echo "<!-- sidebar unavailable -->";
}
?>

Para arquivos que a página genuinamente precisa, prefira require para que o script falhe de forma rápida e clara, em vez de produzir uma saída quebrada.

Boas práticas

1. Use require_once para código, include para saída opcional. Definições de funções/classes nunca devem ser carregadas duas vezes; fragmentos opcionais de UI podem degradar graciosamente.
2. Construa caminhos a partir de __DIR__. Evite caminhos relativos como include 'header.php', que dependem do diretório de trabalho atual e quebram inesperadamente.
3. Nomeie arquivos por propósito. header.php, footer.php, db.php, auth.php — uma olhada no nome do arquivo deve indicar o que está dentro.
4. Mantenha os arquivos incluídos focados. Uma responsabilidade por arquivo torna-os fáceis de reutilizar e raciocinar.
5. Nunca inclua um caminho construído a partir de entrada do usuário (ex.: include $_GET['page']). Isso abre uma vulnerabilidade de Inclusão de Arquivo Local/Remoto. Use uma lista de permissões de valores aceitos.

Conclusão

A família include e require é como os projetos PHP se mantêm DRY: marcação compartilhada, configuração e lógica vivem em arquivos únicos e são importados para as páginas sob demanda. Use require/require_once quando um arquivo for obrigatório, include/include_once quando for opcional, sempre ancore caminhos com __DIR__ e nunca inclua um caminho controlado pelo usuário. Em seguida, veja PHP Functions para organizar a lógica reutilizável que você normalmente colocará nos arquivos incluídos.

Diagrama

graph TD;
A[PHP Page]-->B[Included File];

Prática