## include

(PHP 4, PHP 5, PHP 7, PHP 8)

A expressão `include` inclui e avalia o arquivo informado.

A documentação a seguir também se aplica à declaração require.

Os arquivos são incluídos baseando-se no caminho do arquivo informado ou, se não informado, o include_path especificado. Se o arquivo não for encontrado no include_path, `include` verificará no diretório do script que o executa e no diretório de trabalho corrente antes de falhar. O construtor `include` emitirá um `E_WARNING` se não localizar o arquivo; possui um comportamento diferente do require, que emitirá um `E_ERROR`.

Note que ambas `include` e `require` emitem `E_WARNING`s adicionais, se o arquivo não puder ser acessado, antes de emitir o `E_WARNING` ou `E_ERROR` final, respectivamente.

Se um caminho for definido — seja absoluto (iniciando com a letra da unidade ou `\` no Windows, ou `/` no Unix/Linux ), ou relativo ao diretório atual (começando com `.` ou `..`) — o include_path será completamente ignorado. Por exemplo, se o nome do arquivo iniciar com `../`, o interpretador irá procurar pelo arquivo no diretório pai.

Para mais informações de como o PHP trabalha ao incluir arquivos e o caminho de inclusão, veja a documentação de include_path.

Quando um arquivo é incluído, o código herda o escopo de variáveis da da linha que a inclusão ocorrer. Qualquer variável disponível no arquivo que o incluiu estará disponível no arquivo incluído, daquela linha em diante. Entretanto, todas as funções e classes definidas no arquivo incluído estarão no escopo global.

Exemplo #1 Exemplo básico do construtor `include`

    vars.php
    <?php

    $color = 'green';
    $fruit = 'apple';

    ?>

    test.php
    <?php

    echo "A $color $fruit"; // A

    include 'vars.php';

    echo "A $color $fruit"; // A green apple

    ?>

Se a inclusão ocorrer dentro de uma função, todo o código contido no arquivo incluído irá se comportar como se tivesse sido definido dentro da função. Portanto seguirá o escopo de variáveis da função. Uma exceção para essa regra são as constantes mágicas que são interpretadas antes da inclusão ocorrer.

Exemplo #2 Inclusão em funções

    <?php

    function foo()
    {
        global $color;

        include 'vars.php';

        echo "A $color $fruit";
    }

    /* vars.php está no escopo de foo() por isso *
    * $fruit NÃO está disponível fora deste      *
    * escopo. $color está, porque foi declarada  *
    * como global.                               */

    foo();                    // A green apple
    echo "A $color $fruit";   // A green

    ?>

Quando um arquivo é incluído, o interpretador sai do modo PHP e entra no modo HTML no começo do arquivo incluído, e volta novamente no final. Por esta razão, qualquer código dentro do arquivo incluído que necessite ser executado como PHP deve estar entre tags válidas de início e fim do PHP.

Se os "empacotadores de inclusão de URL" estiverem habilitados no PHP, pode-se definir um arquivo a ser incluído usando uma URL (via HTTP ou outro protocolo suportado - veja Protocolos e empacotadores suportados para uma lista de protocolos) ao invés de um caminho local. Se o servidor de destino interpretar o arquivo incluído como PHP, variáveis podem ser passadas para o arquivo incluído usando uma URL de requisição com HTTP GET. Isso não significa a mesma coisa que incluir e compartilhar o escopo de variáveis com o arquivo incluído; o script é executado no servidor remoto e o resultado é incluído no script local.

Exemplo #3 Usando `include` via HTTP

    <?php

    /* Este exemplo assume que www.exemplo.com.br está configurado para processar
    * arquivos .php e não arquivos .txt. Além disso, 'Funciona' aqui significa
    * que as variáveis $foo e $bar estão disponíveis dentro do arquivo incluído. */

    // Não vai funcionar; arquivo.txt não foi tratado por www.exemplo.com.br como PHP
    include 'http://www.exemplo.com.br/arquivo.txt?foo=1&bar=2';

    // Não vai funcionar; procura por um arquivo chamado 'arquivo.php?foo=1&bar=2' no
    // sistema de arquivos local.
    include 'arquivo.php?foo=1&bar=2';

    // Funciona.
    include 'http://www.exemplo.com.br/arquivo.php?foo=1&bar=2';
    ?>

Aviso

# Avisos de Segurança

O arquivo remoto pode ser processado pelo servidor remoto (dependendo da extensão do arquivo e se o servidor remoto executa, ou não,arquivos PHP), mas ainda precisa produzir um código PHP válido pois será processado pelo servidor local. Se o arquivo do servidor remoto deve ser processado como um texto simples, a função readfile() é uma opção muito melhor a ser usada. Caso contrário, deve-se ter um cuidado especial para garantir que o servidor remoto produza um código PHP válido.

Veja também Arquivos Remotos, fopen() e file() para informações relacionadas.

Manipulando retornos: `include` retorna `FALSE` ao falhar e emite um aviso. Inclusões bem sucedidas, ao menos que seja sobrescritas pelo arquivo incluído, retornam `1`. É possível utilizar a declaração return dentro do arquivo incluído para finalizar o processamento e retornar para o arquivo que o incluiu. Além disso, é possível retornar valor a partir do arquivo incluído. Pode-se usar o valor do arquivo incluído como em uma função normal. Isso não é, entretanto, possível quando incluímos arquivos remotos a menos que a saída do arquivo remoto tenha tags válidas de início e fim do PHP (como em um arquivo local). Pode-se declarar as variáveis necessárias dentro dessas tags e estarão disponíveis em qualquer ponto do arquivo que o incluiu.

Pelo fato do `include` ser um construtor especial da linguagem, parênteses não são necessários ao redor do argumento. Tome cuidado ao comparar valores de retorno.

Exemplo #4 Comparando valores de retorno do include

    <?php
    // não vai funcionar, avaliado como include(('vars.php') == TRUE), isto é: include('1')
    if (include('vars.php') == TRUE) {
        echo 'OK';
    }

    // funciona
    if ((include 'vars.php') == TRUE) {
        echo 'OK';
    }
    ?>

Exemplo #5 `include` e a instrução 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` tem o valor `1` porque a inclusão foi bem sucedida. Note a diferença entre os dois exemplos. O primeiro usa return, enquanto o outro não. Se o arquivo não puder ser incluído, `false` é retornado e um `E_WARNING` emitido.

Se funções forem definidas no arquivo incluído, elas podem ser utilizadas no arquivo principal independente se estão antes ou depois do return. Se o arquivo for incluído duas vezes, o PHP emitirá um erro fatal, pois as funções já foram declaradas. É recomendado usar o include_once ao invés de verificar se o arquivo já foi incluído manualmente dentro do arquivo incluído.

Outra forma de "incluir" um arquivo PHP em uma variável é capturar a saída usando as Funções de Controle de Saída com o `include`. Por exemplo:

Exemplo #6 Usando 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;
            return ob_get_clean();
        }
        return false;
    }

    ?>

Para automatizar a inclusão de arquivos nos scripts, veja também as configurações auto_prepend_file e auto_append_file contidas no php.ini.

> Nota: Como esta é uma construção da linguagem e não uma função, ela não pode ser chamada usando funções variáveis ou argumentos nomeados.

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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open