php include,PHP: include - Manual

include

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

La sentencia include incluye y evalúa

el archivo especificado.

La siguiente documentación también se aplica a

Los archivos son incluidos con base en la ruta de acceso dada o, si ninguna es dada, el

include_path especificado. Si el archivo

no se encuentra en el include_path,

include finalmente verificará en el propio directorio del script

que hace el llamado y en el directorio de trabajo actual, antes de fallar. El

constructor include emitirá una

advertencia si

no puede encontrar un archivo, éste es un comportamiento diferente al de

error fatal..

Si una ruta es definida — ya sea absoluta (comenzando con una letra de unidad

o \ en Windows o / en sistemas Unix/Linux) o relativa al

directorio actual (comenzando con . o

..) — el

include_path será ignorado

por completo. Por ejemplo, si un nombre de archivo comienza con ../,

el interprete buscará en el directorio padre para encontrar el archivo solicitado.

Para más información sobre como PHP maneja la inclusión de archivos y la ruta de accesos para incluir,

ver la documentación de include_path.

Cuando se incluye un archivo, el código que contiene hereda el

ámbito de las variables de la

línea en la cual ocurre la inclusión. Cualquier variable disponible en esa línea

del archivo que hace el llamado, estará disponible en el archivo llamado, desde ese

punto en adelante.

Sin embargo, todas las funciones y clases definidas en el archivo incluido tienen el

ámbito global.

Ejemplo #1 Ejemplo básico de include

vars.php

$color='verde';$fruta='manzana';?>

test.php

echo"Una$fruta$color";// Una manzana verde?>

Si la inclusión ocurre al interior de una función dentro del archivo que hace el llamado,

entonces todo el código contenido en el archivo llamado se comportará como

si hubiera sido definida dentro de esa función. Por lo tanto, seguirá

el ámbito de las variables de esa función.

Una excepción a esta regla son las constantes mágicas las cuales son

evaluadas por el intérprete antes que ocurra la inclusión.

Ejemplo #2 Incluyendo dentro de funciones

{

global$color;

include'vars.php';

echo"Una$fruta$color";

}/* vars.php está en el ámbito de foo() así que *

* $fruta NO está disponible por fuera de éste  *

* ámbito. $color sí está porque fue declarado *

* como global.                                 */foo();// Una manzana verdeecho"Una$fruta$color";// Una verde?>

Cuando un archivo es incluido, el intérprete abandona el modo PHP e

ingresa al modo HTML al comienzo del archivo objetivo y se reanuda

de nuevo al final. Por esta razón, cualquier código al interior del archivo

objetivo que deba ser ejecutado como código PHP, tendrá que ser encerrado dentro de

etiquetas válidas de

comienzo y terminación de PHP.

Si las "envolturas URL include"

están activadas en PHP,

se puede especificar el archivo a ser incluido usando una URL (vía HTTP u

otra envoltura soportada - ver Protocolos y Envolturas soportados para una lista

de protocolos) en lugar de una ruta de acceso local. Si el servidor objetivo interpreta

el archivo objetivo como código PHP, las variables se pueden pasar al archivo

incluido usando una string de petición como la usada con HTTP GET. Esto

no es, en estricto rigor, lo mismo que haber incluido el archivo y que

haya heredado el ámbito de variables del archivo padre; el script realmente

está siendo ejecutado en el servidor remoto y el resultado entonces se

incluye dentro del script local.

Ejemplo #3 include por medio de HTTP

* .php y no archivos .txt. Además, aquí 'Funciona' quiere decir que las variables

* $foo y $bar están disponibles dentro del archivo incluido. */

// No funciona; file.txt no puede ser manejado por www.example.com como PHPinclude'http://www.example.com/file.txt?foo=1&bar=2';// No funciona; busca por un archivo llamado 'file.php?foo=1&bar=2' en el

// sistema de archivos local.include'file.php?foo=1&bar=2';// Si funciona.include'http://www.example.com/file.php?foo=1&bar=2';$foo=1;$bar=2;

include'file.txt';// Funciona.include'file.php';// Funciona.?>

Advertencia

Advertencia de seguridad

El archivo remoto puede ser procesado en el servidor remoto (dependiendo de la extensión

del archivo y del hecho de si el servidor remoto corre PHP o no) pero aun así

tiene que producir un script PHP válido, porque será procesado en el

servidor local. Si el archivo desde el servidor remoto debe ser procesado

allá y entregar la salida solamente,

Ver también Archivos remotos,

Manejando retornos: include devuelve

FALSE en caso de falla y eleva una advertencia. Inclusiones

exitosas, a menos que sea reemplazado por el archivo incluido, devolverá

1. Es posible ejecutar una sentencia etiquetas válidas de

inicio y terminación de PHP (igual que con cualquier archivo local). Se pueden declarar las

variables necesarias dentro de esas etiquetas y serán introducidas en

cualquiera sea el punto del archivo en el cual fue incluido.

Debido a que include es un constructor especial del lenguaje,

los paréntesis no son necesarios en torno a su argumento. Se debe tener cuidado cuando se compara

el valor de retorno.

Ejemplo #4 Comparando el valor de retorno de include

echo'OK';

}// sí funcionaif ((include'vars.php') ==TRUE) {

echo'OK';

}?>

Ejemplo #5 include y la sentencia

return.php

$var='PHP';

return$var;?>

noreturn.php

$var='PHP';?>

testreturns.php

$foo= include'return.php';

echo$foo;// muestra 'PHP'$bar= include'noreturn.php';

echo$bar;// muestra 1?>

$bar tiene el valor 1 debido a que el include

fue exitoso. Nótese la diferencia entre los ejemplos anteriores. El primero usa

false y

se emite un E_WARNING.

Si hay funciones definidas en el archivo incluido, se pueden utilizar en el

archivo principal independientemente que hayan

Otra forma de "incluir" un archivo PHP en una variable es capturar la

salida mediante el uso de Funciones de control de

salida con include. Por ejemplo:

Ejemplo #6 Usando buffering de salida para incluir un archivo PHP dentro de una cadena

$string=get_include_contents('somefile.php');

functionget_include_contents($filename) {

if (is_file($filename)) {ob_start();

include$filename;

returnob_get_clean();

}

returnfalse;

}?>

Con el fin de incluir archivos de forma automática dentro de scripts, véase también las

opciones de configuración

auto_prepend_file and

auto_append_file en php.ini.

Nota: Puesto que esto es

una construcción del lenguaje y no una función, no puede ser llamada usando

funciones variables.