api.php

   1 <?php
   2 /*=====================================================================*\
   3 || ###################################################################
   4 || # Iris Studios Shared Object Framework [#]version[#]
   5 || # Copyright ©2002-[#]year[#] Iris Studios, Inc.
   6 || #
   7 || # This program is free software; you can redistribute it and/or modify
   8 || # it under the terms of the GNU General Public License as published by
   9 || # the Free Software Foundation; version [#]gpl[#] of the License.
  10 || #
  11 || # This program is distributed in the hope that it will be useful, but
  12 || # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13 || # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  14 || # more details.
  15 || #
  16 || # You should have received a copy of the GNU General Public License along
  17 || # with this program; if not, write to the Free Software Foundation, Inc.,
  18 || # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  19 || ###################################################################
  20 \*=====================================================================*/
  21
  22 /**
  23 * Abstract Datamanger API
  24 * api.php
  25 *
  26 * @package      ISSO
  27 */
  28
  29 if (!defined('REQ_YES'))
  30 {
  31         /**
  32         * Yes, required
  33         */
  34         define('REQ_YES', 1);
  35
  36         /**
  37         * No, not required
  38         */
  39         define('REQ_NO', 0);
  40
  41         /**
  42         * Auto-increasing value
  43         */
  44         define('REQ_AUTO', -1);
  45
  46         /**
  47         * Set by a cusotm set_*() function
  48         */
  49         define('REQ_SET', 2);
  50 }
  51
  52 /**
  53 * Abstract API
  54 *
  55 * Abstract class that is used as an API base for most common database interaction
  56 * schemes. Creates a simple structure that holds data and can update, delete, and
  57 * insert.
  58 *
  59 * @author               Iris Studios, Inc.
  60 * @copyright    Copyright ©2002 - [#]year[#], Iris Studios, Inc.
  61 * @version              $Revision$
  62 * @package              ISSO
  63 *
  64 */
  65 class API
  66 {
  67         /**
  68         * Registry object
  69         * @var  object
  70         */
  71         var $registry = null;
  72
  73         /**
  74         * Fields: used for verification and sanitization
  75         * NAME => array(TYPE, REQUIRED, VERIFY METHOD (:self for self-named method))
  76         * @var  array
  77         */
  78         var $fields = array();
  79
  80         /**
  81         * Values array: sanitized and verified field values
  82         * @var  array
  83         */
  84         var $values = array();
  85
  86         /**
  87         * Fields that were manually set with set(), not by using set_existing()
  88         * @var  array
  89         */
  90         var $setfields = array();
  91
  92         /**
  93         * WHERE condition
  94         * @var  string
  95         */
  96         var $condition = '';
  97
  98         /**
  99         * The object table row; a fetched row that represents this instance
 100         * @var  array
 101         */
 102         var $objdata = array();
 103
 104         /**
 105         * Insert ID from the insert() command
 106         * @var  integer
 107         */
 108         var $insertid = 0;
 109
 110         /**
 111         * Constructor: cannot instantiate class directly
 112         */
 113         function API(&$registry)
 114         {
 115                 if (!is_subclass_of($this, 'API'))
 116                 {
 117                         trigger_error('Cannot instantiate the API module directly', E_USER_ERROR);
 118                 }
 119
 120                 if (!is_object($registry))
 121                 {
 122                         trigger_error('The passed registry is not an object', E_USER_ERROR);
 123                 }
 124
 125                 $this->registry =& $registry;
 126         }
 127
 128         /**
 129         * Sets a value, sanitizes it, and verifies it
 130         *
 131         * @param        string  Field name
 132         * @param        mixed   Value
 133         * @param        bool    Do clean?
 134         * @param        bool    Do verify?
 135         */
 136         function set($field, $value, $doclean = true, $doverify = true)
 137         {
 138                 if (!isset($this->fields["$field"]))
 139                 {
 140                         trigger_error('Field `' . $field . '` is not valid', E_USER_WARNING);
 141                         return;
 142                 }
 143
 144                 $this->values["$field"] = ($doclean ? $this->registry->clean($value, $this->fields["$field"][0]) : $value);
 145
 146                 $this->setfields[] = $field;
 147
 148                 if (isset($this->fields["$field"][2]) AND $doverify)
 149                 {
 150                         if ($this->fields["$field"][2] == ':self')
 151                         {
 152                                 $verify = $this->{"verify_$field"}($field);
 153                         }
 154                         else
 155                         {
 156                                 $verify = $this->{$this->fields["$field"][2]}($field);
 157                         }
 158
 159                         if (!$verify)
 160                         {
 161                                 // <ERR:CVT>
 162                                 trigger_error('Validation of `' . $field . '` failed', E_USER_ERROR);
 163                         }
 164                 }
 165         }
 166
 167         /**
 168         * Sets the condition to use in the WHERE clause; if not passed, then it calculates it
 169         * from the REQ_AUTO field
 170         *
 171         * @param        string  WHERE conditional bit
 172         */
 173         function set_condition($condition = '')
 174         {
 175                 if ($condition != '')
 176                 {
 177                         $this->condition = $condition;
 178                 }
 179                 else
 180                 {
 181                         foreach ($this->fields AS $name => $options)
 182                         {
 183                                 if ($options[1] == REQ_AUTO)
 184                                 {
 185                                         if (!$this->values["$name"])
 186                                         {
 187                                                 trigger_error('Cannot determine condition from the REQ_AUTO field because it is not set', E_USER_WARNING);
 188                                                 continue;
 189                                         }
 190
 191                                         $this->condition = "$name = " . (($options[0] == TYPE_NOCLEAN OR $options[0] == TYPE_STR) ? "'" . $this->values["$name"] . "'" : $this->values["$name"]);
 192                                 }
 193                         }
 194
 195                         if ($this->condition == '')
 196                         {
 197                                 trigger_error('No REQ_AUTO fields are present and therefore the condition cannot be created', E_USER_WARNING);
 198                         }
 199                 }
 200         }
 201
 202         /**
 203         * Sets existing data into $values where it's not already present
 204         */
 205         function set_existing()
 206         {
 207                 static $run;
 208                 if ($run)
 209                 {
 210                         return;
 211                 }
 212
 213                 $this->fetch();
 214
 215                 foreach ($this->objdata AS $field => $value)
 216                 {
 217                         if (!isset($this->values["$field"]))
 218                         {
 219                                 $this->values["$field"] = $value;
 220                         }
 221                 }
 222
 223                 $run = true;
 224         }
 225
 226         /**
 227         * Fetches a record based on the condition
 228         */
 229         function fetch()
 230         {
 231                 if ($this->condition == '')
 232                 {
 233                         trigger_error('Condition is empty: cannot fetch', E_USER_ERROR);
 234                 }
 235
 236                 $actmethod = (method_exists($this, 'pre_fetch') ? $this->pre_fetch() : '');
 237
 238                 $result = $this->registry->modules['db_mysql']->query_first("SELECT * FROM {$this->prefix}{$this->table} WHERE {$this->condition}");
 239                 if (!$result)
 240                 {
 241                         // <ERR:CVT>
 242                         trigger_error('No record was returned', E_USER_ERROR);
 243                         return;
 244                 }
 245
 246                 $actmethod = (method_exists($this, 'post_fetch') ? $this->post_fetch() : '');
 247
 248                 $this->objdata = $result;
 249         }
 250
 251         /**
 252         * Inserts a record in the database
 253         */
 254         function insert()
 255         {
 256                 $this->verify();
 257
 258                 $actmethod = (method_exists($this, 'pre_insert') ? $this->pre_insert() : '');
 259
 260                 foreach ($this->setfields AS $field)
 261                 {
 262                         $fields[] = $field;
 263                         $values[] = (($this->fields["$field"][0] == TYPE_NOCLEAN OR $this->fields["$field"][0] == TYPE_STR) ? "'" . $this->values["$field"] . "'" : $this->values["$field"]);
 264                 }
 265
 266                 $this->registry->modules['db_mysql']->query("INSERT INTO {$this->prefix}{$this->table} (" . implode(',', $fields) . ") VALUES (" . implode(',', $values) . ")");
 267                 $this->insertid = $this->registry->modules['db_mysql']->insert_id();
 268
 269                 $actmethod = (method_exists($this, 'post_insert') ? $this->post_insert() : '');
 270         }
 271
 272         /**
 273         * Updates a record in the database using the data in $vaues
 274         */
 275         function update()
 276         {
 277                 if ($this->condition == '')
 278                 {
 279                         trigger_error('Condition is empty: cannot fetch', E_USER_ERROR);
 280                 }
 281
 282                 $this->set_existing();
 283                 $this->verify();
 284
 285                 $actmethod = (method_exists($this, 'pre_update') ? $this->pre_update() : '');
 286
 287                 foreach ($this->setfields AS $field)
 288                 {
 289                         $updates[] = "$field = " . (($this->fields["$field"][0] == TYPE_NOCLEAN OR $this->fields["$field"][0] == TYPE_STR) ? "'" . $this->values["$field"] . "'" : $this->values["$field"]);
 290                 }
 291                 $updates = implode(', ', $updates);
 292
 293                 $this->registry->modules['db_mysql']->query("UPDATE {$this->prefix}{$this->table} SET $updates WHERE {$this->condition}");
 294
 295                 $actmethod = (method_exists($this, 'post_update') ? $this->post_update() : '');
 296         }
 297
 298         /**
 299         * Deletes a record
 300         */
 301         function delete()
 302         {
 303                 if ($this->condition == '')
 304                 {
 305                         trigger_error('Condition is empty: cannot fetch', E_USER_ERROR);
 306                 }
 307
 308                 $this->set_existing();
 309
 310                 $actmethod = (method_exists($this, 'pre_delete') ? $this->pre_delete() : '');
 311
 312                 $this->registry->modules['db_mysql']->query("DELETE FROM {$this->prefix}{$this->table} WHERE {$this->condition}");
 313
 314                 $actmethod = (method_exists($this, 'post_delete') ? $this->post_delete() : '');
 315         }
 316
 317         /**
 318         * Verifies that all required fields are set
 319         */
 320         function verify()
 321         {
 322                 foreach ($this->fields AS $name => $options)
 323                 {
 324                         if ($options[1] == REQ_YES)
 325                         {
 326                                 if (!isset($this->values["$name"]))
 327                                 {
 328                                         // <ERR:CVT>
 329                                         trigger_error('Field `' . $name . '` was not set', E_USER_ERROR);
 330                                 }
 331                         }
 332                         else if ($options[1] == REQ_SET)
 333                         {
 334                                 $this->{"set_$name"}();
 335                         }
 336                 }
 337         }
 338
 339         /**
 340         * Verify field: not a zero value
 341         */
 342         function verify_nozero($field)
 343         {
 344                 if ($this->values["$field"] == 0)
 345                 {
 346                         return false;
 347                 }
 348
 349                 return true;
 350         }
 351
 352         /**
 353         * Verify field: not empty
 354         */
 355         function verify_noempty($field)
 356         {
 357                 if (empty($this->values["$field"]))
 358                 {
 359                         return false;
 360                 }
 361
 362                 return true;
 363         }
 364 }
 365
 366 /*=====================================================================*\
 367 || ###################################################################
 368 || # $HeadURL$
 369 || # $Id$
 370 || ###################################################################
 371 \*=====================================================================*/
 372 ?>