require, include, require_once, include_once em PHP: guia completo com exemplos

require, include, require_once, include_once em PHP: qual escolher e por que isso é importante?

Você já se pegou pensando: "Qual é a diferença entre require e include no PHP? E por que existem essas versões estranhas com _once?" — Se sim, você não está sozinho. Essa pergunta está entre as mais populares no Stack Overflow (milhares de visualizações e dezenas de votos). E não é por acaso.

Diariamente, milhares de desenvolvedores PHP — de iniciantes a experientes — usam essas funções. Mas muitos as usam no automático, sem pensar nas consequências. E isso é um erro. A escolha errada pode causar erros fatais, duplicação de código ou, pior ainda, bugs silenciosos que só aparecem no servidor de produção.

Hoje vamos entender de uma vez por todas as diferenças entre require, include, require_once e include_once. Você vai aprender não só a teoria, mas também ver exemplos práticos de código que pode testar agora mesmo. Vamos nessa!

1. O básico: por que incluir arquivos?

Antes de falar sobre as diferenças, vamos lembrar por que fazemos isso. Em projetos reais, o código PHP não é escrito em um único arquivo gigante. Isso seria um pesadelo de manutenção. Em vez disso, o código é dividido em módulos:

\n
• Configuração — config.php
\n
• Funções — functions.php
\n
• Templates — header.php, footer.php
\n
• Classes — User.php, Database.php
\n

E é aí que entram require e include. Eles literalmente "colam" o conteúdo de um arquivo dentro de outro. O PHP processa o arquivo incluído como se o código dele estivesse escrito exatamente naquele local.

2. require vs include: a principal diferença é a reação a erros

Este é o ponto mais importante. Grave isso de uma vez por todas.

include — inclusão suave

include tenta incluir o arquivo. Se o arquivo não existir ou ocorrer um erro, o PHP emite um Warning (aviso), mas continua a execução do script.

<?php\n// include.php\necho "Isso é um include. ";\ninclude 'arquivo_inexistente.php'; // Gera um Warning\necho "O script continua funcionando!";\n?>\n

Resultado:

Isso é um include. Warning: include(arquivo_inexistente.php): failed to open stream...\nO script continua funcionando!

Percebeu? O script não quebrou, ele seguiu em frente. Isso é útil quando a inclusão do arquivo é opcional. Por exemplo, ao incluir um widget que não é essencial para a página.

require — inclusão obrigatória

require faz a mesma coisa, mas com uma diferença crucial: se o arquivo não for encontrado, o PHP emite um Fatal Error (erro fatal) e interrompe o script imediatamente.

<?php\n// require.php\necho "Isso é um require. ";\nrequire 'arquivo_inexistente.php'; // Gera um Fatal Error\necho "Este código nunca será executado!";\n?>\n

Resultado:

Isso é um require. Fatal error: Uncaught Error: Failed opening required 'arquivo_inexistente.php'...

O script morreu. Ponto final. Silêncio total.

Quando usar cada um?

\n
• require — para arquivos críticos: configuração do banco de dados, classes principais, roteador. Se eles não existirem, o site não pode funcionar.
\n
• include — para blocos opcionais: templates, widgets, banners de anúncios. Se o arquivo não for incluído, a página simplesmente será exibida sem aquele bloco.
\n

3. require_once e include_once: proteção contra duplicação

Agora imagine a seguinte situação. Você tem um arquivo config.php que declara constantes e funções. Você p