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 .

Quando um arquivo é incluído , seu código entra no escopo de variável 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 12-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 12-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 I 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 não suportam acesso a arquivos remotos através desta função , mesmo se allow_url_fopen estiver ativado .

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

Veja também : require( ) , require_once( ) , include_once( ) , readfile( ) , virtual( ) e include_path .