include()
A instrução include() inclui e avalia o arquivo informado.
A documentação a seguir se aplica também a require(). Esses dois construtores são idênticos a exceção de como eles manipulam erros. Ambas produzem um Warning mas require() resultará em um Fatal Error. Em outras palavras, utilize require() se você deseja que um arquivo faltando interrompa o processamento da página. include() não se comporta da mesma maneira, permitindo que o script continue nessas situações. Em todo caso, vale a pena confirmar a configuração da diretiva include_path. Esteja avisado que um erro de interpretação no arquivo incluído não causa a parada do processamento em versões do PHP anteriores a PHP 4.3.5. A partir desta versão, causa.
Arquivos a incluir são procurados primeiramente no include_path relativo ao diretório atual de trabalho, e então no diretório atual do script. Por exemplo, se seu include_path é libraries, o diretório atual é /www/, se você incluiu include/a.php e há um b.php nesse arquivo, b.php será procurado primeiro em /www/libraries/ e somente depois em /www/include/.0 Se o nome do arquivo começa com ./ ou ../, ele é procurado apenas no diretório atual.
Quando um arquivo é incluído, seu código entra no escopo de variável da linha onde a inclusão ocorre. Qualquer variável disponível da linha onde a chamada da inclusão ocorre estará disponível para o arquivo incluído, daquele ponto em diante. Entretanto, todas as funções e classes definidas no arquivo incluído tem um escopo global.
Example#1 Exemplos de include()s simples
variaveis.php
<?php
$cor = 'verde';
$fruta = 'maçã';
?>
teste.php
<?php
echo "Uma $fruta $cor"; // Uma
include 'vars.php';
echo "Uma $fruta $cor"; // Uma maçã verde
?>
Se o include ocorre dentro de uma função do arquivo principal, então todo o código incluído será executado como se ele tivesse sido definido dentro daquela função. Da mesma forma, ele seguirá o escopo de variáveis da função. Uma exceção para esta regra são as constantes mágicas que são avaliadas pelo parser antes dos includes ocorrerem.
Example#2 Incluindo dentro de funções
<?php
function foo()
{
global $cor;
include 'variaveis.php';
echo "Uma $fruta $cor";
}
/* variaveis.php está no escopo de foo(), *
.* então $fruta NÃO está disponível fora de *
.* seu escopo. $cor estará porque ela foi *
.* declarada como global */
foo(); // Uma maçã verde
echo "A $fruta $cor"; // Uma maçã
?>
Quando um arquivo é incluído, o interpretador sai do modo PHP e entra no modo HTML (no começo do arquivo incluído), e alterna novamente no seu fim. Por isso, qualquer código dentro do arquivo incluído que precisa ser executado como código PHP tem de ser delimitado por tags válidas de abertura e fechamento.
Se "URL fopen wrappers" estão ativas no PHP (normalmente na configuração default), você pode especificar um arquivo utilizando uma URL (via HTTP ou qualquer outro wrapper suportado --- veja List of Supported Protocols/Wrappers para uma lista dos protocolos) em vez de uma caminho local. Se o servidor apontado interpreta o arquivo informado como código PHP, variáveis podem ser passadas ao arquivo incluído na URL de requisição como num HTTP GET. Isto não é necessariamente a mesma coisa que incluir o arquivo e compartilhar o escopo de variável do arquivo principal: o script será executado no servidor remoto e apenas seu resultado será incluído no script local.
A versões Windows do PHP anteriores ao PHP 4.3.0 não suportam acesso a arquivos remotos através desta função, mesmo se allow_url_fopen estiver ativado.
Example#3 include() através de HTTP
<?php
/* Este exemplo assume que www.exemplo.com está configurado para interpretar
* arquivos .php mas não .txt. Além, 'Funciona' aqui significa que as
* variáveis $foo e $bar estão disponíveis no arquivo incluído */
// Não funciona: arquivos txt não são manipulados em www.example.com como PHP
include 'https://www.exemplo.com/arquivo.txt?foo=1&bar=2';
// Não funciona: procura por um arquivo chamado 'arquivo.php?foo=1&bar=2' no
// sistemas de arquivo local.
include 'arquivo.php?foo=1&bar=2';
// Funciona.
include 'https://www.exemplo.com/arquivo.php?foo=1&bar=2';
$foo = 1;
$bar = 2;
include 'arquivo.txt'; // Funciona.
include 'arquivo.php'; // Funciona.
?>
Security warning
O arquivo remoto pode ser processado pelo servidor remoto (dependendo da extensão do arquivo e do fato de o servidor remoto executar o PHP ou não) mas ainda tem que produzir um script PHP válido porque ele será processado pelo servidor local. Se o arquivo do servidor remoto deve ser processado lá e apenas exibido, a função, readfile() é muito melhor para ser usada. Entretanto, um cuidado especial deve ser tomado para se assegurar que o script remoto irá produzir um código válido e desejado.
Veja também: Arquivos Remotos, fopen() e file() para informações relacionadas.
Manipulando retornos: é possível executar um comando return() dentro de um arquivo incluído para terminar o processamento naquele arquivo e retornar para o script que o chamou. Também é possível retornar valores dos arquivos incluídos. Você pode usar o valoe de uma chamada include como você faria com uma função normal. isto não é, entretanto, possível ao incluir arquivos remotos a menos que a saída do arquivo remoto tenha tags de início e final do PHP válidas (como qualquer arquivo local). Você pode declarar as variáveis necessárias dentro destas tags e elas serão introduzidas em qualquer ponto que o arquivo seja incluído.
Devido a include() ser um construtor especial da linguagem, parentesis não são necessários ao redor do seu argumento. Tenha cuidado ao comparar o valor de retorno.
Example#4 Comparando o valor de retorno de include
<?php
// não funciona, avaliado como(('vars.php') == 'OK'), ex, include('')
if (include('vars.php') == 'OK') {
echo 'OK';
}
// funciona
if ((include 'vars.php') == 'OK') {
echo 'OK';
}
?>
Nota: No PHP 3, o return não pode aparecer dento de um bloco a não ser que ele seja um bloco de função, e nesse caso return() se aplica apenas para a função e não para todo o arquivo.
Example#5 Instruções include() e 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 assimila o valor 1 porque a inclusão foi realizada com sucesso. Verifique a diferença entre os exemplo. O primeiro utiliza return() dentro do arquivo incluído enquanto que o outro não. If the file can't be included, FALSE is returned and E_WARNING is issued.
Se houverem funções definidas no arquivo incluído, elas podem sr usadas no arquivo principal independentemente se elas foram antes de return() ou depois. Se o arquivo for incluído duas vezes, o PHP 5 causa um erro fatal por as funções já foram declaradas, em quanto o PHP 4 não reclama sobre funções definidas após return(). è remendado usar include_once() ao invés de conferir se o arquivo já foi incluído e condicionalmente retornar dentro do arquivo incluído.
Outra maneira de "incluir" um arquivo PHP em uma variável e capturar a saída usando Funções de Controle de Saída com include(). Por exemplo:
Example#6 Usando o 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;
$contents = ob_get_contents();
ob_end_clean();
return $contents;
}
return false;
}
?>
Para poder incluir automaticamente arquivos em um script, veja também as opções de configuração auto_prepend_file e auto_append_file 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.