file-get-contents.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 52ac14fb9776027eb61be0a8d124b6711bfa98ec Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file-get-contents" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>file_get_contents</refname>
  <refpurpose>Transmite un fichero completo a una cadena</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>file_get_contents</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>maxlen</parameter></methodparam>
  </methodsynopsis>
  <para>
   Esta función es similar a <function>file</function>, excepto que
   <function>file_get_contents</function> devuelve el fichero a un
   <type>string</type>, comenzando por el <parameter>offset</parameter> especificado
   hasta <parameter>maxlen</parameter> bytes. Si falla,
   <function>file_get_contents</function> devolverá &false;.
  </para>
  <para>
   <function>file_get_contents</function> es la manera preferida de transmitir el
   contenido de un fichero a una cadena. Para mejorar el rendimiento, utiliza técnicas
   de mapeado de memoria si sistema operativo lo admite..
  </para>
  <note>
   <para>
    Si se está abriendo un URI con caracteres especiales, tales como espacios,
    se necesita codificar el URI con <function>urlencode</function>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Nombre del fichero a leer.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>use_include_path</parameter></term>
     <listitem>
      <note>
       <para>
        A partir de PHP 5, se puede usar la constante <constant>FILE_USE_INCLUDE_PATH</constant>
        para lanzar la búsqueda en
        <link linkend="ini.include-path">include_path</link>.
        Esto no es posible si está habilitada la <link
        linkend="language.types.declarations.strict">tipificación esctricta</link>,
        ya que <constant>FILE_USE_INCLUDE_PATH</constant> es de tipo
        <type>int</type>. Utilice &true; en su lugar.

       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>context</parameter></term>
     <listitem>
      <para>
       Un recurso de contexto válido creado con
       <function>stream_context_create</function>. Si no se necesita usar un
       contexto a medida, se puede saltar este parámetro usando &null;.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       El índice donde comienza la lectura en el flujo original.
       Los índices negativos inician la cuenta desde el final del flujo.
      </para>
      <para>
       La búsqueda de (<parameter>offset</parameter>) no está soportada con ficheros remotos.
       Intentar buscar un fichero no local puede funcionar con índices pequeños, pero
       es impredecible debido a que trabaja sobre el flujo almacenado en buffer.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>maxlen</parameter></term>
     <listitem>
      <para>
       La longitud máxima de los datos leídos. De manera predeterminada se lee hasta que
       se alcance el final del fichero. Observe que este parámetro se aplica al
       flujo procesado por los filtros.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Esta función devuelve los datos leídos &return.falseforfailure;.
  </para>
  &return.falseproblem;
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Se genera un error de nivel <constant>E_WARNING</constant> si <parameter>filename</parameter> no se pudo encontrar, <parameter>maxlength</parameter>
   es menor de cero, o si falla la búsqueda del <parameter>offset</parameter> especificado en el flujo.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Obtiene y muestra el código fuente de la página de inicio de un sitio web</title>
    <programlisting role="php">
<![CDATA[
<?php
$página_inicio = file_get_contents('http://www.example.com/');
echo $página_inicio;
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Buscar dentro de include_path</title>
    <programlisting role="php">
<![CDATA[
<?php
// <= PHP 5
$fichero = file_get_contents('./gente.txt', true);
// > PHP 5
$fichero = file_get_contents('./gente.txt', FILE_USE_INCLUDE_PATH);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Leer una sección de un fichero</title>
    <programlisting role="php">
<![CDATA[
<?php
// Leer 14 caracteres comenzando desde el carácter número 21
$sección = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
var_dump($sección);
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
string(14) "lle Bjori Ro"
]]>
    </screen>
   </example>
   <example>
    <title>Usar contextos de flujo</title>
    <programlisting role="php">
<![CDATA[
<?php
// Crear un flujo
$opciones = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar\r\n"
  )
);

$contexto = stream_context_create($opciones);

// Abre el fichero usando las cabeceras HTTP establecidas arriba
$fichero = file_get_contents('http://www.example.com/', false, $contexto);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.1.0</entry>
       <entry>
        Se añadió soporte para valores negativos de <parameter>offset</parameter>.
       </entry>
      </row>
      <row>
       <entry>5.1.0</entry>
       <entry>
        Se añadieron los parámetros <parameter>offset</parameter> y
        <parameter>maxlen</parameter>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.bin-safe;
  &tip.fopen-wrapper;
  &warn.ssl-non-standard;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>file</function></member>
    <member><function>fgets</function></member>
    <member><function>fread</function></member>
    <member><function>readfile</function></member>
    <member><function>file_put_contents</function></member>
    <member><function>stream_get_contents</function></member>
    <member><function>stream_context_create</function></member>
    <member><link linkend="reserved.variables.httpresponseheader">$http_response_header</link></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- 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
-->