Add documentation on insert(), update() and delete()

source/devapi/database/dbiterator.rst

@@ -1,17 +1,21 @@
-DBIterator
-----------
+Querying
+--------
 
-Goals
-^^^^^
-
-Provide a simple request generator:
+GLPI framework provides a simple request generator:
 
 * without having to write SQL
 * without having to quote table and field name
 * without having to take care of freeing resources
 * iterable
 * countable
 
+.. warning::
+
+   The request generator does not currently support:
+
+   * SQL functions (``NOW()``, ``ADD_DATE()``, ...),
+   * alias in queries.
+
 Basic usage
 ^^^^^^^^^^^
 
@@ -48,6 +52,15 @@ Giving full SQL statement
 If the only option is a full SQL statement, it will be used.
 This usage is deprecated, and should be avoid when possible.
 
+.. note::
+
+   To make a database query that could not be done using recommanded way (calling SQL functions such as ``NOW()``, ``ADD_DATE()``, ... for example), you can do:
+
+   .. code-block:: php
+
+      <?php
+      $DB->request('SELECT id FROM glpi_users WHERE end_date > NOW()');
+
 Without option
 ^^^^^^^^^^^^^^
 
@@ -191,6 +204,8 @@ Using the ``START`` and ``LIMIT`` options:
    $DB->request('glpi_computers', ['START' => 5, 'LIMIT' => 10]);
    // => SELECT * FROM `glpi_computers` LIMIT 10 OFFSET 5"
 
+.. _query_criteria:
+
 Criteria
 ^^^^^^^^
 

source/devapi/database/dbupdate.rst

@@ -0,0 +1,84 @@
+Updating
+--------
+
+.. versionadded:: 9.3
+
+Just as SQL `SELECT` queries, you should avoid plain SQL and use methods provided by the famework from the `DB object <https://forge.glpi-project.org/apidoc/class-DBmysql.html>`_.
+
+.. note::
+
+   To make a database query that could not be done using recommanded way (calling SQL functions such as ``NOW()``, ``ADD_DATE()``, ... for example), you can do:
+
+   .. code-block:: php
+
+      <?php
+      $DB->query('UPDATE glpi_users SET date_mod = NOW()');
+
+   Just like :doc:`querying database <dbiterator>`; you will have to rely on plain SQL when using not supported features, like SQL functions.
+
+General
+^^^^^^^
+
+Escaping of data is currently provided automatically by the framework for all data passed from `GET` or `POST`; you do not have to take care of them (this will change in a future version). You have to take care of escaping data when you use values that came from elsewhere.
+
+The `WHERE` part of `UPDATE` and `DELETE` methods uses the same :ref:`criteria capabilities <query_criteria>` than `SELECT` queries.
+
+Inserting a row
+^^^^^^^^^^^^^^^
+
+You can insert a row in the database using the `insert() method <https://forge.glpi-project.org/apidoc/class-DBmysql.html#_insert>`_:
+
+.. code-block:: php
+
+   <?php
+
+   $DB->insert(
+      'glpi_my_table', [
+         'a_field'      => 'My value',
+         'other_field'  => 'Other value'
+      ]
+   );
+   // => INSERT INTO `glpi_my_table` (`a_field`, `other_field`) VALUES ('My value', Other value)
+
+An `insertOrDie() method <https://forge.glpi-project.org/apidoc/class-DBmysql.html#_insertOrDie>`_ is also provided.
+
+Updating a row
+^^^^^^^^^^^^^^
+
+You can update rows in the database using the `update() method <https://forge.glpi-project.org/apidoc/class-DBmysql.html#_update>`_:
+
+.. code-block:: php
+
+   <?php
+
+   $DB->update(
+      'glpi_my_table', [
+         'a_field'      => 'My value',
+         'other_field'  => 'Other value'
+      ], [
+         'id' => 42
+      ]
+   );
+   // => UPDATE `glpi_my_table` SET `a_field` = 'My value', `other_field` = 'Other value' WHERE `id` = 42
+
+An `updateOrDie() method <https://forge.glpi-project.org/apidoc/class-DBmysql.html#_updateOrDie>`_ is also provided.
+
+.. note::
+
+   The ``update()`` method does not currently support using another field in set. You will therefore have to run queries like ``UPDATE glpi_my_table` SET `ranking` = ranking+1`` using the legacy way.
+
+Removing a row
+^^^^^^^^^^^^^^
+
+You can remove rows from the database using the `delete() method <https://forge.glpi-project.org/apidoc/class-DBmysql.html#_delete>`_:
+
+.. code-block:: php
+
+   <?php
+
+   $DB->delete(
+      'glpi_my_table', [
+         'id' => 42
+      ]
+   );
+   // => DELETE FROM `glpi_my_table` WHERE `id` = 42

source/devapi/database/index.rst

@@ -5,5 +5,5 @@ Database
    :maxdepth: 2
 
    dbmodel
-   querydb
    dbiterator
+   dbupdate