From 597c487cb99caf6398ea98b71005ac0e43ca24a0 Mon Sep 17 00:00:00 2001
From: Remi Collet <fedora@famillecollet.com>
Date: Mon, 7 Jun 2010 02:57:48 +0800
Subject: add some docs

---
 class/CommonTable.php | 63 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 8 deletions(-)

diff --git a/class/CommonTable.php b/class/CommonTable.php
index 721a224..66e1c27 100644
--- a/class/CommonTable.php
+++ b/class/CommonTable.php
@@ -37,6 +37,12 @@ abstract class CommonTable {
     protected $db;
     protected $table;
 
+    /**
+     * Instanciate a CommonTable
+     *
+     * @param $db object PDO instance of the DB connection
+     * @param $table string with table name
+     */
     function __construct(PDO $db, $table) {
 
         $this->db = $db;
@@ -47,6 +53,13 @@ abstract class CommonTable {
         }
     }
 
+    /**
+     * Check if the table already exists
+     *
+     * @param $table string with table name
+     *
+     * @return boolean
+     */
     public function existsTable($table) {
         $req = new TableIterator($this->db, "SHOW TABLES LIKE '$table'");
         foreach ($req as $data) {
@@ -55,6 +68,11 @@ abstract class CommonTable {
         return false;
     }
 
+    /**
+     * Execute an SQL statement (INSERT, DELETE, ...)
+     *
+     * @param $sql string
+     */
     protected function exec($sql) {
         $res = $this->db->exec($sql);
         if ($res===false) {
@@ -63,6 +81,11 @@ abstract class CommonTable {
         }
     }
 
+    /**
+     * Add a new row in the table
+     *
+     * @param fields hashtable of fieldname => value
+     */
     protected function add(array $fields) {
         $col = array();
         $val = array();
@@ -80,19 +103,21 @@ abstract class CommonTable {
                 VALUE (".implode(',',$val).")";
         $this->exec($sql);
     }
+
+    /**
+     * Create the table
+     */
     abstract protected function createTable();
 
     /**
-     * Instanciate a Simple DBIterator
+     * Instanciate a Simple TableIterator on the current table
      *
      * Examples =
-     *  foreach ($DB->request("select * from glpi_states") as $data) { ... }
-     *  foreach ($DB->request("glpi_states") as $ID => $data) { ... }
-     *  foreach ($DB->request("glpi_states", "ID=1") as $ID => $data) { ... }
-     *  foreach ($DB->request("glpi_states", "", "name") as $ID => $data) { ... }
-     *  foreach ($DB->request("glpi_computers",array("name"=>"SBEI003W","entities_id"=>1),array("serial","otherserial")) { ... }
+     *  foreach ($DB->request() as $ID => $data) { ... }
+     *  foreach ($DB->request("ID=1") as $ID => $data) { ... }
+     *  foreach ($DB->request("", "name") as $ID => $data) { ... }
+     *  foreach ($DB->request(array("name"=>"SBEI003W","entities_id"=>1),array("serial","otherserial")) { ... }
      *
-     * @param $tableorsql table name, array of names or SQL query
      * @param $crit string or array of field/values, ex array("id"=>1), if empty => all rows
      *
      * Examples =
@@ -111,6 +136,14 @@ abstract class CommonTable {
         return new TableIterator ($this->db, $this->table, $crit);
     }
 
+    /**
+     * Retrieve 2 columns of all the table's row in a hashtable
+     *
+     * @param $fieldkey string name of the field to use as index
+     * @param $fieldvalue string name of the field to use as value
+     *
+     * @return hashtable
+     */
     public function getAllArray($fieldkey, $fieldvalue) {
         $crit = array('FIELDS'  => array($fieldkey, $fieldvalue),
                       'ORDER'   => $fieldkey);
@@ -124,10 +157,16 @@ abstract class CommonTable {
 
 class TablePearRepo extends CommonTable {
 
+    /**
+     * Instanciate a TablePearRepo to manage pearrepo table
+     */
     function __construct($db) {
         parent::__construct($db, 'pearrepo');
     }
 
+    /**
+     * Create the table and populate it with known repo
+     */
     protected function createTable() {
 
         // Table schema
@@ -160,13 +199,18 @@ class TablePearRepo extends CommonTable {
         }
     }
 
+    /**
+     * Retrieve all the known repository
+     *
+     * @return hastable of alias => url
+     */
     function getAllRepo() {
         return $this->getAllArray('alias', 'url');
     }
 }
 
 /*
- * Helper for simple query => see $DBmysql->requete
+ * Helper for simple query => use directly or through  CommonTable::request()
  */
 class TableIterator  implements Iterator {
 
@@ -272,6 +316,9 @@ class TableIterator  implements Iterator {
         }
     }
 
+    /**
+     * Build WHERE clause
+     */
     private function analyseCrit ($crit, $bool="AND") {
 
         if (!is_array($crit)) {
-- 
cgit