doc-fr/reference/mysql_xdevapi/mysql_xdevapi/collection/add.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: f1e951b988e8aafe49b33bdf2f7812740c66c2d2 Maintainer: Fan2Shrek Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="mysql-xdevapi-collection.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Collection::add</refname>
  <refpurpose>Ajoute un document à la collection</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>mysql_xdevapi\CollectionAdd</type><methodname>mysql_xdevapi\Collection::add</methodname>
   <methodparam><type>mixed</type><parameter>document</parameter></methodparam>
  </methodsynopsis>
  <para>
   Déclenche l'insertion du ou des documents donnés dans la collection, et
   plusieurs variantes de cette méthode sont prises en charge. Les options incluent :
  </para>
  <orderedlist>
   <listitem>
     <para>
      Ajouter un seul document sous forme de chaîne JSON.
     </para>
   </listitem>
   <listitem>
     <para>
      Ajouter un seul document sous forme de tableau comme :
      <literal>[ 'field' => 'value', 'field2' => 'value2' ... ]</literal>
    </para>
   </listitem>
   <listitem>
    <para>
      Un mélange des deux, et plusieurs documents peuvent être ajoutés dans la même opération.
    </para>
   </listitem>
  </orderedlist>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>document</parameter></term>
    <listitem>
     <para>
      Un ou plusieurs documents, et cela peut être soit du JSON ou un tableau de champs avec
      leurs valeurs associées. Cela ne peut pas être un tableau vide.
     </para>
     <para>
      Le serveur MySQL génère automatiquement des valeurs <literal>_id</literal> uniques pour
      chaque document (recommandé), bien que cela puisse également être ajouté manuellement. Cette
      valeur doit être unique, sinon l'opération d'ajout échouera.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Une collection d'objets, Utiliser execute() pour retourner un résultat qui peut être utilisé pour
   interroger le nombre d'éléments affectés, le nombre d'avertissements générés par l'opération, ou pour
   récupérer une liste d'identifiants générés pour les documents insérés.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Exemple de <function>mysql_xdevapi\Collection::add</function></title>
   <programlisting role="php">
<![CDATA[
<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// Ajoute deux documents
$collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
$collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

// Ajoute deux documents en utilisant un seul objet JSON
$result = $collection->add(
  '{"name": "Bernie",
    "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
    "hobbies": ["Sports","Making cupcakes"]}',
  '{"name": "Jane",
    "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
    "hobbies": ["Walking","Making pies"]}')->execute();

// Récupère une liste d'identifiants générés à partir du dernier add()
$ids = $result->getGeneratedIds();
print_r($ids);
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Array
(
    [0] => 00005b6b53610000000000000056
    [1] => 00005b6b53610000000000000057
)
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Un identifiant unique _id est généré par MySQL Server 8.0 ou supérieur, comme démontré
    dans l'exemple. Le champ _id doit être défini manuellement si vous utilisez
    MySQL Server 5.7.
   </para>
  </note>
 </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
-->