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.  * Collection Interface
  22.  * 
  23.  * A Collection is a system for defining a one-to-many relationship between
  24.  * two different classes.  It will load it's contents only when the information
  25.  * is needed.  The Collection callback will be responsible for loading the
  26.  * contents.
  27.  * 
  28.  * The primary class (Student) will contain internal information about the
  29.  * object.  It will also reference a list of data (Course) through some
  30.  * association.  When the primary class is loaded, it will only load the
  31.  * referenced data when the program needs it.  This will allow the program
  32.  * to access Student information without loading the Course list a student
  33.  * is enrolled in.
  34.  * 
  35.  * The Collection requires a callback function, which is responsible for
  36.  * loading the contents of the Collection.  The callback is called when the
  37.  * details of the Collection is needed.  A callback can be a single function
  38.  * or a class method.  The callback would need the Collection object it will
  39.  * be populating and any additional arguments needed.
  40.  * 
  41.  * <pre>
  42.  * class Course {
  43.  *         public static function loadStudentCourses (Collection $col, $student_id) {
  44.  *             $col->setType ("Course");
  45.  *             foreach ($course_list as $course) {
  46.  *                 $col->add ($course);
  47.  *             }
  48.  *         }
  49.  * </pre>
  50.  * 
  51.  * Since objects are passed by reference, there is no need to return any values.  The
  52.  * Collection will accept Course objects (defined by the Type).  Certain methods
  53.  * inside the Collection will call the callback before returning their results.
  54.  * 
  55.  * The Student class will define a Collection inside the Constructor.  This step
  56.  * would require defining the Callback function.  The Student class would also provide
  57.  * a method to return the Collection.
  58.  * 
  59.  * <pre>
  60.  * class Student {
  61.  *         private $_id; // student ID
  62.  *         private $_courses;
  63.  * 
  64.  *         public function __construct () {
  65.  *             $this->_courses = new Collection ("loadStudentCourses", "Course", $this->id);
  66.  *             ...
  67.  *         }
  68.  *         
  69.  *         public function getCourses () {
  70.  *             return $this->_courses;
  71.  *         }
  72.  *         ...
  73.  * }
  74.  * </pre>
  75.  *             
  76.  * When a new Student is created, the Collection object is created, however it is
  77.  * empty.  When the program tries to retrieve details from the Collection, the callback
  78.  * function is called, and the Collection is populated.
  79.  *
  80.  * @category Gumbo
  81.  * @package Collection
  82.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  83.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  84.  * @author Michael Luster <mluster79@yahoo.com>
  85.  * @link http://sourceforge.net/projects/phpgumbo
  86.  * @desc Collection Interface
  87.  * @version 0.0.1
  88.  */
  89.  
  90. gumbo_load ("Interface_List");
  91.  
  92. interface Gumbo_Interface_Collection extends Gumbo_Interface_List {
  93.     
  94.     /**
  95.      * Sets the callback function/method (extra arguments will be sent to callback as is)
  96.      * 
  97.      * The callback function will be called to load the contents of the
  98.      * Collection.  The value could be a function name or a class method. A
  99.      * callback function/method should define a single argument, the
  100.      * Collection.  When the callback is executed, the Collection will
  101.      * pass itself (by reference) to the function.  The callback will
  102.      * set the values of the Collection.
  103.      * 
  104.      * To set a function:
  105.      * <code>$coll->setCallback ("function_name");</code>
  106.      * 
  107.      * To set a class/object method (3 methods):
  108.      * <code>
  109.      * $col->setCallback ("method_name", "class_name");
  110.      * // substitute an Object ($obj) for "class_name" if necessary
  111.      * </code>
  112.      * 
  113.      * @precondition function/method callable
  114.      * @param string $name function/method name (array should be (0=>"class",1=>"method"))
  115.      * @param string|StdClass$obj class name or Object reference
  116.      */
  117.     public function setCallback ($name, $obj=null);
  118.     
  119.     /**
  120.      * Sets the type of Class|Interface the Collection will accept
  121.      * @param string $type 
  122.      */
  123.     public function setType ($type);
  124.     
  125.     
  126.     
  127.     /** ACCESSOR METHODS **/
  128.     /**
  129.      * Returns the Collection Class|Interface Type
  130.      * @return string 
  131.      */
  132.     public function getType ();
  133.     
  134.     /**
  135.      * Returns the callback function/method
  136.      * @return string|array
  137.      */
  138.     public function getCallback ();
  139.     
  140.     /**
  141.      * Returns the parameters to pass to the callback
  142.      * @return array 
  143.      */
  144.     public function getParams ();
  145.     
  146.     /**
  147.      * Returns if the Collection has been loaded
  148.      * @return bool 
  149.      */
  150.     public function isLoaded ();
  151.     
  152. }
  153.  
  154. ?>