archived-doc-es/reference/mongo/mongocollection/save.xml

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

<refentry xml:id="mongocollection.save" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCollection::save</refname>
  <refpurpose>Guarda un documento en esta colección</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>mixed</type><methodname>MongoCollection::save</methodname>
   <methodparam><type>array|object</type><parameter>document</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
  </methodsynopsis>
  <para>
   Si el objeto fuera de la base de datos, se actualizará. En caso contrario, se
   insertará.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;    
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>document</parameter>
     </term>
     <listitem>
      <para>
       Array u objeto a guardar. Si se usa un objeto, este no puede tener propiedades
       protegidas o privadas.
      </para>
      <note>
       <para>
        Si el parámetro no posee una clave o propiedad <literal>_id</literal>,
        se creará una nueva instancia de <classname>MongoId</classname>
        y se le asignará. Véase <function>MongoCollection::insert</function> para
        información adicional sobre este comportamiento.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <parameter>options</parameter>
     </term>
     <listitem>
      <para>
       Opciones para el guardado.
       <itemizedlist>
        &mongo.writes.parameters.fsync;
        &mongo.writes.parameters.journal;
        &mongo.writes.parameters.sockettimeoutms;
        &mongo.writes.parameters.writeconcern;
        &mongo.writes.parameters.writeconcerntimeout;
        &mongo.writes.parameters.writeconcerntimeoutms;
        &mongo.writes.parameters.safe;
        &mongo.writes.parameters.timeout;
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>   
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Si <parameter>w</parameter> estuviera habilitado, devolverá un array que contiene el estado de la
   escritura. En cualquier otro caso, devuelve un booleano que representa si el array no estaba vacío
   (un array vacío no se insertará).
  </para>
 </refsect1>
 
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Lanza una <classname>MongoException</classname> si el documento insertado está
   vacío o si contiene claves de longitud cero. Intentar insertar un objeto
   con propiedades protegidas o privadas causará un error de clave de longitud cero.
  </para>
  &mongo.errors.exceptions.writeconcern;
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>1.5.0</entry>
       <entry>
        <para>
         Se añadió la opción <literal>"wTimeoutMS"</literal>, la cual reemplaza a
         <literal>"wtimeout"</literal>. Emite un error <constant>E_DEPRECATED</constant>
         al utilizar <literal>"wtimeout"</literal>.
        </para>
        <para>
         Se añadió la opción <literal>"socketTimeoutMS"</literal>, la cual reemplaza a
         <literal>"timeout"</literal>. Emite un error <constant>E_DEPRECATED</constant>
         al utilizar <literal>"wtimeout"</literal>.
        </para>
        <para>
         Emite un error <constant>E_DEPRECATED</constant> al utilizar
         <literal>"safe"</literal>.
        </para>
       </entry>
      </row>
      <row>
       <entry>1.2.0</entry>
       <entry>Añadida la opción <literal>"timeout"</literal>.</entry>
      </row>
      <row>
       <entry>1.0.11</entry>
       <entry>
        Se desconecta en errores "not master" si <literal>"safe"</literal> está establecido.
       </entry>
      </row>
      <row>
       <entry>1.0.9</entry>
       <entry>
        <para>
         Añadida la opción <literal>"fsync"</literal>.
        </para>
       </entry>
      </row>
      <row>
       <entry>1.0.5</entry>
       <entry>Añadido el parámetro <parameter>options</parameter>.</entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Ejemplo de <function>MongoCollection::save</function></title>
   <programlisting role="php">
<![CDATA[
<?php

$obj = array('x' => 1);

// insertar $obj en la base de datos
$collection->save($obj);
var_dump($obj);

// añadir otro campo
$obj['foo'] = 'bar';

// $obj no puede insertarse de nuevo; provoca un error de _id duplicado
$collection->insert($obj);

// la función save actualiza $obj con el nuevo campo
$collection->save($obj);

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
array(2) {
  ["x"]=>
  int(1)
  ["_id"]=>
  object(MongoId)#4 (1) {
    ["$id"]=>
    string(24) "50b6afe544415ed606000000"
  }
}
]]>
   </screen>
  </example>
 </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
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
-->