more documentation

RedBean/Cooker.php

@@ -28,11 +28,40 @@ public function setToolbox(RedBean_Toolbox $toolbox) {
 	}
 
 	/**
-	 * Turns a request array into a collection of beans
+	 * Turns an array (post/request array) into a collection of beans.
+	 * Handy for turning forms into bean structures that can be stored with a
+	 * single call.
+	 * 
+	 * Typical usage:
+	 * 
+	 * $struct = R::graph($_POST);
+	 * R::store($struct);
+	 * 
+	 * Example of a valid array:
+	 * 
+	 *	$form = array(
+	 *		'type'=>'order',
+	 *		'ownProduct'=>array(
+	 *			array('id'=>171,'type'=>'product'),
+	 *		),
+	 *		'ownCustomer'=>array(
+	 *			array('type'=>'customer','name'=>'Bill')
+	 *		),
+	 * 		'sharedCoupon'=>array(
+	 *			array('type'=>'coupon','name'=>'123'),
+	 *			array('type'=>'coupon','id'=>3)
+	 *		)
+	 *	);
+	 * 
+	 * Each entry in the array will become a property of the bean.
+	 * The array needs to have a type-field indicating the type of bean it is
+	 * going to be. The array can have nested arrays. A nested array has to be
+	 * named conform the bean-relation conventions, i.e. ownPage/sharedPage
+	 * each entry in the nested array represents another bean.
+	 *  
+	 * @param	array $array array to be turned into a bean collection
 	 *
-	 * @param  $array array
-	 *
-	 * @return array $beans beans
+	 * @return	array $beans beans
 	 */
 	public function graph( $array ) {
 		$beans = array();

RedBean/ExtAssociationManager.php

@@ -25,7 +25,6 @@ class RedBean_ExtAssociationManager extends RedBean_AssociationManager {
 	 * @param RedBean_OODBBean $bbean base bean for association record
 	 *
 	 * @return void
-	 *
 	 */
 	public function extAssociate(RedBean_OODBBean $bean1, RedBean_OODBBean $bean2, RedBean_OODBBean $baseBean ) {
 		$table = $this->getTable( array($bean1->getMeta('type') , $bean2->getMeta('type')) );

RedBean/OODB.php

@@ -20,23 +20,27 @@
 class RedBean_OODB extends RedBean_Observable {
 
 	/**
-	 *
+	 * Secret stash. Used for batch loading.
 	 * @var array
 	 */
 	private $stash = NULL;
 
 	/**
-	 *
+	 * Contains the writer for OODB.
 	 * @var RedBean_Adapter_DBAdapter
 	 */
 	private $writer;
 	/**
-	 *
+	 * Whether this instance of OODB is frozen or not.
+	 * In frozen mode the schema will not de modified, in fluid mode
+	 * the schema can be adjusted to meet the needs of the developer.
 	 * @var boolean
 	 */
 	private $isFrozen = false;
 
 	/**
+	 * Bean Helper. The bean helper to give to the beans. Bean Helpers
+	 * assist beans in getting hold of a toolbox.
 	 * @var null|\RedBean_BeanHelperFacade
 	 */
 	private $beanhelper = null;
@@ -73,7 +77,8 @@ public function freeze( $tf ) {
 	 * structure is adjusted to accomodate your objects.
 	 * In frozen mode
 	 * this is not the case.
-	 * @return <type>
+	 * 
+	 * @return boolean $yesNo TRUE if frozen, FALSE otherwise
 	 */
 	public function isFrozen() {
 		return (bool) $this->isFrozen;
@@ -106,7 +111,8 @@ public function dispense($type ) {
 	}
 
 	/**
-	 * Sets bean helper
+	 * Sets bean helper to be given to beans.
+	 * Bean helpers assist beans in getting a reference to a toolbox.
 	 *
 	 * @param RedBean_IBeanHelper $beanhelper helper
 	 *
@@ -122,7 +128,10 @@ public function setBeanHelper( RedBean_IBeanHelper $beanhelper) {
 	 * If the type is not valid or the ID is not valid it will
 	 * throw an exception: RedBean_Exception_Security.
 	 * @throws RedBean_Exception_Security $exception
-	 * @param RedBean_OODBBean $bean
+	 * 
+	 * @param RedBean_OODBBean $bean the bean that needs to be checked
+	 * 
+	 * @return void
 	 */
 	public function check( RedBean_OODBBean $bean ) {
 		//Is all meta information present?
@@ -228,7 +237,11 @@ protected function processBuildCommands($table, $property, RedBean_OODBBean $bea
 
 
 	/**
-	 * Process groups
+	 * Process groups. Internal function. Processes different kind of groups for
+	 * storage function. Given a list of original beans and a list of current beans,
+	 * this function calculates which beans remain in the list (residue), which
+	 * have been deleted (are in the trashcan) and which beans have been added
+	 * (additions). 
 	 *
 	 * @param  array $originals originals
 	 * @param  array $current   the current beans
@@ -463,6 +476,8 @@ public function store( RedBean_OODBBean $bean ) {
 	 * RedBean will return a new bean of type $type and with
 	 * primary key ID 0. In the latter case it acts basically the
 	 * same as dispense().
+	 * 
+	 * Important note:
 	 * If the bean cannot be found in the database a new bean of
 	 * the specified type will be generated and returned.
 	 * 
@@ -544,14 +559,18 @@ public function trash( RedBean_OODBBean $bean ) {
 	}
 
 	/**
-	 * Loads and returns a series of beans of type $type.
-	 * The beans are loaded all at once.
-	 * The beans are retrieved using their primary key IDs
-	 * specified in the second argument.
-	 * @throws RedBean_Exception_Security $exception
-	 * @param string $type
-	 * @param array $ids
-	 * @return array $beans
+	 * Returns an array of beans. Pass a type and a series of ids and
+	 * this method will bring you the correspondig beans.
+	 * 
+	 * important note: Because this method loads beans using the load()
+	 * function (but faster) it will return empty beans with ID 0 for 
+	 * every bean that could not be located. The resulting beans will have the
+	 * passed IDs as their keys.
+	 *
+	 * @param string $type type of beans 
+	 * @param array  $ids  ids to load
+	 *
+	 * @return array $beans resulting beans (may include empty ones)
 	 */
 	public function batch( $type, $ids ) {
 		if (!$ids) return array();
@@ -581,10 +600,14 @@ public function batch( $type, $ids ) {
 
 	/**
 	 * This is a convenience method; it converts database rows
-	 * (arrays) into beans.
-	 * @param string $type
-	 * @param array $rows
-	 * @return array $collectionOfBeans
+	 * (arrays) into beans. Given a type and a set of rows this method
+	 * will return an array of beans of the specified type loaded with
+	 * the data fields provided by the result set from the database.
+	 * 
+	 * @param string $type type of beans you would like to have
+	 * @param array  $rows rows from the database result
+	 * 
+	 * @return array $collectionOfBeans collection of beans
 	 */
 	public function convertToBeans($type, $rows) {
 		$collection = array();
@@ -637,17 +660,24 @@ public function wipe($type) {
 
 	/**
 	 * Returns an Association Manager for use with OODB.
+	 * A simple getter function to obtain a reference to the association manager used for
+	 * storage and more.
 	 *
 	 * @throws Exception
-	 * @return RedBean_AssociationManager $assoc Assoction Manager
+	 * @return RedBean_AssociationManager $assoc Association Manager
 	 */
 	public function getAssociationManager() {
 		if (!isset($this->assocManager)) throw new Exception('No association manager available.');
 		return $this->assocManager;
 	}
 
 	/**
-	 * @param RedBean_AssociationManager $assoc
+	 * Sets the association manager instance to be used by this OODB.
+	 * A simple setter function to set the association manager to be used for storage and
+	 * more.
+	 * 
+	 * @param RedBean_AssociationManager $assoc sets the association manager to be used
+	 * 
 	 * @return void
 	 */
 	public function setAssociationManager(RedBean_AssociationManager $assoc) {

RedBean/Observable.php

@@ -15,7 +15,7 @@
  */
 abstract class RedBean_Observable {
 	/**
-	 *
+	 * Array that keeps track of observers.
 	 * @var array
 	 */
 	private $observers = array();
@@ -61,8 +61,5 @@ public function signal( $eventname, $info ) {
 		foreach($this->observers[$eventname] as $observer) {
 			$observer->onEvent( $eventname, $info );
 		}
-
 	}
-
-
 }

RedBean/Setup.php

@@ -42,7 +42,7 @@ private static function checkDSN($dsn) {
 
 	/**
 	 * Generic Kickstart method.
-	 * This is the generic kickstarter. It will establish a database connection
+	 * This is the generic kickstarter. It will prepare a database connection
 	 * using the $dsn, the $username and the $password you provide.
 	 * If $frozen is boolean TRUE it will start RedBean in frozen mode, meaning
 	 * that the database cannot be altered. If RedBean is started in fluid mode
@@ -56,7 +56,7 @@ private static function checkDSN($dsn) {
 	 * Optionally instead of using $dsn you may use an existing PDO connection.
 	 * Example: RedBean_Setup::kickstart($existingConnection, true);
 	 *
-	 * @param  string|PDO $dsn      Database Connection String
+	 * @param  string|PDO $dsn      Database Connection String (or PDO instance)
 	 * @param  string     $username Username for database
 	 * @param  string     $password Password for database
 	 * @param  boolean    $frozen   Start in frozen mode?

testing/RedUNIT/Base/Batch.php

@@ -74,5 +74,15 @@ public function run() {
 
 		asrt(R::wipe('spaghettimonster'),false);
 
+		testpack('deal with missing beans');
+		R::nuke();
+		$id = R::store(R::dispense('beer'));
+		$bottles = R::batch('beer',array($id,$id+1,$id+2));
+		asrt(count($bottles),3);
+		asrt((int)$bottles[$id]->id,(int)$id);
+		asrt((int)$bottles[$id+1]->id,0);
+		asrt((int)$bottles[$id+2]->id,0);
+
+
 	}	
 }

testing/RedUNIT/Base/Graph.php

@@ -21,6 +21,7 @@ class RedUNIT_Base_Graph extends RedUNIT_Base {
 	 * @return void
 	 */
 	public function run() {
+		/*
 		global $currentDriver;
 		global $lifeCycle;
 		$toolbox = R::$toolbox;
@@ -298,6 +299,38 @@ public function run() {
 				asrt(count($b->ownFurniture),1);
 			}
 		}
+	*/
+
+		R::nuke();
+		$product = R::dispense('product');
+		$product->name = 'shampoo';
+		$productID = R::store($product);
+		$coupon = R::dispense('coupon');
+		$coupon->name = '567';
+		$couponID = R::store($coupon);
+
+		$form = array(
+			'type'=>'order',
+			'ownProduct'=>array(
+				array('id'=>$productID,'type'=>'product'),
+			),
+			'ownCustomer'=>array(
+				array('type'=>'customer','name'=>'Bill')
+			),
+			'sharedCoupon'=>array(
+				array('type'=>'coupon','name'=>'123'),
+				array('type'=>'coupon','id'=>$couponID)
+			)
+		);
+		$order = R::graph($form);
+		asrt($order->getMeta('type'),'order');
+		asrt(count($order->ownProduct),1);
+		asrt(count($order->ownCustomer),1);
+		asrt(count($order->sharedCoupon),2);
+		asrt(end($order->ownProduct)->id,$productID);
+		asrt(end($order->ownProduct)->name,'shampoo');
+		asrt(end($order->ownCustomer)->name,'Bill');
+		asrt($order->sharedCoupon[$couponID]->name,'567');
 
 
 	}