(PHP 4, PHP 5, PHP 7, PHP 8)
A expressão include inclui e avalia o arquivo informado.
A documentação a seguir também se aplica a declaração require.
Os arquivos são incluídos baseando-se no caminho do arquivo informado ou, se não informado, o include_path especificado. Se o arquivo não for encontrado no include_path, include checará no diretório do script que o executa e no diretório de trabalho corrente, antes de falhar. O construtor include emitirá um E_WARNING se não localizar o arquivo; possui um comportamento diferente do require, que emitirá um E_ERROR.
Note que ambas include e require emitem E_WARNINGs adicionais, se o arquivo não puder ser acessado, antes de emitir o E_WARNING ou E_ERROR final, respectivamente.
Se um caminho for definido — seja absoluto (iniciando com a letra do drive ou \ no Windows, ou / no Unix/Linux ), ou relativo ao diretório atual (começando com . ou ..) — o include_path será completamente ignorado. Por exemplo, se o nome do arquivo iniciar com ../, o interpretador irá procurar pelo arquivo no diretório pai.
Para mais informações de como o PHP trabalha ao incluir arquivos e o caminho de inclusão, veja a documentação do include_path.
Quando um arquivo é incluído, o código herda o escopo de variáveis da da linha que a inclusão ocorrer. Qualquer variável disponível no arquivo que incluiu estará disponível no arquivo incluído, daquela linha em diante. Entretanto, todas as funções e classes definidas no arquivo incluído estarão no escopo global.
Exemplo #1 Exemplo básico do construtor include
vars.php
<?php
$color = 'green';
$fruit = 'apple';
?>
test.php
<?php
echo "A $color$fruit"; // A
include 'vars.php';
echo "A $color$fruit"; // A green apple
?>Se a inclusão ocorrer dentro de uma função todo o código contido no arquivo incluído irá se comportar como se tivesse sido definido dentro da função. Portanto seguirá o escopo de variáveis da função. Uma exceção para essa regra são as constantes mágicas que são interpretadas antes da inclusão ocorrer.
Exemplo #2 Inclusão em funções
<?php
function foo()
{
global $color;
include 'vars.php';
echo "A $color$fruit";
}
foo(); // A green apple
echo "A $color$fruit"; // A green
?>Quando um arquivo é incluído, o interpretador sai do modo PHP e entra no modo HTML no começo do arquivo incluído, e volta novamente no final. Por esta razão, qualquer código dentro do arquivo incluído que necessite ser executado como PHP deve estar entre tags válidas de início e fim do PHP.
Se os "empacotadores de inclusão de URL" estiverem habilitados no PHP, pode-se definir um arquivo a ser incluído usando uma URL (via HTTP ou outro protocolo suportado - veja Protocolos e Wrappers suportados para uma lista de protocolos) ao invés de um caminho local. Se o servidor de destino interpretar o arquivo incluído como PHP, variáveis podem ser passadas para o arquivo incluído usando uma URL de requisição com HTTP GET. Isso não significa a mesma coisa que incluir e compartilhar o escopo de variáveis com o arquivo incluído; O script é executado no servidor remoto e o resultado incluído no script local.
Exemplo #3 Usando include via HTTP
<?php
// Não vai funcionar; arquivo.txt não foi tratado por www.exemplo.com.br como PHP
include 'http://www.exemplo.com.br/arquivo.txt?foo=1&bar=2';
// Não vai funcionar; procura por um arquivo chamado 'arquivo.php?foo=1&bar=2' no
// sistema de arquivos local.
include 'arquivo.php?foo=1&bar=2';
// Funciona.
include 'http://www.exemplo.com.br/arquivo.php?foo=1&bar=2';
?>O arquivo remoto pode ser processado pelo servidor remoto (dependendo da extensão do arquivo e se o servidor remoto executa, ou não,arquivos PHP), mas ainda precisa produzir um código PHP válido pois será processado pelo servidor local. Se o arquivo do servidor remoto deve ser processado como um texto simples, a função readfile() é uma opção muito melhor a ser usada. Caso contrário, deve-se ter um cuidado especial para garantir que o servidor remoto produza um código PHP válido.
Veja também Arquivos Remotos, fopen() e file() para informações relacionadas.
Manipulando Retornos: o include retorna FALSE ao falhar e emite um aviso. Inclusões bem sucedidas, ao menos que seja sobrescritas pelo arquivo incluído, retornam 1. É possível utilizar a declaração return dentro do arquivo incluído para finalizar o processamento e retornar para o arquivo que o incluiu. Além disso, é possível retornar valor a partir do arquivo incluído. Pode-se usar o valor do arquivo incluído como em uma função normal. Isso não é, entretanto, possível quando incluímos arquivos remotos a menos que a saída do arquivo remoto tenha tags válidas de início e fim do PHP (como em um arquivo local). Pode-se declarar as variáveis necessárias dentro dessas tags e estarão disponíveis em qualquer ponto do arquivo que o incluiu.
Pelo fato do include ser um construtor especial da linguagem, parênteses não são necessários ao redor do argumento. Tome cuidado ao comparar valores de retorno.
Exemplo #4 Comparando valores de retorno do include
<?php
// não vai funcionar, avaliado como include(('vars.php') == TRUE), isto é: include('1')
if (include('vars.php') == TRUE) {
echo 'OK';
}
// funciona
if ((include 'vars.php') == TRUE) {
echo 'OK';
}
?>Exemplo #5 include e a instrução return
return.php
<?php
$var = 'PHP';
return $var;
?>
noreturn.php
<?php
$var = 'PHP';
?>
testreturns.php
<?php
$foo = include 'return.php';
echo $foo; // imprime 'PHP'
$bar = include 'noreturn.php';
echo $bar; // imprime 1
?>$bar tem o valor 1 porque a inclusão foi bem sucedida. Note a diferença entre os dois exemplos. O primeiro usa o return, enquanto o outro não. Se o arquivo não puder ser incluído, false é retornado e um E_WARNING emitido.
Se funções forem definidas no arquivo incluído, elas podem ser utilizadas no arquivo principal independente se estão antes ou depois do return. Se o arquivo for incluído duas vezes, o PHP emitirá um erro fatal, pois as funções já foram declaradas. É recomendado usar o include_once ao invés de verificar se o arquivo já foi incluído manualmente dentro do arquivo incluído.
Outra forma de "incluir" um arquivo PHP em uma variável é capturar a saída usando as Funções de Controle de Saída com o include. Por exemplo:
Exemplo #6 Usando buffer de saída para incluir um arquivo PHP em uma string
<?php
$string = get_include_contents('somefile.php');
function get_include_contents($filename) {
if (is_file($filename)) {
ob_start();
include $filename;
return ob_get_clean();
}
return false;
}
?>Para automatizar a inclusão de arquivos nos scripts, veja também as configurações auto_prepend_file e auto_append_file contidas no php.ini.
Nota: Como esta é uma construção da linguagem e não uma função, ela não pode ser chamada usando funções variáveis ou argumentos nomeados.
Veja também require, require_once, include_once, get_included_files(), readfile(), virtual(), e include_path.