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

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

<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 expresión de lenguaje <literal>include</literal> incluye y ejecuta
  el fichero especificado en argumento.
 </simpara>
 <simpara>
  Esta documentación también se aplica a la instrucción de lenguaje
  <function>require</function>.
 </simpara>
 <simpara>
  Los ficheros se incluyen siguiendo la ruta del fichero proporcionada; si no se proporciona ninguna,
  se verificará el <link linkend="ini.include-path">include_path</link>. Si el fichero no se encuentra en el
  <link linkend="ini.include-path">include_path</link>,
  <literal>include</literal> verificará en el directorio del script llamador
  y en el directorio de trabajo actual antes de fallar. La instrucción
  <literal>include</literal> emitirá <constant>E_WARNING</constant> si no puede encontrar el fichero; este comportamiento es diferente de
  <function>require</function>, que emitirá <constant>E_ERROR</constant>.
 </simpara>
 <simpara>
  Tenga en cuenta que <literal>include</literal> y <literal>require</literal>
  lanzarán errores de tipo <constant>E_WARNING</constant>, si el
  fichero no es accesible, antes de lanzar un error de tipo
  <constant>E_WARNING</constant> o <constant>E_ERROR</constant>, respectivamente.
 </simpara>
 <simpara>
  Si se define una ruta, absoluta (comenzando con una letra de unidad seguida
  de <literal>\</literal> para Windows, o <literal>/</literal> para Unix/Linux)
  o relativa (comenzando con . o ..), el <link linkend="ini.include-path">include_path</link>
  será ignorado. Por ejemplo, si un nombre de fichero comienza con <literal>../</literal>,
  PHP buscará en el directorio padre para encontrar el fichero especificado.
 </simpara>
 <simpara>
  Para más información sobre cómo PHP maneja los ficheros incluidos así
  como la ruta de inclusión, consulte la documentación relativa
  al <link linkend="ini.include-path">include_path</link>.
 </simpara>
 <simpara>
  Cuando un fichero es incluido, el código que lo compone hereda el
  <link linkend="language.variables.scope">ámbito de las variables</link>
  de la línea donde aparece la inclusión. Todas las variables disponibles en esa
  línea en el fichero llamador estarán disponibles en el fichero llamado, a partir de ese punto. Sin embargo, todas las funciones y clases definidas en
  el fichero incluido tienen un ámbito global.
 </simpara>
 <para>
  <example>
   <title>Ejemplo con <literal>include</literal></title>
   <programlisting role="php">
