Gumbo PHP Library API Documentation

Collection Interface

A Collection is a system for defining a one-to-many relationship between two different classes. It will load it's contents only when the information is needed. The Collection callback will be responsible for loading the contents.

The primary class (Student) will contain internal information about the object. It will also reference a list of data (Course) through some association. When the primary class is loaded, it will only load the referenced data when the program needs it. This will allow the program to access Student information without loading the Course list a student is enrolled in.

The Collection requires a callback function, which is responsible for loading the contents of the Collection. The callback is called when the details of the Collection is needed. A callback can be a single function or a class method. The callback would need the Collection object it will be populating and any additional arguments needed.

 class Course {
 		public static function loadStudentCourses (Collection $col, $student_id) {
 			$col->setType ("Course");
 			foreach ($course_list as $course) {
 				$col->add ($course);
 			}
 		}

Since objects are passed by reference, there is no need to return any values. The Collection will accept Course objects (defined by the Type). Certain methods inside the Collection will call the callback before returning their results.

The Student class will define a Collection inside the Constructor. This step would require defining the Callback function. The Student class would also provide a method to return the Collection.

 class Student {
 		private $_id; // student ID
 		private $_courses;

 		public function __construct () {
 			$this->_courses = new Collection ("loadStudentCourses", "Course", $this->id);
 			...
 		}

 		public function getCourses () {
 			return $this->_courses;
 		}
 		...
 }

When a new Student is created, the Collection object is created, however it is empty. When the program tries to retrieve details from the Collection, the callback function is called, and the Collection is populated.