require_once

A Palavra-chave PHP require_once

require_once inclui e avalia um arquivo PHP externo no ponto onde a instrução é escrita — mas somente na primeira vez que esse arquivo é solicitado. Se o mesmo arquivo for solicitado novamente posteriormente na mesma requisição, o PHP o ignora. Isso torna require_once a forma mais segura de importar arquivos que definem funções, classes, traits ou constantes, pois carregá-los uma segunda vez causaria falha no script.

Esta página aborda a sintaxe, como a garantia de "uma vez" funciona, exemplos executáveis e como require_once difere de require, include e include_once.

Sintaxe

A palavra-chave require_once inclui e avalia um arquivo PHP externo, garantindo que ele seja processado apenas uma vez. Veja a sintaxe básica:

A sintaxe PHP de require_once

require_once 'path/to/file.php';

Isso inclui e avalia o conteúdo de path/to/file.php, mas somente se ele ainda não tiver sido incluído durante esta requisição. Por ser um construtor de linguagem (não uma função), os parênteses são opcionais — require_once 'file.php'; e require_once('file.php'); se comportam da mesma forma.

Nota: Se o arquivo especificado não puder ser encontrado, require_once dispara um erro fatal e interrompe o script. Seu equivalente include_once apenas emite um aviso e permite que o script continue.

Como a garantia de "apenas uma vez" funciona

O PHP mantém uma lista interna de arquivos que já foram carregados (resolvidos para seus caminhos absolutos). Quando encontra um require_once, ele verifica essa lista primeiro:

• Se o arquivo não está na lista, o PHP carrega e executa-o, depois o adiciona à lista.
• Se o arquivo já está na lista, o PHP não faz nada e continua.

Isso é o que torna require_once seguro para arquivos que definem coisas. Os dois arquivos a seguir demonstram isso. helpers.php define uma função e imprime uma linha para que possamos ver quando ela realmente é executada:

<?php
// helpers.php
echo "helpers.php is being loaded\n";

function greet($name)
{
    return "Hello, $name!";
}

<?php
// main.php
require_once 'helpers.php';
require_once 'helpers.php'; // second request is silently skipped

echo greet("World") . "\n";

Executar main.php imprime:

helpers.php is being loaded
Hello, World!

A linha "helpers.php is being loaded" aparece apenas uma vez, mesmo que o arquivo tenha sido solicitado duas vezes — e a segunda solicitação não redeclarou greet(), o que de outra forma seria um erro fatal.

Exemplos

Vejamos alguns exemplos práticos de como a palavra-chave require_once pode ser usada:

Exemplos de require_once em PHP

<?php

// Example 1
require_once 'config.php';

// Example 2
function myFunction()
{
  require_once 'helpers.php';
  // Code block here
}

Ambos os exemplos incluem e avaliam arquivos externos exatamente uma vez. Isso evita os erros que ocorrem quando um arquivo é carregado duas vezes — mais comumente, a redeclaração de uma função ou classe.

Nota: Embora require_once possa ser colocado dentro de uma função, o rastreamento de inclusão do PHP é global para toda a requisição. O posicionamento no nível superior é geralmente preferido; recorra à inclusão dentro de funções apenas quando o carregamento precisar ser condicional.

require_once vs as outras palavras-chave de inclusão

O PHP possui quatro construtos de inclusão. Eles diferem em dois eixos independentes: o que acontece em caso de falha e se o arquivo pode ser carregado mais de uma vez.

As variantes _once existem precisamente para evitar a re-execução de um arquivo. Com o simples require, solicitar helpers.php duas vezes o executa duas vezes — e a segunda execução falha fatalmente ao tentar redeclarar greet():

PHP Fatal error: Cannot redeclare function greet() ...

Regra geral: use require_once para arquivos que definem coisas (bibliotecas de funções, classes, configurações que não devem ser executadas duas vezes); use include para arquivos que apenas produzem saída, como um cabeçalho de página reutilizável que você renderiza intencionalmente várias vezes.

Benefícios

O uso da palavra-chave require_once traz vários benefícios, incluindo:

• Prevenção de erros: Garante que um arquivo seja processado apenas uma vez, evitando erros fatais por redeclaração de funções, classes ou traits.
• Uso eficiente de recursos: Evita carregamento e análise redundantes de arquivos. (Nota: o PHP mantém uma pequena sobrecarga de rastreamento para arquivos incluídos, mas isso geralmente é compensado pelo custo de reanalisar arquivos grandes.)

Conclusão

Em conclusão, require_once é uma ferramenta confiável para incluir arquivos PHP externos enquanto evita processamento duplicado e erros fatais. Use-o quando um arquivo precisar ser carregado exatamente uma vez, e escolha require ou include quando precisar de tratamento de erros diferente ou quiser evitar a sobrecarga de rastreamento. Esperamos que este guia ajude você a escrever um código PHP mais robusto.

Prática