Central de Ajuda

As construções include e require carregam e avaliam outro arquivo no contexto atual. Elas ajudam a separar configuração, funções e templates, mas incluir um caminho controlado pelo visitante pode criar vulnerabilidade de inclusão local ou remota. Em aplicações modernas, prefira autoload do Composer para classes e caminhos construídos pelo próprio código.

Diferenças

Use require para um arquivo indispensável à inicialização. Use include quando a ausência foi prevista e existe tratamento real. As variantes _once evitam redeclaração, mas não substituem uma arquitetura de dependências.

Caminhos previsíveis com __DIR__

<?php
declare(strict_types=1);

$config = require __DIR__ . '/../config/app.php';
require_once __DIR__ . '/../vendor/autoload.php';

__DIR__ usa o diretório do arquivo atual e não depende do diretório de trabalho da requisição ou do cron. Coloque configuração e código sensível fora do document root sempre que possível.

Arquivo de configuração que retorna dados

<?php
// config/app.php
return [
    'environment' => getenv('APP_ENV') ?: 'production',
    'debug' => false,
];

Não grave senha real no repositório. Use variáveis de ambiente ou o mecanismo de segredos do framework e limite leitura dos arquivos.

O padrão perigoso

<?php
// NÃO faça isto:
include $_GET['pagina'] . '.php';

Um atacante pode tentar sequências de diretório, wrappers PHP ou arquivos enviados. Retirar ../ com substituição simples não torna o código seguro.

Use uma lista explícita

<?php
$paginas = [
    'inicio' => __DIR__ . '/pages/inicio.php',
    'contato' => __DIR__ . '/pages/contato.php',
];

$chave = $_GET['pagina'] ?? 'inicio';
if (!isset($paginas[$chave])) {
    http_response_code(404);
    exit('Página não encontrada.');
}
require $paginas[$chave];

Para aplicações maiores, use roteador e controladores do framework. Nunca transforme diretamente uma URL em caminho de arquivo executável.

Autoload com Composer

Classes devem seguir namespaces e PSR-4 quando possível:

{
  "autoload": {
    "psr-4": {"App\\": "src/"}
  }
}

composer dump-autoload --optimize

Depois, carregue uma vez vendor/autoload.php. Isso evita uma sequência manual de includes e torna dependências rastreáveis.

Includes remotos

Não habilite allow_url_include. Esse recurso é obsoleto há várias versões e amplia risco de execução. Para consumir uma API ou arquivo remoto, use cliente HTTP com timeout, validação de certificado, limite de tamanho e tratamento de resposta; não execute o conteúdo como PHP.

Escopo e saída

Um arquivo incluído herda o escopo do ponto de chamada, o que pode expor ou sobrescrever variáveis. Templates devem receber dados explicitamente e escapar cada valor no contexto correto. Evite efeitos colaterais em arquivos de definição.

Diagnóstico

• registre o caminho resolvido sem incluir segredos;
• confira maiúsculas e minúsculas no Linux;
• use is_file() e is_readable() apenas quando a ausência é esperada;
• verifique permissões e proprietário;
• não revele o caminho completo ao visitante;
• revise open_basedir e include_path somente quando o log apontar.

Referência: manual do include. Para opções relacionadas, veja allow_url_fopen e allow_url_include e o guia de desenvolvimento PHP seguro.

Recursos relacionados

Continue com materiais e serviços relacionados ao tema deste guia.