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. include() produz um Warning enquanto require() produzirá 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 o cancelamento do processamento.

Arquivos a incluir são procurados primeiramente no include_path relativo ao diretório atual de trabalho e depois no include_path relativo ao diretório atual do script. Por exemplo, se seu incluide_path é ., 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/ e somente depois em /www/include/.

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.

Exemplo 16-3. 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.

Exemplo 16-4. 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 Apêndice L 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.

Atenção

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.

Exemplo 16-5. 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 'http://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 'http://www.exemplo.com/arquivo.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include
'arquivo.txt';  // Funciona.
include 'arquivo.php';  // Funciona.

?>
Vaja também: Arquivos Remotos, fopen() e file() para informações relacionadas.

Por serem include() e require() dois construtores de linguagem especiais, você precisa delimitá-los como um bloco de instruções quando utilizados dentro de instruções condicionais.

Exemplo 16-6. include() e instruções condicionais

<?php

// Isto está errado e não funcionará como desejado
if ($condition)
    include
$arquivo;
else
    include
$outro;


// E este está correto
if ($condition) {
    include
$arquivo;
} else {
    include
$outro;
}

?>

Também é possível executar uma instrução return() dentro de um arquivo incluído de maneira a finalizar o processamento daquele arquivo e retornar para o script que o chamou. Também é possível retornar valores de arquivos incluídos. Você pode pegar o valor de retorno de um include como faria com uma função normal.

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.

Exemplo 16-7. 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. Há outras maneiras de "incluir" arquivos dentro de variáveis, com fopen(), file() ou utilizando include() através das Funções de Controle de Output.

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(), readfile(), virtual() e include_path.