Source for file Collection.class.php

Documentation is available at Collection.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 Collection
  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.  * Standard Collection Class
  22.  *
  23.  * @category Gumbo
  24.  * @package Collection
  25.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  26.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  27.  * @author Michael Luster <mluster79@yahoo.com>
  28.  * @link http://sourceforge.net/projects/phpgumbo
  29.  * @desc Standard Collection Class
  30.  * @version 0.0.1
  31.  */
  32.  
  33. gumbo_load ("Interface_Collection");
  34.  
  35. class Gumbo_Collection implements Gumbo_Interface_Collection, IteratorAggregate {
  36.     
  37.     /** @var string $_type type of class|interface supplied objects must be */
  38.     private $_type = "StdClass";
  39.     /** @var array $_list array list of the objects that are part of the Collection */
  40.     private $_list = array ();
  41.     
  42.     /** @var string|array$_callback callback function/method that loads values into the Collection */
  43.     private $_callback;
  44.     /** @var array $_params callback function parameters */
  45.     private $_params = array ();
  46.     /** @var bool $_loaded tells if the Collection has been loaded */
  47.     private $_loaded = false;
  48.     
  49.     
  50.     
  51.     /**
  52.      * Constructor (extra arguments sent to callback as is)
  53.      * @param string $func callback function/method name
  54.      * @param string|StdClass$cls callback class name or object
  55.      */
  56.     public function __construct ($func=null, $cls=null) {
  57.         // checking for additional parameters on the callback function
  58.         $args = array ();
  59.         if (func_num_args () > 2) {
  60.             foreach (func_get_args () as $key=>$val) {
  61.                 if ($key <= 1) { continue; }
  62.                 $args [] = $val;
  63.             }
  64.         }
  65.         if (!is_null ($func)) { $this->setCallback ($func, $cls); }
  66.         $this->_params = $args;
  67.     }
  68.     
  69.     
  70.     
  71.     /** OVERLOADED METHODS **/
  72.     /**
  73.      * Returns Data (wrapper to get())
  74.      * @param int|string$key for integers, use $list->{$num}
  75.      * @return mixed 
  76.      */
  77.     public function __get ($key) {
  78.         return $this->get ($key);
  79.     }
  80.     
  81.     /**
  82.      * Sets Data (wrapper to add())
  83.      * @param int|string$key 
  84.      * @param mixed $data 
  85.      */
  86.     public function __set ($key, $data) {
  87.         $this->add ($data, $key);
  88.     }
  89.     
  90.     /**
  91.      * Returns if key is set (wrapper to exists())
  92.      * @param int|string$key 
  93.      * @return bool 
  94.      */
  95.     public function __isset ($key) {
  96.         return $this->exists ($key);
  97.     }
  98.     
  99.     /**
  100.      * Removes Data (wrapper to remove())
  101.      * @param int|string$key 
  102.      */
  103.     public function __unset ($key) {
  104.         $this->remove ($key);
  105.     }
  106.     
  107.     
  108.     
  109.     /** ACTION METHODS **/
  110.     /**
  111.      * Adds an Object to the Collection
  112.      * @param StdClass $obj 
  113.      * @param string|int$key key reference name
  114.      * @throws Gumbo_Exception
  115.      */
  116.     public function add ($data, $key=null) {
  117.         try {
  118.             // verify preconditions
  119.             if (!is_object ($data)) {
  120.                 throw new Gumbo_Exception ("Invalid Argument 'data:obj' => {$data}:" . gettype ($data));
  121.             }
  122.             if (!is_null ($key) && (!is_string ($key) && !is_numeric ($key))) {
  123.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str|null' => {$key}:" . gettype ($key));
  124.             }
  125.             if (is_numeric ($key)) { $key = (int) $key; }
  126.             
  127.             $type = $this->getType ();
  128.             if (!($data instanceof $type)) {
  129.                 throw new Gumbo_Exception ("Invalid Class|Interface ({$type}): " . get_class ($data));
  130.             } 
  131.             
  132.             // run callback function
  133.             $this->_onload ();
  134.             
  135.             // add new Object
  136.             if (!is_null ($key)) {
  137.                 $this->_list [$key] = $data;
  138.             } else {
  139.                 // automatically set a new Object
  140.                 $this->_list [] = $data;
  141.             }
  142.         } catch (Gumbo_Exception $e) {
  143.             $e->setFunction (__METHOD__);
  144.             gumbo_trigger ($e);
  145.         }
  146.     }
  147.     
  148.     /**
  149.      * Removes an Object from the Collection
  150.      * @param int|string$key key name
  151.      * @throws Gumbo_Exception
  152.      */
  153.     public function remove ($key) {
  154.         try {
  155.             // verify precondition
  156.             if (!is_string ($key) && !is_numeric ($key)) {
  157.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str' => {$key}:" . gettype ($key));
  158.             }
  159.             if (is_numeric ($key)) { $key = (int) $key; }
  160.             
  161.             // run callback function
  162.             $this->_onload ();
  163.             
  164.             // check if the key exists
  165.             if (!$this->exists ($key)) {
  166.                 throw new Gumbo_Exception ("Collection Key Undefined: {$key}");
  167.             }
  168.             
  169.             unset ($this->_list [$key]);
  170.         } catch (Gumbo_Exception $e) {
  171.             $e->setFunction (__METHOD__);
  172.             gumbo_trigger ($e);
  173.         }
  174.     }
  175.     
  176.     /**
  177.      * Removes a value from the List (not used)
  178.      * @param mixed $data 
  179.      */
  180.     public function removeValue ($data) {
  181.         return;
  182.     }
  183.     
  184.     /**
  185.      * Resets the List (not used)
  186.      * @postcondition !size()
  187.      */
  188.     public function reset () {
  189.         return;
  190.     }
  191.     
  192.     
  193.     
  194.     /** MUTATOR METHODS **/
  195.     /**
  196.      * Sets the type of class|interface of the Collection
  197.      * @param string $type 
  198.      * @throws Gumbo_Exception
  199.      */
  200.     public function setType ($type) {
  201.         try {
  202.             // verify precondition
  203.             if (!is_string ($type)) {
  204.                 throw new Gumbo_Exception ("Invalid Argument 'type:str' => {$type}:" . gettype ($type));
  205.             }
  206.             if (!class_exists ($type, false) && !interface_exists ($type, false)) {
  207.                 throw new Gumbo_Exception ("Class|Interface Undefined: {$type}");
  208.             }
  209.             
  210.             $this->_type = $type;
  211.         } catch (Gumbo_Exception $e) {
  212.             $e->setFunction (__METHOD__);
  213.             gumbo_trigger ($e);
  214.         }
  215.     }
  216.     
  217.     /**
  218.      * Sets the callback function/method (extra arguments will be sent to callback as is)
  219.      * 
  220.      * The callback function will be called to load the contents of the
  221.      * Collection.  The value could be a function name or a class method. A
  222.      * callback function/method should define a single argument, the
  223.      * Collection.  When the callback is executed, the Collection will
  224.      * pass itself (by reference) to the function.  The callback will
  225.      * set the values of the Collection.
  226.      * 
  227.      * To set a function:
  228.      * <code>$coll->setCallback ("function_name");</code>
  229.      * 
  230.      * To set a class/object method (3 methods):
  231.      * <code>
  232.      * $col->setCallback ("method_name", "class_name");
  233.      * // substitute an Object ($obj) for "class_name" if necessary
  234.      * </code>
  235.      * 
  236.      * @precondition function/method callable
  237.      * @param string $name function/method name (array should be (0=>"class",1=>"method"))
  238.      * @param string|StdClass$obj class name or Object reference
  239.      * @throws Gumbo_Exception
  240.      */
  241.     public function setCallback ($name, $obj=null) {
  242.         try {
  243.             // verify preconditions
  244.             if (!is_string ($name)) {
  245.                 throw new Gumbo_Exception ("Invalid Argument 'name:str' => {$name}:" . gettype ($name));
  246.             }
  247.             if (!is_null ($obj) && !is_string ($obj) && !is_object ($obj)) {
  248.                 throw new Gumbo_Exception ("Invalid Argument 'obj:str|StdClass|null' => {$obj}:" . gettype ($obj));
  249.             }
  250.             
  251.             // set callback value
  252.             if (is_null ($obj)) {
  253.                 $callback = $name;
  254.             } else {
  255.                 $callback = array ($obj, $name);
  256.             }
  257.             
  258.             // verify if the function/method is callable
  259.             if (!is_callable ($callback)) {
  260.                 $exc_func = $name . "()";
  261.                 if (!is_null ($obj)) {
  262.                     $exc_class = $obj;
  263.                     if (is_object ($obj)) {
  264.                         $exc_class = get_class ($obj);
  265.                     }
  266.                     $exc_func .= "::{$exc_class}";
  267.                 }
  268.                 throw new Gumbo_Exception ("Function/Method Not Callable: {$exc_func}");
  269.             }
  270.             
  271.             // set the callback function
  272.             $this->_callback = $callback;
  273.             
  274.             // checking for additional parameters on the callback function
  275.             $args = array ();
  276.             if (func_num_args () > 2) {
  277.                 foreach (func_get_args () as $key=>$val) {
  278.                     if ($key <= 1) { continue; }
  279.                     $args [] = $val;
  280.                 }
  281.             }
  282.             $this->_params = $args;
  283.         } catch (Gumbo_Exception $e) {
  284.             $e->setFunction (__METHOD__);
  285.             gumbo_trigger ($e);
  286.         }
  287.     }
  288.     
  289.     /**
  290.      * Executes the callback function
  291.      * 
  292.      * This method must be called by all methods inside the Collection.  This
  293.      * will ensure that the Collection is populated only when the data it
  294.      * holds is needed.
  295.      * 
  296.      * @precondition getCallback ()
  297.      * @precondition !isLoaded ()
  298.      * @throws Gumbo_Exception
  299.      */
  300.     private function _onload () {
  301.         try {
  302.             // verify precontitions
  303.             if ($this->isLoaded () === true) {
  304.                 return;
  305.             }
  306.             if (!$this->getCallback ()) {
  307.                 throw new Gumbo_Exception ("Callback Function Undefined");
  308.             }
  309.             
  310.             // execute callback function
  311.             $this->_loaded = true;
  312.             $params [] = $this;
  313.             foreach ($this->getParams () as $val) {
  314.                 $params [] = $val;
  315.             }
  316.             
  317.             call_user_function_array ($this->getCallback (), $params);
  318.         } catch (Gumbo_Exception $e) {
  319.             $e->setFunction (__METHOD__);
  320.             gumbo_trigger ($e);
  321.         }
  322.     }
  323.     
  324.     
  325.     
  326.     /** ACCESSOR METHODS **/
  327.     /**
  328.      * Returns the corresponding Object associated with the given key
  329.      * @param int|string$key 
  330.      * @return StdClass 
  331.      */
  332.     public function get ($key) {
  333.         try {
  334.             // verify precondition
  335.             if (!is_string ($key) && !is_numeric ($key)) {
  336.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str' => {$key}:" . gettype ($key));
  337.             }
  338.             
  339.             // run callback function
  340.             $this->_onload ();
  341.             
  342.             if (!$this->exists ($key)) {
  343.                 throw new Gumbo_Exception ("Collection Key Undefined: {$key}");
  344.             }
  345.             
  346.             return $this->_list [$key];
  347.         } catch (Gumbo_Exception $e) {
  348.             $e->setFunction (__METHOD__);
  349.             gumbo_trigger ($e);
  350.         }
  351.         return null;
  352.     }
  353.     
  354.     /**
  355.      * Returns the entire List
  356.      * @return array 
  357.      */
  358.     public function getAll () {
  359.         return $this->_list;
  360.     }
  361.     
  362.     /**
  363.      * Returns an array of the Collection keys
  364.      * @precondition size () > 0
  365.      * @return array 
  366.      */
  367.     public function keys () {
  368.         // run callback function
  369.         $this->_onload ();
  370.         return array_keys ($this->_list);
  371.     }
  372.     
  373.     /**
  374.      * Verifies a Key exists
  375.      * @param int|string$key 
  376.      * @return bool 
  377.      */
  378.     public function exists ($key) {
  379.         try {
  380.             // verify precondition
  381.             if (!is_string ($key) && !is_numeric ($key)) {
  382.                 throw new Gumbo_Exception ("Invalid Argument 'key:int|str' => {$key}:" . gettype ($key));
  383.             }
  384.             if (is_numeric ($key)) { $key = (int) $key; }
  385.             
  386.             // run callback function
  387.             $this->_onload ();
  388.             
  389.             return isset ($this->_list [$key]);
  390.         } catch (Gumbo_Exception $e) {
  391.             $e->setFunction (__METHOD__);
  392.             gumbo_trigger ($e);
  393.         }
  394.         return false;
  395.     }
  396.     
  397.     /**
  398.      * Returns the size of the Collection
  399.      * @return int 
  400.      */
  401.     public function size () {
  402.         // run callback function 
  403.         $this->_onload ();
  404.         
  405.         // return array size
  406.         return count ($this->_list);
  407.     }
  408.     
  409.     /**
  410.      * Returns the Collection Type
  411.      * @return string 
  412.      */
  413.     public function getType () {
  414.         return $this->_type;
  415.     }
  416.     
  417.     /**
  418.      * Returns the callback function/method
  419.      * @return string|array
  420.      */
  421.     public function getCallback () {
  422.         return $this->_callback;
  423.     }
  424.     
  425.     /**
  426.      * Returns the parameters to pass to the callback
  427.      * @return array 
  428.      */
  429.     public function getParams () {
  430.         return $this->_params;
  431.     }
  432.     
  433.     /**
  434.      * Returns if the Collection has been loaded
  435.      * @return bool 
  436.      */
  437.     public function isLoaded () {
  438.         return $this->_loaded;
  439.     }
  440.     
  441.     
  442.     
  443.     /**
  444.      * Returns an Iterator object
  445.      * @return Gumbo_Iterator 
  446.      * @uses Gumbo_Iterator
  447.      */
  448.     public function getIterator () {
  449.         // run callback function
  450.         $this->_onload ();
  451.         
  452.         // return the CollectionIterator
  453.         gumbo_load ("Iterator");
  454.         return new Gumbo_Iterator ($this->_list);
  455.     }
  456.     
  457. }
  458.  
  459. ?>