Source for file dbrow.php

Documentation is available at dbrow.php

  1. <?php
  2. /**
  3. * Database row base class
  4. *
  5. * @author    Stuart Prescott
  6. * @copyright  Copyright Stuart Prescott
  7. * @license    http://opensource.org/licenses/gpl-license.php GNU Public License
  8. * @version    $Id$
  9. * @package    Bumblebee
  10. * @subpackage FormsLibrary
  11. */
  12.  
  13. /** Load ancillary functions */
  14. require_once 'inc/typeinfo.php';
  15. checkValidInclude();
  16.  
  17. /** parent object */
  18. require_once 'dbobject.php';
  19. /** status codes for success/failure of database actions */
  20. require_once 'inc/statuscodes.php';
  21.  
  22.  
  23. /**
  24. * Object representing a database row (and extensible to represent joined rows)
  25. *
  26. * Typical usage:<code>
  27. *   #set database connection parameters
  28. *   $obj = new DBRow("users", 14, "userid");
  29. *   #set the fields required and their attributes
  30. *   $obj->addElement(....);
  31. *   #connect to the database
  32. *   $obj->fill();
  33. *   #check to see if user data changes some values
  34. *   $obj->update($POST);
  35. *   $obj->checkValid();
  36. *   #synchronise with database
  37. *   $obj->sync();</code>
  38. *
  39. * @package    Bumblebee
  40. * @subpackage FormsLibrary
  41. */
  42. class DBRow extends DBO {
  43.   /** @var boolean  this is a new object the form for which has not yet been shown to the user */
  44.   var $newObject = 0;
  45.   /** @var boolean  this row should be inserted into the db */
  46.   var $insertRow = 0;
  47.   /** @var boolean  include all fields in the SQL statement not just ones that have changed or have values  */
  48.   var $includeAllFields = 0;
  49.   /** @var boolean  automatically number new objects (i.e. the database will do it for us) */
  50.   var $autonumbering = 1;
  51.   /** @var string   a restriction that is included in the WHERE statement for all queries  */
  52.   var $restriction = '';
  53.   /** @var string   number of the start record number for a LIMIT statement */
  54.   var $recStart = '';
  55.   /** @var string   number of the stop record number for a LIMIT statement */
  56.   var $recNum   = '';
  57.   /** @var string   do a two-step synchronisation routine whereby the record is created first then updated second */
  58.   var $use2StepSync;
  59.   /** @var array    additional rows to be included at the end of the display table */
  60.   var $extrarows;
  61.   /** @var boolean  row is marked as deleted in the table (but not actually deleted)  */
  62.   var $isDeleted = false;
  63.   /** @var string   this object can be deleted from the table (using DELETE); otherwise set the delete column to 1 for delete */
  64.   var $deleteFromTable = 1;
  65.  
  66.   /**
  67.   *  Create a new database row object
  68.   *
  69.   * @param string $table   name of the table to be used
  70.   * @param integer $id     row id number in the table (-1 for new object)
  71.   * @param string $idfield (optional) the column in the table for the primary key (id)
  72.   */
  73.   function DBRow($table, $id, $idfield='id') {
  74.     $this->DBO($table, $id, $idfield);
  75.     #$this->fields = array();
  76.   }
  77.  
  78.   /**
  79.   * Set the value of the primary key (id) for this object
  80.   *
  81.   * @param integer $newId    the id value to use
  82.   */
  83.   function setId($newId) {
  84.     $this->log('DBRow: setting new id'.$newId);
  85.     $this->id = $newId;
  86.     $this->fields[$this->idfield]->set($this->id);
  87.     foreach (array_keys($this->fields) as $k) {
  88.       if ($this->fields[$k]->notifyIdChange) {
  89.         $this->fields[$k]->idChange($newId);
  90.       }
  91.     }
  92.   }
  93.  
  94.   /**
  95.   *  Update the object with the user-submitted data
  96.   *
  97.   *  update the value of each of the objects fields according to the user
  98.   *  input data, and validate the data if appropriate
  99.   *  @param array user supplied data (field => $value)
  100.   *  @return boolean data is valid
  101.   */
  102.   function update($data) {
  103.     $this->log('DBRow:'.$this->namebase.' Looking for updates:');
  104.     // First, check to see if this record is new
  105.     if ($this->id == -1 && ! $this->ignoreId) {
  106.       $this->insertRow = 1;
  107.     }
  108.  
  109.     // We're a new object, but has the user filled the form in, or is the
  110.     // user about to fill the form in?
  111.     $this->newObject = 1;
  112.     foreach (array_keys($this->fields) as $k) {
  113.       if ($k != $this->idfield && isset($data[$this->namebase.$k]) && ! $this->fields[$k]->hidden) {
  114.         $this->log('I AM NOT NEW '.$k.':changed');
  115.         $this->newObject = 0;
  116.         break;
  117.       }
  118.     }
  119.  
  120.     // check each field in turn to allow it to update its data
  121.     foreach (array_keys($this->fields) as $k) {
  122.       $this->log("Check $k ov:".$this->fields[$k]->value
  123.                             .'('.$this->fields[$k]->useNullValues .'/'. $this->newObject.')');
  124.       if (!($this->fields[$k]->useNullValues && $this->newObject)) {
  125.         $this->changed += $this->fields[$k]->update($data);
  126.       }
  127.       $this->log('nv:'.$this->fields[$k]->value.' '.($this->changed ? 'changed' : 'not changed'));
  128.     }
  129.     #$this->checkValid();
  130.     return $this->changed;
  131.   }
  132.  
  133.   /**
  134.   * check the validity of the data
  135.   * @return boolean data is valid
  136.   */
  137.   function checkValid() {
  138.     $this->isValid = 1;
  139.     // check each field in turn to allow it to update its data
  140.     // if this object has not been filled in by the user, then
  141.     // suppress validation
  142.     foreach (array_keys($this->fields) as $k) {
  143.       if (! ($this->newObject && $this->insertRow)) {
  144.         $this->log('Checking valid '.$this->fields[$k]->namebase . $k);
  145.         if (! $this->fields[$k]->isValid()) {
  146.           $this->errorMessage .= T_('Invalid data:').' '.$this->fields[$k]->longname
  147.                                     .'('.$this->fields[$k]->name.')'
  148.                                   .' = "'. $this->fields[$k]->getValue() .'"<br />';
  149.           $this->isValid = false;
  150.         }
  151.       }
  152.     }
  153.     if (! $this->isValid) {
  154.       $this->errorMessage .= '<br />'
  155.           .T_('Some values entered into the form are not valid and should be highlighted in the form below. Please check your data entry and try again.');
  156.     }
  157.     return $this->isValid;
  158.   }
  159.  
  160.   /**
  161.   * Synchronise this object's fields with the database
  162.   *
  163.   * If the object is new, then INSERT the data, if the object is pre-existing
  164.   * then UPDATE the data. Fancier fields that are only pretending to
  165.   * do be simple fields (such as JOINed data) should perform their updates
  166.   * during the _sqlvals() call
  167.   *
  168.   * @return integer  from statuscodes
  169.   */
  170.   function sync() {
  171.     global $TABLEPREFIX;
  172.     // If the input isn't valid then bail out straight away
  173.     if (! $this->changed) {
  174.       $this->log('not syncing: changed='.$this->changed);
  175.       return STATUS_NOOP;
  176.     } elseif (! $this->isValid) {
  177.       $this->log('not syncing: valid='.$this->isValid);
  178.       return STATUS_ERR;
  179.     }
  180.     $this->log('syncing: changed='.$this->changed.' valid='.$this->isValid);
  181.     if ($this->use2StepSync) {
  182.       $this->log('starting two-step sync');
  183.       $this->_twoStageSync();
  184.     }
  185.     $sql_result = STATUS_NOOP;
  186.     //obtain the *clean* parameter='value' data that has been SQL-cleansed
  187.     //this will also trip any complex fields to sync
  188.     $vals = $this->_sqlvals($this->insertRow || $this->includeAllFields);
  189.     if ($vals != '') {
  190.       //echo "changed with vals=$vals<br/>";
  191.       if (! $this->insertRow) {
  192.         //it's an existing record, so update
  193.         $q = 'UPDATE '.$TABLEPREFIX.$this->table
  194.             .' SET '.$vals
  195.             .' WHERE '.$this->idfield.'='.qw($this->id)
  196.             .(($this->restriction !== '') ? ' AND '.$this->restriction : '')
  197.             .' LIMIT 1';
  198.         $sql_result = db_quiet($q, $this->fatal_sql);
  199.       } else {
  200.         //it's a new record, insert it
  201.         $q = 'INSERT '.$TABLEPREFIX.$this->table.' SET '.$vals;
  202.         $sql_result = db_quiet($q, $this->fatal_sql);
  203.         # FIXME: do we need to check that this was successful in here?
  204.         if ($this->autonumbering) {
  205.           //the record number can now be copied into the object's data.
  206.           $this->setId(db_new_id());
  207.         }
  208.         $this->insertRow = 0;
  209.       }
  210.     }
  211.     $this->errorMessage .= $this->oob_errorMessage;
  212.     //echo "sql=$sql_result, oob=$this->oob_status\n";
  213.     return $sql_result | $this->oob_status;
  214.   }
  215.  
  216.   /**
  217.   * An alternative way of synchronising this object's fields with the database.
  218.   *
  219.   * Using this approach, we:
  220.   *   - If the object is new, then INSERT a temp row first.
  221.   *   - Then, trip the sqlvals() calls.
  222.   *   - Then, UPDATE the data.
  223.   *
  224.   * Here, we to the 'create temp row' part.
  225.   */
  226.   function _twoStageSync() {
  227.     if ($this->id == -1) {
  228.       $row = new DBRow($this->table, -1, 'id');
  229.       $f = new Field($this->idfield);
  230.       $f->value = -1;
  231.       $row->addElement($f);
  232.       foreach ($this->fields as $field) {
  233.         if ($field->requiredTwoStage) {
  234.           $row->addElement(clone($field));
  235.         }
  236.       }
  237.       $row->isValid = 1;
  238.       $row->changed = 1;
  239.       $row->insertRow = 1;
  240.       $row->sync();
  241.       if ($this->autonumbering) {
  242.         //the record number can now be copied into the object's data.
  243.         $this->setId($row->id);
  244.       }
  245.       $this->insertRow = 0;
  246.       $this->log('Created temp row for locking, id='.$this->id.')');
  247.     }
  248.   }
  249.  
  250.   /**
  251.   * Delete this object's row from the database.
  252.   *
  253.   * @param mixed (optional) string or array of column => value added to the UPDATE statement objects are only to be marked as deleted not actually deleted.
  254.   * @return integer from statuscodes
  255.   */
  256.   function delete($extraUpdates=NULL) {
  257.     global $TABLEPREFIX;
  258.     if ($this->id == -1) {
  259.       // nothing to do
  260.       $this->log('$id == -1, so nothing to do');
  261.       return STATUS_NOOP;
  262.     }
  263.     if (! $this->deletable) {
  264.       $this->log('Object not deletable by rule.');
  265.       $this->errorMessage = T_('Cannot delete this item. Permission denied.');
  266.       return STATUS_FORBIDDEN;
  267.     }
  268.     $sql_result = -1;
  269.     if ($this->deleteFromTable) {
  270.       $q = 'DELETE FROM '.$TABLEPREFIX.$this->table
  271.           .' WHERE '.$this->idfield.'='.qw($this->id)
  272.           .(($this->restriction !== '') ? ' AND '.$this->restriction : '')
  273.           .' LIMIT 1';
  274.     } else {
  275.       $updates = array();
  276.       if (is_array($extraUpdates)) {
  277.         $updates = array_merge($updates, $extraUpdates);
  278.       } elseif ($extraUpdates !== NULL) {
  279.         $updates[] = $extraUpdates;
  280.       }
  281.       // toggle the deleted state
  282.       $updates[] = 'deleted='.($this->isDeleted?0:1); // old MySQL cannot handle true, use 0,1 instead
  283.       $q = 'UPDATE '.$TABLEPREFIX.$this->table
  284.           .' SET '.join($updates, ', ')
  285.           .' WHERE '.$this->idfield.'='.qw($this->id)
  286.           .(($this->restriction !== '') ? ' AND '.$this->restriction : '')
  287.           .' LIMIT 1';
  288.     }
  289.     #$this->log($q);
  290.     $sql_result = db_quiet($q, $this->fatal_sql);
  291.     return $sql_result;
  292.   }
  293.  
  294.   /**
  295.   * Generate name='value' data for the SQL statement
  296.   *
  297.   * @param boolean $force (optional) force all fields to be included
  298.   * @return string of data statements
  299.   */
  300.   function _sqlvals($force=0) {
  301.     $vals = array();
  302.     foreach (array_keys($this->fields) as $k) {
  303.       if ($this->fields[$k]->changed || $force) {
  304.         //obtain a string of the form "name='Stuart'" from the field.
  305.         //Complex fields can use this as a JIT syncing point, and may
  306.         //choose to return nothing here, in which case their entry is
  307.         //not added to the return list for the row
  308.         $this->log('Getting SQL string for '.$this->fields[$k]->name, 8);
  309.         $sqlval = $this->fields[$k]->sqlSetStr('', $force);
  310.         #echo "$k,oob = '".$this->fields[$k]->oob_status."' ";
  311.         $this->oob_status |= $this->fields[$k]->oob_status;
  312.         $this->oob_errorMessage .= $this->fields[$k]->oob_errorMessage;
  313.         if ($sqlval) {
  314.           #echo "SQLUpdate: '$sqlval' <br />";
  315.           $vals[] = $sqlval;
  316.         }
  317.         #$vals[] = "$k=" . qw($v->value);
  318.       }
  319.     }
  320.     #echo "<pre>"; print_r($vals); echo "</pre>";
  321.     return join(', ',$vals);
  322.   }
  323.  
  324.   /**
  325.   * Add a new field to the row
  326.   *
  327.   * Add an element into the fields[] array. The element must conform
  328.   * to the Fields class (or at least its interface!) as that will be
  329.   * assumed elsewhere in this object.
  330.   * Inheritable attributes are also set here.
  331.   *
  332.   * @param Field $el the field to add
  333.   */
  334.   function addElement($el) {
  335.     $this->fields[$el->name] = $el;
  336.     if ($this->fields[$el->name]->editable == -1) {
  337.       $this->fields[$el->name]->editable = $this->editable;
  338.     }
  339.     if (! isset($this->fields[$el->name]->namebase)) {
  340.       $this->fields[$el->name]->namebase = $this->namebase;
  341.       #echo "Altered field $el->name to $this->namebase\n";
  342.     }
  343.     if ($this->fields[$el->name]->suppressValidation == -1) {
  344.       $this->fields[$el->name]->suppressValidation = $this->suppressValidation;
  345.       #echo "Altered field $el->name to $this->namebase\n";
  346.     }
  347.     #echo $el->name;
  348.     #echo "foo:".$this->fields[$el->name]->name.":bar";
  349.   }
  350.  
  351.   /**
  352.   * Add multiple new fields to the row
  353.   *
  354.   * Adds multiple elements into the fields[] array.
  355.   *
  356.   * @param array $els array of Field objects
  357.   */
  358.   function addElements($els) {
  359.     foreach ($els as $e) {
  360.       #echo $e->text_dump();
  361.       $this->addElement($e);
  362.     }
  363.   }
  364.  
  365.   /**
  366.   * Perform the SQL lookup to fill the object with the current data
  367.   *
  368.   * Fill this object (i.e. its fields) from the SQL query
  369.   * @global string  prefix for table names
  370.   */
  371.   function fill() {
  372.     global $TABLEPREFIX;
  373.     //echo "foo:$this->id:bar";
  374.     if (($this->id !== NULL && $this->id !== '' && $this->id != -1) || $this->ignoreId) {
  375.       //FIXME: can we do this using quickSQLSelect()?
  376.       $where = array();
  377.       if (! $this->ignoreId) {
  378.         $where[] = $this->idfield.'='.qw($this->id);
  379.       }
  380.       if (is_array($this->restriction)) {
  381.         $where = array_merge($where, $this->restriction);
  382.       } elseif ($this->restriction !== '') {
  383.         $where[] = $this->restriction;
  384.       }
  385.       $q = 'SELECT * FROM '
  386.           .$TABLEPREFIX.$this->table .' AS '. $this->table
  387.           .' WHERE '.join($where, ' AND ')
  388.           .(($this->recStart !== '') && ($this->recNum !== '')
  389.                           ? " LIMIT $this->recStart,$this->recNum" : '');
  390.       $g = db_get_single($q);
  391.       if (is_array($g)) {
  392.         foreach (array_keys($this->fields) as $k) {
  393.           if (! $this->fields[$k]->sqlHidden) {
  394.             $val = issetSet($g,$k);
  395.             $this->fields[$k]->set($val);
  396.           }
  397.         }
  398.         $this->isDeleted = issetSet($g, 'deleted', false);
  399.       } else {
  400.         $this->insertRow = $this->ignoreId;
  401.       }
  402.     }
  403.     if ($this->ignoreId) {
  404.       $this->id = $this->fields[$this->idfield]->value;
  405.     } else {
  406.       //we have to have an id present otherwise we're in trouble next time
  407.       $this->fields[$this->idfield]->set($this->id);
  408.     }
  409.   }
  410.  
  411.   function fillWithDefaults() {
  412.     #echo "Filling with defaults";
  413.     foreach (array_keys($this->fields) as $k) {
  414.       #echo get_class($this->fields[$k]);
  415.       #echo '"'.$this->fields[$k]->defaultValue.'"';
  416.       $this->fields[$k]->set($this->fields[$k]->defaultValue);
  417.     }
  418.   }
  419.  
  420.   /**
  421.   * Quick and dirty dump of fields (values only, not a full print_r
  422.   */
  423.   function text_dump() {
  424.     $t  = "<pre>$this->dumpheader $this->table (id=$this->id)\n{\n";
  425.     foreach ($this->fields as $v) {
  426.       $t .= "\t".$v->text_dump();
  427.     }
  428.     $t .= "}\n</pre>";
  429.     return $t;
  430.   }
  431.  
  432.   function display() {
  433.     return $this->text_dump();
  434.   }
  435.  
  436.   /**
  437.   * Display the row as a form in a table
  438.   *
  439.   * @param integer $j      (optional) number of columns in the table (will pad as necessary)
  440.   * @return string  html table
  441.   */
  442.   function displayInTable($j) {
  443.     $t = '<table class="tabularobject">';
  444.     foreach ($this->fields as $v) {
  445.       $t .= $v->displayInTable($j);
  446.     }
  447.     $t .= '</table>';
  448.     if (is_array($this->extrarows)) {
  449.       foreach ($this->extrarows as $v) {
  450.         $t .= '<tr>';
  451.         foreach ($v as $c) {
  452.           $t .= '<td>'.$c.'</td>';
  453.         }
  454.         $t .= '</tr>';
  455.       }
  456.     }
  457.     return $t;
  458.   }
  459.  
  460.   function displayAsTable($cols=2) {
  461.     return $this->displayInTable($cols);
  462.   }
  463.  
  464.  
  465.   /**
  466.   * PHP5 clone method
  467.   *
  468.   * PHP5 clone statement will perform only a shallow copy of the object. Any subobjects must also be cloned
  469.   */
  470.   function __clone() {
  471.     parent::__clone();
  472.   }
  473.  
  474. } // class dbrow
  475.  
  476. ?>

Documentation generated on Tue, 06 Mar 2007 10:01:22 +0000 by phpDocumentor 1.3.0