<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >include</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REL="HOME" TITLE="Manual do PHP" HREF="index.html"><LINK REL="UP" TITLE="Estruturas de Controle" HREF="language.control-structures.html"><LINK REL="PREVIOUS" TITLE="require" HREF="function.require.html"><LINK REL="NEXT" TITLE="require_once" HREF="function.require-once.html"><META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=UTF-8"></HEAD ><BODY CLASS="sect1" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >Manual do PHP</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="function.require.html" ACCESSKEY="P" >Anterior</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Capítulo 16. Estruturas de Controle</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="function.require-once.html" ACCESSKEY="N" >Próxima</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="sect1" ><H1 CLASS="sect1" ><A NAME="function.include" ><A HREF="function.include.html" ><B CLASS="function" >include()</B ></A ></A ></H1 ><P > A instrução <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A > inclui e avalia o arquivo informado. </P ><P > A documentação a seguir se aplica também a <A HREF="function.require.html" ><B CLASS="function" >require()</B ></A >. Esses dois construtores são idênticos a exceção de como eles manipulam erros. Ambas produzem um <A HREF="phpdevel-errors.html#internal.e-warning" >Warning</A > mas <A HREF="function.require.html" ><B CLASS="function" >require()</B ></A > resultará em um <A HREF="phpdevel-errors.html#internal.e-error" >Fatal Error</A >. Em outras palavras, utilize <A HREF="function.require.html" ><B CLASS="function" >require()</B ></A > se você deseja que um arquivo faltando interrompa o processamento da página. <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A > 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 <A HREF="ini.core.html#ini.include-path" >include_path</A >. 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. </P ><P > 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 é <TT CLASS="literal" >.</TT >, o diretório atual é <TT CLASS="filename" >/www/</TT >, se você incluiu <TT CLASS="filename" >include/a.php</TT > e há um <TT CLASS="filename" >b.php</TT > nesse arquivo, <TT CLASS="filename" >b.php</TT > será procurado primeiro em <TT CLASS="filename" >/www/</TT > e somente depois em <TT CLASS="filename" >/www/include/</TT >. Se o nome do arquivo começa com <TT CLASS="literal" >./</TT > ou <TT CLASS="literal" >../</TT >, ele é procurado apenas no include_path relativo ao diretório de rabalho atual. </P ><P > Quando um arquivo é incluído, seu código entra no <A HREF="language.variables.scope.html" >escopo de variável</A > 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. </P ><P > <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN4995" ></A ><P ><B >Exemplo 16-5. Exemplos de <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A >s simples</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> variaveis.php<br /><font color="#0000BB"><?php<br /><br />$cor </font><font color="#007700">= </font><font color="#DD0000">'verde'</font><font color="#007700">;<br /></font><font color="#0000BB">$fruta </font><font color="#007700">= </font><font color="#DD0000">'maçã'</font><font color="#007700">;<br /><br /></font><font color="#0000BB">?><br /></font><br />teste.php<br /><font color="#0000BB"><?php<br /><br /></font><font color="#007700">echo </font><font color="#DD0000">"Uma $fruta $cor"</font><font color="#007700">; </font><font color="#FF8000">// Uma<br /><br /></font><font color="#007700">include </font><font color="#DD0000">'vars.php'</font><font color="#007700">;<br /><br />echo </font><font color="#DD0000">"Uma $fruta $cor"</font><font color="#007700">; </font><font color="#FF8000">// Uma maçã verde<br /><br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><P > 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. </P ><P > <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN5001" ></A ><P ><B >Exemplo 16-6. Incluindo dentro de funções</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br /><br /></font><font color="#007700">function </font><font color="#0000BB">foo</font><font color="#007700">()<br />{<br /> global </font><font color="#0000BB">$cor</font><font color="#007700">;<br /><br /> include </font><font color="#DD0000">'variaveis.php'</font><font color="#007700">;<br /><br /> echo </font><font color="#DD0000">"Uma $fruta $cor"</font><font color="#007700">;<br />}<br /><br /></font><font color="#FF8000">/* variaveis.php está no escopo de foo(), *<br />.* então $fruta NÃO está disponível fora de *<br />.* seu escopo. $cor estará porque ela foi *<br />.* declarada como global */<br /><br /></font><font color="#0000BB">foo</font><font color="#007700">(); </font><font color="#FF8000">// Uma maçã verde<br /></font><font color="#007700">echo </font><font color="#DD0000">"A $fruta $cor"</font><font color="#007700">; </font><font color="#FF8000">// Uma maçã<br /><br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><P > 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 <A HREF="language.basic-syntax.html#language.basic-syntax.phpmode" >tags válidas de abertura e fechamento</A >. </P ><P > Se "<A HREF="ref.filesystem.html#ini.allow-url-fopen" >URL fopen wrappers</A >" 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 <A HREF="wrappers.html" >Apêndice N</A > 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. </P ><DIV CLASS="warning" ><P ></P ><TABLE CLASS="warning" BORDER="1" WIDTH="100%" ><TR ><TD ALIGN="CENTER" ><B >Atenção</B ></TD ></TR ><TR ><TD ALIGN="LEFT" ><P >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 <A HREF="ref.filesystem.html#ini.allow-url-fopen" >allow_url_fopen</A > estiver ativado. </P ></TD ></TR ></TABLE ></DIV ><P > <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN5013" ></A ><P ><B >Exemplo 16-7. <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A > através de HTTP</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br /><br /></font><font color="#FF8000">/* Este exemplo assume que www.exemplo.com está configurado para interpretar<br /> * arquivos .php mas não .txt. Além, 'Funciona' aqui significa que as<br /> * variáveis $foo e $bar estão disponíveis no arquivo incluído */<br /><br />// Não funciona: arquivos txt não são manipulados em www.example.com como PHP<br /></font><font color="#007700">include </font><font color="#DD0000">'http://www.exemplo.com/arquivo.txt?foo=1&bar=2'</font><font color="#007700">;<br /><br /></font><font color="#FF8000">// Não funciona: procura por um arquivo chamado 'arquivo.php?foo=1&bar=2' no<br />// sistemas de arquivo local.<br /></font><font color="#007700">include </font><font color="#DD0000">'arquivo.php?foo=1&bar=2'</font><font color="#007700">;<br /><br /></font><font color="#FF8000">// Funciona.<br /></font><font color="#007700">include </font><font color="#DD0000">'http://www.exemplo.com/arquivo.php?foo=1&bar=2'</font><font color="#007700">;<br /><br /></font><font color="#0000BB">$foo </font><font color="#007700">= </font><font color="#0000BB">1</font><font color="#007700">;<br /></font><font color="#0000BB">$bar </font><font color="#007700">= </font><font color="#0000BB">2</font><font color="#007700">;<br />include </font><font color="#DD0000">'arquivo.txt'</font><font color="#007700">; </font><font color="#FF8000">// Funciona.<br /></font><font color="#007700">include </font><font color="#DD0000">'arquivo.php'</font><font color="#007700">; </font><font color="#FF8000">// Funciona.<br /><br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><DIV CLASS="warning" ><P ></P ><TABLE CLASS="warning" BORDER="1" WIDTH="100%" ><TR ><TD ALIGN="CENTER" ><B >Security warning</B ></TD ></TR ><TR ><TD ALIGN="LEFT" ><P > 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, <A HREF="function.readfile.html" ><B CLASS="function" >readfile()</B ></A > é 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. </P ></TD ></TR ></TABLE ></DIV ><P > Veja também: <A HREF="features.remote-files.html" >Arquivos Remotos</A >, <A HREF="function.fopen.html" ><B CLASS="function" >fopen()</B ></A > e <A HREF="function.file.html" ><B CLASS="function" >file()</B ></A > para informações relacionadas. </P ><P > Manipulando retornos: é possível executar um comando <A HREF="function.return.html" ><B CLASS="function" >return()</B ></A > 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 <A HREF="language.basic-syntax.html#language.basic-syntax.phpmode" >tags de início e final do PHP válidas</A > (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. </P ><P > Devido a <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A > 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. </P ><P > <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN5031" ></A ><P ><B >Exemplo 16-8. Comparando o valor de retorno de include</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br /></font><font color="#FF8000">// não funciona, avaliado como(('vars.php') == 'OK'), ex, include('')<br /></font><font color="#007700">if (include(</font><font color="#DD0000">'vars.php'</font><font color="#007700">) == </font><font color="#DD0000">'OK'</font><font color="#007700">) {<br /> echo </font><font color="#DD0000">'OK'</font><font color="#007700">;<br />}<br /></font><font color="#FF8000">// funciona<br /></font><font color="#007700">if ((include </font><font color="#DD0000">'vars.php'</font><font color="#007700">) == </font><font color="#DD0000">'OK'</font><font color="#007700">) {<br /> echo </font><font color="#DD0000">'OK'</font><font color="#007700">;<br />}<br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><P > <DIV CLASS="note" ><BLOCKQUOTE CLASS="note" ><P ><B >Nota: </B > 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 <A HREF="function.return.html" ><B CLASS="function" >return()</B ></A > se aplica apenas para a função e não para todo o arquivo. </P ></BLOCKQUOTE ></DIV > </P ><P > <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN5039" ></A ><P ><B >Exemplo 16-9. Instruções <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A > e <A HREF="function.return.html" ><B CLASS="function" >return()</B ></A ></B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> return.php<br /><font color="#0000BB"><?php<br /><br />$var </font><font color="#007700">= </font><font color="#DD0000">'PHP'</font><font color="#007700">;<br /><br />return </font><font color="#0000BB">$var</font><font color="#007700">;<br /><br /></font><font color="#0000BB">?><br /></font><br />noreturn.php<br /><font color="#0000BB"><?php<br /><br />$var </font><font color="#007700">= </font><font color="#DD0000">'PHP'</font><font color="#007700">;<br /><br /></font><font color="#0000BB">?><br /></font><br />testreturns.php<br /><font color="#0000BB"><?php<br /><br />$foo </font><font color="#007700">= include </font><font color="#DD0000">'return.php'</font><font color="#007700">;<br /><br />echo </font><font color="#0000BB">$foo</font><font color="#007700">; </font><font color="#FF8000">// imprime 'PHP'<br /><br /></font><font color="#0000BB">$bar </font><font color="#007700">= include </font><font color="#DD0000">'noreturn.php'</font><font color="#007700">;<br /><br />echo </font><font color="#0000BB">$bar</font><font color="#007700">; </font><font color="#FF8000">// imprime 1<br /><br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><P > <TT CLASS="literal" >$bar</TT > assimila o valor <TT CLASS="literal" >1</TT > porque a inclusão foi realizada com sucesso. Verifique a diferença entre os exemplo. O primeiro utiliza <A HREF="function.return.html" ><B CLASS="function" >return()</B ></A > dentro do arquivo incluído enquanto que o outro não. If the file can't be included, <TT CLASS="constant" ><B >FALSE</B ></TT > is returned and <TT CLASS="literal" >E_WARNING</TT > is issued. </P ><P > Se houverem funções definidas no arquivo incluído, elas podem sr usadas no arquivo principal independentemente se elas foram antes de <A HREF="function.return.html" ><B CLASS="function" >return()</B ></A > 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 <A HREF="function.return.html" ><B CLASS="function" >return()</B ></A >. è remendado usar <A HREF="function.include-once.html" ><B CLASS="function" >include_once()</B ></A > ao invés de conferir se o arquivo já foi incluído e condicionalmente retornar dentro do arquivo incluído. </P ><P > Outra maneira de "incluir" um arquivo PHP em uma variável e capturar a saída usando <A HREF="ref.outcontrol.html" >Funções de Controle de Saída</A > com <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A >. Por exemplo: </P ><P > <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN5058" ></A ><P ><B >Exemplo 16-10. Usando o buffer de saída para incluir um arquivo PHP em uma string</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br />$string </font><font color="#007700">= </font><font color="#0000BB">get_include_contents</font><font color="#007700">(</font><font color="#DD0000">'somefile.php'</font><font color="#007700">);<br /><br />function </font><font color="#0000BB">get_include_contents</font><font color="#007700">(</font><font color="#0000BB">$filename</font><font color="#007700">) {<br /> if (</font><font color="#0000BB">is_file</font><font color="#007700">(</font><font color="#0000BB">$filename</font><font color="#007700">)) {<br /> </font><font color="#0000BB">ob_start</font><font color="#007700">();<br /> include </font><font color="#0000BB">$filename</font><font color="#007700">;<br /> </font><font color="#0000BB">$contents </font><font color="#007700">= </font><font color="#0000BB">ob_get_contents</font><font color="#007700">();<br /> </font><font color="#0000BB">ob_end_clean</font><font color="#007700">();<br /> return </font><font color="#0000BB">$contents</font><font color="#007700">;<br /> }<br /> return </font><font color="#0000BB">false</font><font color="#007700">;<br />}<br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><P > Para poder incluir automaticamente arquivos em um script, veja também as opções de configuração <A HREF="ini.core.html#ini.auto-prepend-file" >auto_prepend_file</A > e <A HREF="ini.core.html#ini.auto-append-file" >auto_append_file</A > no <TT CLASS="filename" >php.ini</TT >. </P ><DIV CLASS="note" ><BLOCKQUOTE CLASS="note" ><P ><B >Nota: </B >Este é um construtor de linguagem e não uma função, por isso não é possível chamá-lo através de <A HREF="functions.variable-functions.html" >funções variáveis</A ></P ></BLOCKQUOTE ></DIV ><P > Veja também: <A HREF="function.require.html" ><B CLASS="function" >require()</B ></A >, <A HREF="function.require-once.html" ><B CLASS="function" >require_once()</B ></A >, <A HREF="function.include-once.html" ><B CLASS="function" >include_once()</B ></A >, <A HREF="function.get-included-files.html" ><B CLASS="function" >get_included_files()</B ></A >, <A HREF="function.readfile.html" ><B CLASS="function" >readfile()</B ></A >, <A HREF="function.virtual.html" ><B CLASS="function" >virtual()</B ></A > e <A HREF="ini.core.html#ini.include-path" >include_path</A >. </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="function.require.html" ACCESSKEY="P" >Anterior</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Principal</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="function.require-once.html" ACCESSKEY="N" >Próxima</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="function.require.html" ><B CLASS="function" >require()</B ></A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="language.control-structures.html" ACCESSKEY="U" >Acima</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="function.require-once.html" ><B CLASS="function" >require_once()</B ></A ></TD ></TR ></TABLE ></DIV ></BODY ></HTML >