JTagua

Inicio » PHP » Estructuras de control » include / include_once » Tutorial PHP(37): include, include_once

Tutorial PHP(37): include, include_once


include

(PHP 4, PHP 5)

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

La siguiente documentación también se aplica a require.

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 require, el cual emitirá un 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
<?php
$color&nbsp;=&nbsp;'verde';
$fruta&nbsp;=&nbsp;'manzana';
?>

test.php
<?php
echo&nbsp;"Una&nbsp;$fruta&nbsp;$color";&nbsp;//&nbsp;Una
include&nbsp;'vars.php';
echo&nbsp;"Una&nbsp;$fruta&nbsp;$color";&nbsp;//&nbsp;Una&nbsp;manzana&nbsp;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

<?php
function&nbsp;foo()
{
global&nbsp;$color;

include&nbsp;'vars.php';

echo&nbsp;"Una&nbsp;$fruta&nbsp;$color";
}

/*&nbsp;vars.php&nbsp;está&nbsp;en&nbsp;el&nbsp;ámbito&nbsp;de&nbsp;foo()&nbsp;así&nbsp;que&nbsp;*
*&nbsp;$fruta&nbsp;NO&nbsp;está&nbsp;disponible&nbsp;por&nbsp;fuera&nbsp;de&nbsp;éste&nbsp;&nbsp;*
*&nbsp;ámbito.&nbsp;$color&nbsp;sí&nbsp;está&nbsp;porque&nbsp;fue&nbsp;declarado&nbsp;*
*&nbsp;como&nbsp;global.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/

foo();&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;Una&nbsp;manzana&nbsp;verde
echo&nbsp;"Una&nbsp;$fruta&nbsp;$color";&nbsp;&nbsp;&nbsp;//&nbsp;Una&nbsp;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.

AdvertenciaVersiones 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 #3 include por medio de HTTP

<?php
/*&nbsp;Este&nbsp;ejemplo&nbsp;asume&nbsp;que&nbsp;www.example.com&nbsp;está&nbsp;configurado&nbsp;para&nbsp;interpretar&nbsp;archivos
*&nbsp;.php&nbsp;y&nbsp;no&nbsp;archivos&nbsp;.txt.&nbsp;Además,&nbsp;aquí&nbsp;'Funciona'&nbsp;quiere&nbsp;decir&nbsp;que&nbsp;las&nbsp;variables
*&nbsp;$foo&nbsp;y&nbsp;$bar&nbsp;están&nbsp;disponibles&nbsp;dentro&nbsp;del&nbsp;archivo&nbsp;incluido.&nbsp;*/

//&nbsp;No&nbsp;funciona;&nbsp;file.txt&nbsp;no&nbsp;puede&nbsp;ser&nbsp;manejado&nbsp;por&nbsp;www.example.com&nbsp;como&nbsp;PHP
include&nbsp;'http://www.example.com/file.txt?foo=1&bar=2';

//&nbsp;No&nbsp;funciona;&nbsp;busca&nbsp;por&nbsp;un&nbsp;archivo&nbsp;llamado&nbsp;'file.php?foo=1&bar=2'&nbsp;en&nbsp;el
//&nbsp;sistema&nbsp;de&nbsp;archivos&nbsp;local.
include&nbsp;'file.php?foo=1&bar=2';

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

$foo&nbsp;=&nbsp;1;
$bar&nbsp;=&nbsp;2;
include&nbsp;'file.txt';&nbsp;&nbsp;//&nbsp;Funciona.
include&nbsp;'file.php';&nbsp;&nbsp;//&nbsp;Funciona.
?>

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, readfile() es la mejor función para usar. De lo contrario, debe tenerse especial cuidado para asegurar que el script remoto produce un código válido y deseado.

