include()

La sentencia include() incluye y evalúa el archivo especificado.

Esta documentación también se aplica a la función require(). require() y include() son idénticas en todos los aspectos excepto en el modo de actuar ante un error. include() produce un Warning mientras que require() produce un Error Fatal. En otras palabras, no dude en utilizar require() si quiere que un fichero no encontrado cuelgue el procesamiento de la página. include() no se comporta de esta manera, el script seguirá funcionando de todas maneras. Asegurarse que include_path este configurado bien.

Cuando un fichero es incluido, el código que contiene hereda la variable scope de la linea en donde el include ocurre. Cualquier variable disponible en esa linea en el fichero desde donde se hace la inclusión estará disponible en el fichero incluido a partir de ese momento.

Ejemplo 16-3. Ejemplo básico de la funcióninclude()


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

?>

Si la inclusión ocurre dentro de una función en el fichero donde se incluye, todo el código contenido en el fichero incluido se comportará como si hubiese sido definido dentro de esta función.

Ejemplo 16-4. Incluyendo desde funciones


<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php is in the scope of foo() so     *
 * $fruit is NOT available outside of this  *
 * scope.  $color is because we declared it *
 * as global.                               */

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

?>

Cuando un fichero es incluido, el intérprete sale del modo PHP y entra en modo HTML al principio del archivo referenciado, y vuelve de nuevo al modo PHP al final. Por esta razón, cualquier código dentro del archivo referenciado que debiera ser ejecutado como código PHP debe ser encerrado dentro de etiquetas válidas de comienzo y fin de PHP.

Si "URL fopen wrappers" esta activada en PHP (como está en la configuración inicial), se puede especificar el fichero que se va a incluir usando una URL (via HTTP u otro mecanismo soportado, consultar Apéndice M) en vez de un fichero local. Si el servidor destino interpreta el fichero destino como código PHP, variables pueden ser mandadas al fichero incluido usando una cadena URL de petición, tal como se hace con HTTP GET. Esto no es lo mismo que incluir un fichero y que este fichero herede las variables del fichero padre; el script es ejecutado en el servidor remoto y el resultado es incluido en en script local.

Aviso

Versiones de PHP para Windows anteriores a 4.3.0, no soportan el acceso remoto a archivos para esta función, no funcionará ni activando siquiera allow_url_fopen.

Ejemplo 16-5. include() a traves de HTTP


<?php

/* This example assumes that www.example.com is configured to parse .php 
 * files and not .txt files. Also, 'Works' here means that the variables 
 * $foo and $bar are available within the included file.*/

// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';

// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include 'file.txt';  // Works.
include 'file.php';  // Works.

?>

Ver también Ficheros remotos, fopen() y file() para obtener información adicional.

Ya que include() y require() son contructores especiales del lenguaje, se deben de incluir dentro del bloque de una sentencia, si están dentro de un bloque condicional.

Ejemplo 16-6. include() y bloques condicionales


<?php

// This is WRONG and will not work as desired.
if ($condition)
    include $file;
else
    include $other;


// This is CORRECT.
if ($condition) {
    include $file;
} else {
    include $other;
}

?>

Es posible ejecutar una sentencia return dentro de un archivo incluido para terminar el procesado de ese archivo y volver al archivo de comandos que lo llamó. Tambien es posible retornar valores de ficheros incluidos. Se puede coger el valor de la llamada "include" como se haría con una función normal.

Nota: En PHP3, return no puede aparecer dentro de un bloque a menos que sea un bloque de función, en el cual return se aplica a esa función y no al archivo completo.

Ejemplo 16-7. include() y return()


return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 1

?>

$bar es igual a 1 porque la inclusión salio bien. Notar la diferencia entre los dos ejemplos anteriores. el primero usa return() dentro del fichero incluido y el segundo no. Otras maneras de incluir ficheros en variables es con fopen(), file() ó usando include()con Funciones de control de salida.

Nota: Puesto que esto es una construcción del lenguaje y no una función, no puede ser llamado usando funciones variables

Ver también require(), require_once(), include_once(), readfile(), virtual(), y include_path.