require

A instrução require do PHP

Em PHP, require pega o conteúdo de outro arquivo PHP, insere-o no ponto onde require aparece e o avalia como se tivesse sido escrito ali. É assim que projetos PHP dividem o código em vários arquivos: configuração, funções auxiliares, definições de classes e templates ficam em seus próprios arquivos e são incluídos com require.

O que distingue require do seu irmão include é como ele reage a um arquivo ausente. Se o arquivo de destino não puder ser encontrado, require para o script com um erro fatal, enquanto include apenas emite um aviso e continua. Isso torna require a escolha certa para arquivos sem os quais o script não pode funcionar.

Este guia aborda a sintaxe, exemplos executáveis, a diferença entre require e include, quando usar require_once, e os problemas comuns que causam confusão.

Sintaxe

require é um construtor de linguagem, não uma função, portanto pode ser escrito com ou sem parênteses:

require '/path/to/file.php';
require('/path/to/file.php'); // also valid, but parentheses are unnecessary

Na prática, você quase sempre quer que os caminhos sejam relativos ao script atual, e não ao diretório de trabalho do PHP. A constante mágica __DIR__ armazena o diretório do arquivo em que aparece, então construir caminhos a partir dela mantém o require funcionando independentemente de onde o script seja executado:

require __DIR__ . '/config.php';

Um exemplo executável

O trecho abaixo cria um pequeno arquivo auxiliar, o inclui com require e depois chama a função que ele define. Você pode colar tudo em um único arquivo .php e executá-lo — o auxiliar é criado no mesmo diretório em tempo de execução, tornando o exemplo autocontido.

<?php

// Create a helper file next to this script.
file_put_contents(__DIR__ . '/greet.php', <<<'PHP'
<?php
function greet($name) {
    return "Hello, $name!";
}
PHP);

// Pull the helper in. After this line greet() is available.
require __DIR__ . '/greet.php';

echo greet('Ada'); // Hello, Ada!

Saída:

Hello, Ada!

Uma vez que um arquivo é incluído com require, tudo o que ele declara — funções, classes e quaisquer variáveis de nível superior — passa a fazer parte do escopo atual, exatamente como se você tivesse digitado o código diretamente.

require vs include

Ambas as instruções carregam e avaliam um arquivo. A única diferença de comportamento é o que acontece quando o arquivo está ausente ou ilegível:

Use require para coisas como um arquivo de conexão com banco de dados ou um autoloader, onde continuar sem eles não faz sentido. Recorra a include somente quando um arquivo ausente deve ser tolerado — por exemplo, uma substituição de tema opcional.

require_once: evite carregar duas vezes

Incluir o mesmo arquivo duas vezes causa problemas: redeclarar uma função ou classe é em si um erro fatal. require_once resolve isso lembrando quais arquivos já foram carregados e ignorando qualquer solicitação repetida.

<?php
require_once __DIR__ . '/User.php'; // loads the file
require_once __DIR__ . '/User.php'; // already loaded — does nothing

Como regra geral, use require_once para arquivos que definem coisas (classes, bibliotecas de funções) e require simples para arquivos que você executa intencionalmente mais de uma vez, como um template renderizado em um loop. A mesma distinção entre once/non-once existe para include como include_once.

Padrões comuns

Um arquivo de configuração compartilhado carregado no topo de um script de entrada:

<?php
require __DIR__ . '/config.php';

// $dbHost, $dbUser, etc. defined in config.php are now available.
$pdo = new PDO("mysql:host=$dbHost", $dbUser, $dbPass);

Um arquivo incluído com require também pode retornar um valor com return, que require avalia. Esta é uma forma limpa de carregar um array de configuração:

// config.php
<?php
return [
    'host' => 'localhost',
    'port' => 3306,
];

// index.php
<?php
$config = require __DIR__ . '/config.php';
echo $config['port']; // 3306

Armadilhas comuns

• Construa caminhos a partir de __DIR__, não de strings relativas. require 'config.php' resolve a partir do diretório de trabalho atual do PHP, que pode diferir da localização do script e falhar silenciosamente em diferentes servidores web ou invocações via CLI.
• require executa no ponto em que aparece. Colocá-lo dentro de uma função (como no exemplo acima) adia o carregamento até que essa função seja chamada, e limita quaisquer variáveis de nível superior do arquivo ao escopo dessa função.
• Prefira um autoloader para classes. Incluir manualmente dezenas de arquivos de classe é propenso a erros. Projetos modernos usam o vendor/autoload.php do Composer (carregado uma vez com require) e deixam o autoloading PSR-4 carregar as classes sob demanda.

Conclusão

require é a base da organização de código em PHP: divide um programa em arquivos focados e carrega os que um script depende, falhando visivelmente se algum estiver ausente. Construa caminhos a partir de __DIR__, escolha require_once para definições a fim de evitar carregamento duplo, e use include somente quando um arquivo ausente for aceitável. Para bibliotecas de classes, um autoloader do Composer é o substituto moderno para listas de require escritas manualmente.

Prática