Apostilas e Tutoriais

PHP Manual

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.

Exemplo #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.

Exemplo #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.

Aviso

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 #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 '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.

?>

Aviso

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.

Exemplo #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';
}
?>

Exemplo #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:

Exemplo #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.


PHP Manual