example: add example of how to use Db get_one() & get_many() helpers

example/includes/db.php

@@ -22,22 +22,16 @@ $db = new Db(
 function get_items($orderby='id', $raw_values=false) {
   global $db;
   try {
-    $query = $db -> fpdo -> from('item')
-      -> orderBy($orderby);
+    $info = $db -> get_many('item', null, null, $orderby);
+    if (!is_array($info))
+      return;
+    if ($raw_values)
+      return $info;
 
-    $result = $query -> execute();
-    if ($result !== false) {
-      $info = $result -> fetchAll();
-      if ($info === false)
-        return null;
-      if ($raw_values)
-        return $info;
-
-      $items = array();
-      foreach ($info as $item)
-        $items[$item['id']] = $db -> format_row_info($item, array('date'));
-      return $items;
-    }
+    $items = array();
+    foreach ($info as $item)
+      $items[$item['id']] = $db -> format_row_info($item, array('date'));
+    return $items;
   }
   catch (Exception $e) {
     Log :: error("Error retreiving items info from database : ".$e->getMessage());
@@ -48,19 +42,15 @@ function get_items($orderby='id', $raw_values=false) {
 function get_item($id, $raw_values=false) {
   global $db;
   try {
-    $query = $db -> fpdo -> from('item')
-      -> where('id', $id);
+    $info = $db -> get_one('item', array('id' => $id));
 
-    $result = $query -> execute();
-    if ($result !== false) {
-      $info = $result -> fetch();
-      if ($info === false)
-        return null;
-      if ($raw_values)
-        return $info;
+    if (!is_array($info))
+      return false;
 
-      return $db -> format_row_info($info, array('date'));
-    }
+    if ($raw_values)
+      return $info;
+
+    return $db -> format_row_info($info, array('date'));
   }
   catch (Exception $e) {
     Log :: error("Error retreiving item #$id info from database : ".$e->getMessage());

src/Db.php

@@ -113,6 +113,189 @@ class Db {
     $this -> pdo -> setAttribute(PDO::ATTR_AUTOCOMMIT, $value);
   }
 
+  /*
+   * Simple request helpers
+   */
+
+  /**
+   * Helper to retreive one row from a table of the database
+   * @param string $table              The table name
+   * @param array|string $where        WHERE clause(s) as expected by Envms\FluentPDO\Query
+   * @param array|string|null $fields  The expected fields as string (separeted by comma) or an
+   *                                   array (optional, default: all table fields will be returned)
+   * @return array|false
+   */
+  public function get_one($table, $where, $fields=null) {
+    try {
+      $query = $this -> fpdo -> from($table) -> where($where);
+      if ($fields)
+        $query -> select(null) -> select($fields);
+      if ($query->execute() === false)  // @phpstan-ignore-line
+        return false;
+      $return = $query->fetchAll();
+      if (is_array($return) && count($return) == 1)
+        return $return[0];
+    }
+    catch (Exception $e) {
+      Log :: error(
+        "Error occured getting one row of the table %s in database (where %s): %s",
+        $table,
+        is_array($where)?
+        preg_replace("/\n */", " ", print_r($where, true)):
+        vardump($where),
+        $e->getMessage()
+      );
+    }
+    return false;
+  }
+
+
+  /**
+   * Helper to retreive multiple rows from a table of the database
+   * @param string $table              The table name
+   * @param array|string $where        WHERE clause(s) as expected by Envms\FluentPDO\Query
+   * @param array|string|null $fields  The expected fields as string (separeted by comma) or an
+   *                                   array (optional, default: all table fields will be returned)
+   * @param string|null $order_by      An optional ORDER clause as a string
+   * @param string|null $limit         An optional LIMIT clause as a string
+   * @return array|false
+   */
+  public function get_many(
+    $table, $where=null, $fields=null, $order_by=null, $limit=null
+  ) {
+    try {
+      $query = $this -> fpdo -> from($table);
+      if ($fields)
+        $query -> select(null) -> select($fields);
+      if ($where)
+        $query -> where($where);
+      if ($order_by)
+        $query -> orderBy($order_by);
+      if ($query->execute() === false)  // @phpstan-ignore-line
+        return false;
+      $return = $query->fetchAll();
+      if (is_array($return))
+        return $return;
+    }
+    catch (Exception $e) {
+      Log :: error(
+        "Error occured getting rows of the table %s in database (where %s): %s",
+        $table,
+        is_array($where)?
+        preg_replace("/\n */", " ", print_r($where, true)):
+        vardump($where),
+        $e->getMessage()
+      );
+    }
+    return false;
+  }
+
+  /**
+   * Helper to insert a row in a table
+   * @param string               $table    The table name
+   * @param array<string,mixed>  $values   The values of the row
+   * @param boolean $want_id  Set to true if you want to retreive the ID of the inserted row
+   * @return bool|int The ID of the inserted row if $want_id, or true/false in case of success/error
+   */
+  public function insert($table, $values, $want_id=false) {
+    try {
+      $id = $this -> fpdo -> insertInto($table)
+        -> values($values)
+        -> execute();
+    }
+    catch (Exception $e) {
+      Log :: error(
+        "Error occured inserting row in the table %s of the database: %s\nValues:\n%s",
+        $table,
+        $e->getMessage(),
+        vardump($values)
+      );
+      return false;
+    }
+    if ($id !== false) {
+      Log::debug('Row insert in table %s with ID #%s', $table, $id);
+      return $want_id?$id:true;
+    }
+    return false;
+  }
+
+  /**
+   * Helper to update a row in database
+   * @param string $table                         The table name
+   * @param array<string,mixed> $changes          Associative array of changes
+   * @param array|string $where                   WHERE clause(s) as expected by Envms\FluentPDO\Query
+   * @param null|int|false $expected_row_changes  The number of expected row affected by the query
+   *                                              or false if you don't want to check it (optional,
+   *                                              default: null == 1)
+   * @return bool
+   */
+  public function update($table, $changes, $where, $expected_row_changes=null) {
+    if (is_null($expected_row_changes)) $expected_row_changes = 1;
+    try {
+      $result = $this -> fpdo -> update($table)
+        -> set($changes)
+        -> where($where)
+        -> execute();
+    }
+    catch (Exception $e) {
+      Log :: error(
+        "Error occured updating %s in the table %s of the database (where %s): %s\nChanges:\n%s",
+        $expected_row_changes == 1?'row':'rows',
+        $table,
+        is_array($where)?
+        preg_replace("/\n */", " ", print_r($where, true)):
+        vardump($where),
+        $e->getMessage(),
+        vardump($changes)
+      );
+      return false;
+    }
+    if (!is_int($result))
+      return false;
+    if ($expected_row_changes === false)
+      return true;
+    return $expected_row_changes == $result;
+  }
+
+  /**
+   * Helper to delete one or multiple rows in a table of the database
+   * @param string $table                         The table name
+   * @param array|string $where                   WHERE clause(s) as expected by Envms\FluentPDO\Query
+   * @param null|int|false $expected_row_changes  The number of expected row affected by the query
+   *                                              or false if you don't want to check it (optional,
+   *                                              default: null == 1)
+   * @return bool
+   */
+  public function delete($table, $where, $expected_row_changes=null) {
+    if (is_null($expected_row_changes)) $expected_row_changes = 1;
+    try {
+      $result = $this -> fpdo -> deleteFrom($table)
+        -> where($where)
+        -> execute();
+    }
+    catch (Exception $e) {
+      Log :: error(
+        "Error occured deleting %s in the table %s of the database (where %s): %s",
+        $expected_row_changes == 1?'one row':'some rows',
+        $table,
+        is_array($where)?
+        preg_replace("/\n */", " ", print_r($where, true)):
+        vardump($where),
+        $e->getMessage()
+      );
+      return false;
+    }
+    // Bad return type declared in \Envms\FluentPDO\Queries\Delete
+    // @phpstan-ignore-next-line
+    if (!is_int($result))
+      return false;
+    // @phpstan-ignore-next-line
+    if ($expected_row_changes === false)
+      return true;
+    return $expected_row_changes == $result;
+  }
+
+
   /*
    * Handle date/datetime format
    */