file-put-contents.xml

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

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file-put-contents">
 <refnamediv>
  <refname>file_put_contents</refname> 
  <refpurpose>Escribir datos en un fichero</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>file_put_contents</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam><type>mixed</type><parameter>data</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
  </methodsynopsis>
  <para> 
   Esta función es idéntica que llamar a <function>fopen</function>, 
   <function>fwrite</function> y <function>fclose</function> sucesivamente
   para escribir información en un fichero.
  </para>
  <para>
   Si <parameter>filename</parameter> no existe, se crea el fichero.
   De otro modo, el fichero existente se sobrescribe, a menos que la
   bandera <constant>FILE_APPEND</constant> esté establecida.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Ruta del fichero donde se escribe la información
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>data</parameter></term>
     <listitem>
      <para>
       La información a escribir. Puede ser tanto un recurso <type>string</type>, como
       <type>array</type> o <type>stream</type>.
      </para>
      <para>
       Si <parameter>data</parameter> es un recurso <type>stream</type>, el
       buffer restante de ese flujo será copiado al fichero especificado.
       Esto es similar a usar <function>stream_copy_to_stream</function>.
      </para>
      <para>
       También se puede especificar el parámetro <parameter>data</parameter> como un
       array de una sóla dimensión. Esto es equivalente a
       <literal>file_put_contents($nombre_fichero, implode('', $array))</literal>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       El valor de <parameter>flags</parameter> puede ser cualquier combinación de
       las siguientes banderas, unidas con el operador binario OR
       (<literal>|</literal>).
      </para>
      <para>
       <table>
        <title>Banderas disponibles</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Bandera</entry>
           <entry>Descripción</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>
            <constant>FILE_USE_INCLUDE_PATH</constant>
           </entry>
           <entry>
            Buscar <parameter>filename</parameter> en el directorio incluido.
            Véase <link linkend="ini.include-path">include_path</link> para más
            información.
           </entry>
          </row>
          <row>
           <entry>
            <constant>FILE_APPEND</constant>
           </entry>
           <entry>
            Si el fichero <parameter>filename</parameter> ya existe, añade
            la información al fichero en vez de sobrescribirlo.
           </entry>
          </row>
          <row>
           <entry>
            <constant>LOCK_EX</constant>
           </entry>
           <entry>
            Adquirir acceso exclusivo al fichero mientras se está ejecutando la
            escritura. En otras palabras, ocurre una llamada a <function>flock</function>
            entre la llamada a <function>fopen</function> y la llamada a
            <function>fwrite</function>. Esto no es indéntico a una llamada a
            <function>fopen</function> con el modo "x".
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>context</parameter></term>
     <listitem>
      <para>
       Un recurso de contexto válido creado con
       <function>stream_context_create</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Esta función devuelve el número de bytes que fueron escritos en el fichero, o
   &false; en caso de error.
  </para>
  &return.falseproblem;
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo sencillo de uso</title>
    <programlisting role="php">
<![CDATA[
<?php
$fichero = 'gente.txt';
// Abre el fichero para obtener el contenido existente
$actual = file_get_contents($fichero);
// Añade una nueva persona al fichero
$actual .= "John Smith\n";
// Escribe el contenido al fichero
file_put_contents($fichero, $actual);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Usar banderas</title>
    <programlisting role="php">
<![CDATA[
<?php
$fichero = 'gente.txt';
// La nueva persona a añdir al fichero
$persona = "John Smith\n";
// Escribir los contenidos en el fichero,
// usando la bandera FILE_APPEND para añadir el contenido al final del fichero
// y la bandera LOCK_EX para evitar que cualquiera escriba en el fichero al mismo tiempo
file_put_contents($fichero, $persona, FILE_APPEND | LOCK_EX);
?>
]]>
    </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>5.1.0</entry>
       <entry>
        Añadido el soporte para <constant>LOCK_EX</constant> y la capacidad de pasar
        un recurso de flujo al parámetro <parameter>data</parameter>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  &note.bin-safe;
  &tip.fopen-wrapper;
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>fopen</function></member>
    <member><function>fwrite</function></member>
    <member><function>file_get_contents</function></member>
    <member><function>stream_context_create</function></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
-->