<![CDATA[
vars.php
<?php

$color = 'verde';
$fruit = 'manzana';

?>

test.php
<?php

echo "Una $fruit $color"; // Una

include 'vars.php';

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

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  Si la inclusión ocurre dentro de una función,
  el código incluido será considerado como parte de la
  función. Esto modifica el contexto de las variables accesibles.
  Una excepción a esta regla: las <link
  linkend="language.constants.magic">constantes mágicas</link> son analizadas
  por el analizador antes de que la inclusión ocurra.
 </simpara>
 <para>
  <example>
   <title>Inclusión de ficheros dentro de una función</title>
   <programlisting role="php">
<![CDATA[
<?php

function foo()
{
    global $couleur;

    include 'vars.php';

    echo "Una $fruit $couleur";
}

/* vars.php está en el contexto de foo()
 * por lo tanto $fruit no está disponible fuera de
 * esta función. $couleur sí lo está, ya que es
 * una variable global */

foo();                      // Una pomme verte
echo "Una $fruit $couleur"; // Una  verte

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  Es importante señalar que cuando un fichero es
  <function>include</function> o <function>require</function>,
  los errores de análisis aparecerán en HTML al
  principio del fichero, y el análisis del fichero
  padre no será interrumpido. Por esta razón, el código
  que está en el fichero debe ser colocado entre
  <link linkend="language.basic-syntax.phpmode">las etiquetas
  habituales de PHP</link>.
 </simpara>
 <simpara>
  Si los <link linkend="ini.allow-url-include">gestores de inclusión de URL</link>
  están activados en PHP,
  puede localizar el fichero con una URL (vía HTTP o
  bien con un gestor adecuado: ver <xref linkend="wrappers"/>
  para una lista de protocolos), en lugar de una simple ruta
  local. Si el servidor remoto interpreta el fichero como código
  PHP, variables pueden ser transmitidas al servidor remoto
  vía la URL y el método GET. Esto no es, estrictamente hablando,
  lo mismo que heredar el contexto de variable.
  El fichero incluido es en realidad un script ejecutado a distancia,
  y su resultado es incluido en el código actual.
 </simpara>
 <para>
  <example>
   <title>Utilizar la instrucción <literal>include</literal> vía HTTP</title>
   <programlisting role="php">
<![CDATA[
<?php

/* Este ejemplo supone que www.example.com está configurado para tratar
 * los ficheros .php y no los ficheros .txt. Además,
 * 'Work' significa aquí que las variables
 * $foo y $bar están disponibles en el fichero incluido
 */

// No funciona: file.txt no ha sido tratado por www.example.com como PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// No funciona: el script busca un fichero llamado
// 'file.php?foo=1&bar=2' en el sistema local
include 'file.php?foo=1&bar=2';

// Funciona
include 'http://www.example.com/file.php?foo=1&bar=2';
?>
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <title>Alerta de seguridad</title>
  <para>
   Un fichero remoto puede ser tratado en el servidor remoto
   (dependiendo de la extensión del fichero y si el servidor remoto
   ejecuta PHP o no) pero debe producir siempre un script PHP válido
   porque será tratado en el servidor local. Si el fichero del servidor
   remoto debe ser tratado en el lugar y mostrado solamente,
   <function>readfile</function> es una función mucho más apropiada.
   De otra manera, debería tener cuidado de asegurar el script remoto
   para que produzca un código válido y deseado.
   </para>
 </warning>
 <para>
  Ver también
  <link linkend="features.remote-files">trabajar con ficheros remotos</link>,
  <function>fopen</function> y
  <function>file</function> para información relacionada.
 </para>
 <simpara>
  Manejo del retorno: <literal>include</literal> devuelve &false; en caso
  de error y emite un aviso. Las inclusiones exitosas, incluyendo si
  son sobrescritas por el fichero incluido, devuelven
  <literal>1</literal>. Es posible ejecutar la estructura de lenguaje
  <function>return</function> dentro de un fichero
  incluido para determinar el proceso en ese fichero, y volver
  al script que lo llamó. Además, es posible devolver valores desde ficheros incluidos. Puede tomar el valor
  desde la llamada al fichero incluido como desee desde una
  función normal. Esto no es posible, sin embargo, al incluir ficheros remotos, y esto, mientras la salida del fichero remoto no tenga
  <link linkend= "language.basic-syntax.phpmode">etiquetas PHP de inicio
  y fin válidas</link> (al igual que para los ficheros locales).
  Puede declarar las variables necesarias dentro de estas etiquetas
  y serán introducidas en el lugar donde el fichero fue incluido.
 </simpara>
 <para>
  Como <literal>include</literal> es una estructura de lenguaje particular,
  los paréntesis no son necesarios alrededor del argumento. Tenga cuidado
  al comparar el valor devuelto.
  <example>
   <title>Comparación del valor devuelto de una inclusión</title>
   <programlisting role="php">
<![CDATA[
<?php
// No funciona, evaluado como include(('vars.php') == TRUE), es decir include('1')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// Funciona
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title><literal>include</literal> y <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 de <literal>1</literal> ya que
  la inclusión fue exitosa. Tenga en cuenta la diferencia entre los dos
  ejemplos anteriores. El primero utiliza el comando
  <function>return</function>
  en el fichero incluido, mientras que el segundo no lo hace.
  Si el fichero no puede ser incluido, &false; es devuelto y un error
  de nivel <constant>E_WARNING</constant> es enviado.
 </simpara>
 <para>
  Si hay funciones definidas en el fichero incluido, pueden ser
  utilizadas en el fichero principal si están antes del
  <function>return</function> o después.
  Si el fichero es incluido dos veces, PHP emitirá un error fatal ya que las
  funciones ya han sido declaradas.
  Se recomienda utilizar <function>include_once</function>
  en lugar de verificar si el fichero ya ha sido incluido y por lo tanto devolver
  condicionalmente la inclusión del fichero.
 </para>
 <simpara>
  Otra forma de incluir un fichero PHP en una variable es capturar
  la salida utilizando las funciones de
  <link linkend="ref.outcontrol">control de salida</link> con
  <literal>include</literal>. Por ejemplo:
 </simpara>
 <para>
  <example>
   <title>Uso del buffer de salida para incluir un fichero PHP en
   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>
  Para incluir automáticamente ficheros en sus scripts, vea también
  las opciones de configuración
  <link linkend="ini.auto-prepend-file">auto_prepend_file</link> y
  <link linkend="ini.auto-append-file">auto_append_file</link>
  del &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
-->