include_once

A Instrução include_once do PHP

include_once inclui e avalia um arquivo durante a execução, mas somente se esse arquivo ainda não tiver sido incluído na requisição atual. Se o mesmo arquivo for solicitado novamente com include_once, o PHP o ignora silenciosamente. Isso o torna a escolha segura para arquivos que definem funções, classes ou constantes — incluir tal arquivo duas vezes provocaria um erro fatal "cannot redeclare".

Esta página aborda a sintaxe, como include_once difere de include e require_once, o que ele retorna e os casos comuns em que você realmente o utiliza.

Sintaxe

include_once é uma construção de linguagem, portanto os parênteses são opcionais:

include_once 'filename.php';
include_once('filename.php'); // also valid

O PHP rastreia o arquivo pelo seu caminho real resolvido. Assim, include_once 'lib.php' e include_once './lib.php' que apontam para o mesmo arquivo em disco são tratados como a mesma inclusão — a segunda é ignorada.

Como o include_once decide se deve incluir

A regra é uma inclusão por requisição. O exemplo abaixo usa tempnam() para criar um arquivo real em tempo de execução, escrever uma definição de função nele e incluí-lo duas vezes. Incluir uma definição de função duas vezes com include simples causaria uma falha; include_once não causa.

<?php

// Create a real file that defines a function.
$libFile = tempnam(sys_get_temp_dir(), 'lib');
file_put_contents($libFile, '<?php function greet($name) { return "Hello, $name!"; }');

include_once $libFile; // file is loaded, function defined
echo greet('Ada'), "\n";

include_once $libFile; // already included -> skipped, no redeclare error
echo greet('Linus'), "\n";

unlink($libFile);

// Output:
// Hello, Ada!
// Hello, Linus!

O segundo include_once não faz nada porque o arquivo já foi carregado, então greet() nunca é redeclarada.

Valor de retorno

include_once retorna 1 em uma inclusão nova (quando o arquivo não tem um return explícito) e true se o arquivo já foi incluído. Se o arquivo não puder ser encontrado, emite um aviso e retorna false (ele não interrompe o script — isso é função do require_once).

<?php

$result = include_once 'this-file-does-not-exist.php';
var_dump($result); // bool(false), plus a warning

// Output:
// bool(false)

Um arquivo também pode retornar um valor, o que é útil para arquivos de configuração:

<?php

// config.php would contain: <?php return ['debug' => true];
$config = include_once 'config.php';

include_once vs os outros três

O PHP possui quatro construções de inclusão de arquivo. Elas diferem em dois eixos — uma vez ou toda vez e aviso ou erro fatal quando o arquivo está ausente:

Use include_once quando o arquivo for opcional, mas não puder ser carregado duas vezes. Use require_once quando o arquivo for essencial (uma classe sem a qual seu código não pode funcionar) e não puder ser carregado duas vezes.

Quando usar

• Bibliotecas de funções e classes. Qualquer arquivo que declare uma função, classe ou interface deve ser carregado com include_once (ou require_once) para que um erro de redeclaração seja impossível, mesmo que várias partes da sua aplicação o importem.
• Cabeçalhos/rodapés compartilhados. Um header.php que deve ser renderizado uma vez por página.
• Constantes e configuração. Arquivos que define() constantes — redefinir uma constante gera um aviso.

No PHP moderno, o autoloader do Composer geralmente substitui a inclusão manual para classes, mas include_once ainda está em todo lugar em código legado, templates e scripts pequenos.

Armadilhas comuns

• Ele protege contra inclusão dupla, não ordem de carregamento. include_once não resolve magicamente dependências entre arquivos; ele apenas impede que o mesmo arquivo seja carregado duas vezes.
• A verificação "once" é por requisição, não persistente — cada requisição HTTP começa com uma lousa em branco.
• Symlinks e diferentes caminhos relativos para o mesmo arquivo são desduplicados pelo caminho real, mas um arquivo acessível por dois caminhos genuinamente diferentes (por exemplo, diferentes montagens) pode ser incluído duas vezes.

Conclusão

include_once inclui um arquivo exatamente uma vez por requisição, evitando erros fatais de redeclaração e saída duplicada. Use-o (ou require_once) sempre que um arquivo definir funções, classes ou constantes. Escolha entre as famílias include_* e require_* com base em se um arquivo ausente deve ser um aviso recuperável ou uma parada definitiva.

Prática