(PHP 4, PHP 5, PHP 7)
A declaraçã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, a declaração 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 aviso se não localizar o arquivo; possui um comportamento diferente do construtor require, que emitirá um erro fatal.
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";
}
/* vars.php is in the scope of foo() so *
* $fruit is NOT available outside of this *
* scope. $color is because we declared it *
* as global. */
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
/* This example assumes that www.example.com is configured to parse .php
* files and not .txt files. Also, 'Works' here means that the variables
* $foo and $bar are available within the included file. */
// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';
// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';
// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';
$foo = 1;
$bar = 2;
include 'file.txt'; // Works.
include 'file.php'; // Works.
?>
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
// won't work, evaluated as include(('vars.php') == TRUE), i.e. include('')
if (include('vars.php') == TRUE) {
echo 'OK';
}
// works
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; // prints 'PHP'
$bar = include 'noreturn.php';
echo $bar; // prints 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 mesmo arquivo for incluído duas vezes, o PHP 5 emitirá um erro fatal, pois as funções já foram declaradas, enquanto que no PHP 4 não se queixa de funções definidas depois do return. É 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: Este é um construtor de linguagem e não uma função, por isso não é possível chamá-lo através de funções variáveis
Veja também require, require_once, include_once, get_included_files(), readfile(), virtual(), e include_path.