archived-doc-es/language/control-structures/include.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: c5c902b47755cf0c0761e90cce4cc8ee1eb9426e Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: seros -->

<sect1 xml:id="function.include" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>include</title>
 <?phpdoc print-version-for="include"?>
 <simpara>
  La sentencia <literal>include</literal> incluye y evalúa
  el archivo especificado.
 </simpara>
 <simpara>
  La siguiente documentación también se aplica a <function>require</function>.
 </simpara>
 <simpara>
  Los archivos son incluidos con base en la ruta de acceso dada o, si ninguna es dada, el
  <link linkend="ini.include-path">include_path</link> especificado. Si el archivo
  no se encuentra en el <link linkend="ini.include-path">include_path</link>,
  <literal>include</literal> finalmente verificará en el propio directorio del script
  que hace el llamado y en el directorio de trabajo actual, antes de fallar. El
  constructor <literal>include</literal> emitirá una
  <link linkend="errorfunc.constants.errorlevels.e-warning">advertencia</link> si
  no puede encontrar un archivo, éste es un comportamiento diferente al de
  <function>require</function>, el cual emitirá un
  <link linkend="errorfunc.constants.errorlevels.e-error">error fatal.</link>.
 </simpara>
 <simpara>
  Si una ruta es definida — ya sea absoluta (comenzando con una letra de unidad
  o <literal>\</literal> en Windows o <literal>/</literal> en sistemas Unix/Linux) o relativa al
  directorio actual (comenzando con <literal>.</literal> o
  <literal>..</literal>) — el
  <link linkend="ini.include-path">include_path</link> será ignorado
  por completo. Por ejemplo, si un nombre de archivo comienza con <literal>../</literal>,
  el interprete buscará en el directorio padre para encontrar el archivo solicitado.
 </simpara>
 <simpara>
  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 <link linkend="ini.include-path">include_path</link>. 
 </simpara>
 <simpara>
  Cuando se incluye un archivo, el código que contiene hereda el
  <link linkend="language.variables.scope">ámbito de las variables</link> 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.
 </simpara>
 <para>
  <example>
   <title>Ejemplo básico de <literal>include</literal></title>
   <programlisting role="php">
<![CDATA[
vars.php
<?php

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

?>

test.php
<?php

echo "Una $fruta $color"; // Una

include 'vars.php';

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

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  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 <link
  linkend="language.constants.predefined">constantes mágicas</link> las cuales son
  evaluadas por el intérprete antes que ocurra la inclusión.
 </simpara>
 <para>
  <example>
   <title>Incluyendo dentro de funciones</title>
   <programlisting role="php">
<![CDATA[
<?php

function foo()
{
    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 verde
echo "Una $fruta $color";   // Una verde

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  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
  <link linkend="language.basic-syntax.phpmode">etiquetas válidas de
   comienzo y terminación de PHP</link>.
 </simpara>
 <simpara>
  Si las "<link linkend="ini.allow-url-include">envolturas URL include</link>"
  están activadas en PHP,
  se puede especificar el archivo a ser incluido usando una URL (vía HTTP u
  otra envoltura soportada - ver <xref linkend="wrappers"/> 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.
 </simpara>
 <para>
  <example>
   <title><literal>include</literal> por medio de HTTP</title>
   <programlisting role="php">
<![CDATA[
<?php

/* Este ejemplo asume que www.example.com está configurado para interpretar archivos
* .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 PHP
include '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.

?>
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <title>Advertencia de seguridad</title>
  <para>
   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, <function>readfile</function> 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.
  </para>
 </warning>
 <para>
  Ver también <link linkend="features.remote-files">Archivos remotos</link>,
  <function>fopen</function> y <function>file</function> para información
  relacionada.
 </para>
 <simpara>
  Manejando retornos: <literal>include</literal> devuelve 
  <literal>FALSE</literal> en caso de falla y eleva una advertencia. Inclusiones
  exitosas, a menos que sea reemplazado por el archivo incluido, devolverá
  <literal>1</literal>. Es posible ejecutar una sentencia <function>return</function>
  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 <link linkend= "language.basic-syntax.phpmode">etiquetas válidas de
  inicio y terminación de PHP</link> (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.
 </simpara>
 <para>
  Debido a que <literal>include</literal> 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.
  <example>
   <title>Comparando el valor de retorno de include</title>
   <programlisting role="php">
<![CDATA[
<?php
// no funcionará, se evalúa como include(('vars.php') == TRUE), es decir, include('')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// sí funciona
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title><literal>include</literal> y la sentencia <function>return</function></title>
   <programlisting role="php">
<![CDATA[
return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // muestra 'PHP'

$bar = include 'noreturn.php';

echo $bar; // muestra 1

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  <literal>$bar</literal> tiene el valor <literal>1</literal> debido a que el include
  fue exitoso. Nótese la diferencia entre los ejemplos anteriores. El primero usa
  <function>return</function> dentro del archivo incluido, mientras que el otro no.
  Si el archivo no se pueden incluir, se retorna &false; y
  se emite un <constant>E_WARNING</constant>.
 </simpara>
 <para>
  Si hay funciones definidas en el archivo incluido, se pueden utilizar en el
  archivo principal independientemente que hayan <function>return</function> 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 <function>return</function>.
  Se recomienda el uso de <function>include_once</function> en lugar de
  comprobar si el archivo ya estaba incluido y hacer el retorno de forma condicionada dentro
  del archivo incluido.
 </para>
 <simpara>
  Otra forma de "incluir" un archivo PHP en una variable es capturar la
  salida mediante el uso de <link linkend="ref.outcontrol">Funciones de control de
  salida</link> con <literal>include</literal>. Por ejemplo:
 </simpara>
 <para>
  <example>
   <title>Usando buffering de salida para incluir un archivo PHP dentro de una cadena</title>
   <programlisting role="php">
<![CDATA[
<?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;
}

?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  Con el fin de incluir archivos de forma automática dentro de scripts, véase también las
  opciones de configuración
  <link linkend="ini.auto-prepend-file">auto_prepend_file</link> and
  <link linkend="ini.auto-append-file">auto_append_file</link> en &php.ini;.
 </para>
 
 &note.language-construct;
 
 <simpara>
  Ver también <function>require</function>, <function>require_once</function>,
  <function>include_once</function>, <function>get_included_files</function>,
  <function>readfile</function>, <function>virtual</function> y
  <link linkend="ini.include-path">include_path</link>.
 </simpara>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->