Source for file Record.class.php

Documentation is available at Record.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package DB
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Record Interface
  22.  * 
  23.  * This Interface is responsible for representing a database table record.  It
  24.  * provides methods to retrieve record information as well as manipulating the
  25.  * data.  The record can be saved, removed, or a new one created.
  26.  *
  27.  * @category Gumbo
  28.  * @package DB
  29.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  30.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  31.  * @author Michael Luster <mluster79@yahoo.com>
  32.  * @link http://sourceforge.net/projects/phpgumbo
  33.  * @desc Record Interface
  34.  * @version 0.0.1
  35.  */
  36.  
  37. interface Gumbo_Interface_Record {
  38.     
  39.     /**
  40.      * Serialized method
  41.      * @return array 
  42.      */
  43.     public function __sleep ();
  44.     
  45.     /**
  46.      * Unserialized method
  47.      */
  48.     public function __wakeup ();
  49.     
  50.     /**
  51.      * Sets the value of a table column
  52.      * @param string $column 
  53.      * @param mixed $val 
  54.      */
  55.     public function __set ($column, $val);
  56.     
  57.     /**
  58.      * Unsets the value of the supplied table column
  59.      * @param string $column 
  60.      */
  61.     public function __unset ($column);
  62.     
  63.     /**
  64.      * Returns the raw value of the column name
  65.      * @param string $column 
  66.      * @return mixed 
  67.      */
  68.     public function __get ($column);
  69.     
  70.     /**
  71.      * Returns if the Column is set
  72.      * @param string $column 
  73.      * @return bool 
  74.      */
  75.     public function __isset ($column);
  76.     
  77.     
  78.     
  79.     
  80.     
  81.     /** ACTION METHODS **/
  82.     /**
  83.      * Loads the record into memory
  84.      */
  85.     public function load ();
  86.     
  87.     /**
  88.      * Loads an XML string, but only the first level of the parent
  89.      * 
  90.      * @param string $xml 
  91.      * @param string $parent name of top level XML element
  92.      */
  93.     public function loadXML ($xml, $parent=null);
  94.     
  95.     /**
  96.      * Clears the object values, leaves the columns structure
  97.      * @param bool $erase_all clears extra values from memory
  98.      */
  99.     public function unload ($erase_all=false);
  100.     
  101.     
  102.     
  103.     /**
  104.      * Removes the record from the database
  105.      * @precondition isLoaded ()
  106.      * @precondition !isReadOnly ()
  107.      */
  108.     public function kill ();
  109.     
  110.     /**
  111.      * Saves a modified record to the database
  112.      * @precondition isLoaded ()
  113.      * @precondition isModified ()
  114.      * @precondition !isReadOnly ()
  115.      */
  116.     public function save ();
  117.     
  118.     /**
  119.      * Creates a new record in the database
  120.      * @precondition !isLoaded ()
  121.      * @precondition isModified ()
  122.      * @precondition !isReadOnly
  123.      */
  124.     public function create ();
  125.     
  126.     
  127.     
  128.     /**
  129.      * Resets the object by removing the values from the modified array
  130.      */
  131.     public function reset ();
  132.     
  133.     
  134.     
  135.     /** MUTATOR METHODS **/
  136.     /**
  137.      * Sets the object as read only
  138.      * @param bool $val 
  139.      */
  140.     public function setReadOnly ($val);
  141.     
  142.     /**
  143.      * Adds (increments) to the current count columns value
  144.      * @precondition _isColumnCount ($column)
  145.      * @param string $column count column name
  146.      * @param int $num increases by the supplied number
  147.      */
  148.     public function add ($column, $num=1);
  149.     
  150.     /**
  151.      * Wrapper to add() method
  152.      * @param string $column count column name
  153.      * @param int $num increases by the supplied number
  154.      */
  155.     public function increment ($column, $num=1);
  156.     
  157.     /**
  158.      * Subtracts (decrement) one from the count column value
  159.      * @precondition _isColumnCount ($column)
  160.      * @param string $column count column name
  161.      * @param int $num decreases by the supplied number
  162.      * @param bool $allow_negative allows negative values
  163.      */
  164.     public function sub ($column, $num=1, $allow_negative=false);
  165.     
  166.     /**
  167.      * Wrapper to sub() method
  168.      * @param string $column count column name
  169.      * @param int $num decreases by the supplied number
  170.      * @param bool $allow_negative allows negative values
  171.      */
  172.     public function decrement ($column, $num=1, $allow_negative=false);
  173.     
  174.     
  175.     
  176.     /** ACCESSOR METHODS **/
  177.     /**
  178.      * Returns the table name
  179.      * @return string 
  180.      */
  181.     public function getTable ();
  182.     
  183.     /**
  184.      * Returns the primary key name
  185.      * @return string 
  186.      */
  187.     public function getPrimaryKey ();
  188.     
  189.     /**
  190.      * Returns the primary key value
  191.      * @return mixed 
  192.      */
  193.     public function getPrimaryValue ();
  194.     
  195.     /**
  196.      * Returns the value of a column
  197.      * @param string $column Column Name
  198.      * @return mixed 
  199.      */
  200.     public function get ($column);
  201.     
  202.     /**
  203.      * Returns the XML parent element name
  204.      * @return string 
  205.      */
  206.     public function getXMLParent ();
  207.     
  208.     // Table Columns
  209.     /**
  210.      * Returns the entire Columns array
  211.      * @return array 
  212.      */
  213.     public function getAllColumns ();
  214.     
  215.     // Modified table columns
  216.     /**
  217.      * Returns all modified table columns array
  218.      * @return array 
  219.      */
  220.     public function getAllColumnsMod ();
  221.     
  222.     // Extra columns
  223.     /**
  224.      * Returns all the extra columns array
  225.      * @return array 
  226.      */
  227.     public function getAllColumnsExtra ();
  228.     
  229.     // Count Columns
  230.     /**
  231.      * Returns all the count columns
  232.      * @return array 
  233.      */
  234.     public function getAllColumnsCount ();
  235.     
  236.     
  237.     
  238.     /**
  239.      * Returns if the records was loaded
  240.      * @return bool 
  241.      */
  242.     public function isLoaded ();
  243.     
  244.     /**
  245.      * Returns if the record was modified
  246.      * @return bool 
  247.      */
  248.     public function isModified ();
  249.     
  250.     /**
  251.      * Returns if the record accesses the database
  252.      * @return bool 
  253.      */
  254.     public function isReadOnly ();
  255.     
  256.     /**
  257.      * Returns the object as an XML formatted string
  258.      * @param string $parent parent element name
  259.      * @return string 
  260.      */
  261.     public function asXML ($parent=null);
  262.     
  263. }
  264.  
  265. ?>