Ver también Archivos remotos, fopen() y file() para información relacionada.

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 return dentro de un archivo incluido con el fin de terminar el procesamiento en ese archivo y volver a script que lo llamó. Además, es posible retornar valores desde los archivos incluidos. Se puede tomar el valor de la llamada “include” de la misma forma como se haría con una función normal. Esto no es, sin embargo, posible si se incluyen archivos remotos, a menos que la salida del archivo remoto tenga unas 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

<?php
//&nbsp;no&nbsp;funciona,&nbsp;evaluado&nbsp;como&nbsp;include(('vars.php')&nbsp;==&nbsp;'OK'),&nbsp;es&nbsp;decir&nbsp;include('')
if&nbsp;(include('vars.php')&nbsp;==&nbsp;'OK')&nbsp;{
echo&nbsp;'OK';
}

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

Ejemplo #5 include y la sentencia return

return.php
<?php
$var&nbsp;=&nbsp;'PHP';
return&nbsp;$var;
?>

noreturn.php
<?php
$var&nbsp;=&nbsp;'PHP';
?>

testreturns.php
<?php
$foo&nbsp;=&nbsp;include&nbsp;'return.php';
echo&nbsp;$foo;&nbsp;//&nbsp;muestra&nbsp;'PHP'
$bar&nbsp;=&nbsp;include&nbsp;'noreturn.php';
echo&nbsp;$bar;&nbsp;//&nbsp;muestra&nbsp;1
?>

$bar tiene el valor 1 debido a que el include fue exitoso. Nótese la diferencia entre los ejemplos anteriores. El primero usa return dentro del archivo incluido, mientras que el otro no. Si el archivo no se pueden incluir, se retorna 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 return antes o después. Si el archivo se incluye dos veces, PHP 5 arrojará un error fatal ya que las funciones ya han sido declaradas, mientras que PHP 4 no se queja acerca de las funciones definidas después de un return. Se recomienda el uso de include_once en lugar de comprobar si el archivo ya estaba incluido y hacer el retorno de forma condicionada dentro del archivo incluido.

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

<?php
$string&nbsp;=&nbsp;get_include_contents('somefile.php');

function&nbsp;get_include_contents($filename)&nbsp;{
if&nbsp;(is_file($filename))&nbsp;{
ob_start();
include&nbsp;$filename;
return&nbsp;ob_get_clean();
}
return&nbsp;false;
}
?>

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.

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

 

include_once

(PHP 4, PHP 5)

La sentencia include_once incluye y evalúa el fichero especificado durante la ejecución del script. Es un comportamiento similar al de la sentencia include, siendo la única diferencia que si el código del fichero ya ha sido incluido, no se volverá a incluir. Como su nombre lo indica, será incluido sólo una vez.

include_once puede ser usado en casos donde el mismo fichero podría ser incluido y evaluado más de una vez durante una ejecución particular de un script, así que en este caso, puede ayudar a evitar problemas como la redefinición de funciones, reasignación de valores de variables, etc.

Ver la documentación de include para información sobre como trabaja esta función.

Nota:

Con PHP 4, la funcionalidad _once difiere entre sistemas operativos insensibles a mayúsculas y minúsculas (como Windows) así que por ejemplo:

Ejemplo #1 include_once con un SO insensible a mayúsculas y minúsculas en PHP 4

<?php
include_once&nbsp;"a.php";&nbsp;//&nbsp;esto&nbsp;incluirá&nbsp;a.php
include_once&nbsp;"A.php";&nbsp;//&nbsp;esto&nbsp;incluirá&nbsp;a.php&nbsp;otra&nbsp;vez!&nbsp;(sólo&nbsp;PHP&nbsp;4)
?>

Este comportamiento cambió en PHP 5, así que por ejemplo con Windows primero se normaliza la ruta de acceso para que C:\PROGRA~1\A.php sea identificado igual que C:\Program Files\a.php y el fichero sea incluido sólo una vez.

Me gusta:

Etiquetas: , ,

By in include / include_once on .

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s

A %d blogueros les gusta esto: