Diferença entre include, include_once, require e require_once - PHP

Incluir arquivos para o escopo de outro arquivo pode ser muito útil para diversas finalidades, como organizar o código, evitar reescrever o mesmo código uma ou mais vezes, entre outras finalidades. E para isso o PHP nos disponibiliza as estruturas de controle chamadas include, include_once, require e require_once. Neste artigo vamos ver para que servem essas estruturas e suas diferenças.

Antes de saber a diferença de cada uma, vamos relembrar ou aprender, caso você não saiba, como funciona tanto o include, include_once, require e require_once.

Como funciona o include e o require no PHP

Conforme a documentação do PHP, os arquivos são incluídos baseando-se no caminho do arquivo informado, em outras palavras, será procurado o arquivo conforme o caminho que você digitou na estrutura include, include_once, require ou require_once.
Podendo ser caminhos absolutos, como:

include '/var/www/html/index.php';
// ou
include 'C:\Users\index.php';

ou caminhos relativos:

include '../html/index.php';

Caso não seja informado nenhum caminho, e sim, somente o nome do arquivo, o arquivo será procurado no mesmo diretório onde o script que está sendo executado tentou incluir o arquivo.

Outra característica muito útil do include e require é que as variáveis, funções e classes que foram declarados no arquivo incluído, estarão disponíveis daquela linha em diante no escopo onde o arquivo foi incluído. Funções e classes serão incluídos no escopo global. Veja um exemplo:

<?php

$name = 'Pedro';
$age = 20;

<?php

include 'vars.php';

echo "Olá $name, sua idade é $age";

// Olá Pedro, sua idade é 20

Outra característica interessante do include e require é que você pode retornar valores do arquivo incluído para uma variável, para isso, use a declaração return, veja um exemplo:

<?php

return [
    'name' => 'Pedro',
    'age' => 20
];

<?php

$person = include 'vars.php';

print_r($person);

// Array ( [name] => Pedro [age] => 20 )

Para mais informações sobre o include e require, veja uma descrição completa no manual do PHP: https://www.php.net/manual/pt_BR/function.include.php

Diferença entre include, include_once, require e require_once

Agora que você já sabe um pouco mais sobre como funciona o include e o require, vamos aprender a diferença de cada um.

É bem simples, include e require funcionam da mesma forma, a diferença é que o require caso não encontre o arquivo que esta sendo incluído, ele emitirá um E_COMPILE_ERROR, fazendo a aplicação parar exatamente naquele ponto, enquanto o include apenas emitirá um alerta E_WARNING, seguindo a aplicação. Então caso você queira que o conteúdo do arquivo que será incluído seja obrigatório, utilize o require ou require_once.

E a diferença do include para o include_once, e require para require_once, é que se for include_once ou require_once, o arquivo que está sendo incluído será incluído apenas uma vez na execução do código, isso evitará possíveis problemas como variáveis sobre escritas ou que funções e classes sejam redeclaradas causando um erro no código.