Source for file Mapper.class.php

Documentation is available at Mapper.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 Map
  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.  * Mapper Interface
  22.  * 
  23.  * The Mapper is responsible for holding Maps.  A Map is simply a key reference
  24.  * to some outside data (see Gumbo_Interface_Map for more details).  The Mapper
  25.  * can hold a single Map, or multiple Maps referenced by a key.
  26.  * 
  27.  * Once the Maps are assigned, the 'map' method will be responsible for taking
  28.  * some foreign data and applying the appropriate Map.  For example, if the
  29.  * Mapper Class wants to Map internal properties to an HTML form, the program would
  30.  * pass the $_REQUEST array (or some other) into the 'map' method.  The Map class
  31.  * would define the reference from the HTML form name to the internal property.
  32.  * 
  33.  * <pre>
  34.  * // quick implementation of map method (assume inside class)
  35.  * public function map ($data, $key=null) {
  36.  *     $map = $this->getMap ($key);
  37.  *     foreach ($data as $key=>$val) {
  38.  *         if (!$map->isForeignKey ($key)) { continue; }
  39.  *         $property = $map->getKey ($key);
  40.  *         $this->$property = $val;
  41.  *     }
  42.  * }
  43.  * </pre>
  44.  * 
  45.  * <pre>
  46.  * // map foreign data to the Mapper
  47.  * $mapper = new Some_Mapper_Class ();
  48.  * $mapper->map ($_REQUEST); // assuming a Map was created
  49.  * </pre>
  50.  *
  51.  * @category Gumbo
  52.  * @package Map
  53.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  54.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  55.  * @author Michael Luster <mluster79@yahoo.com>
  56.  * @link http://sourceforge.net/projects/phpgumbo
  57.  * @desc Mapper Interface
  58.  * @version 0.0.1
  59.  * @see Gumbo_Interface_Map
  60.  */
  61.  
  62. gumbo_load ("Interface_Map");
  63.  
  64. interface Gumbo_Interface_Mapper {
  65.     
  66.     /** ACTION METHODS **/
  67.     /**
  68.      * Adds a Map
  69.      * @param Gumbo_Interface_Map $map 
  70.      * @param string $key reference string to the Map object
  71.      * @param bool $replace replaces original
  72.      */
  73.     public function addMap (Gumbo_Interface_Map $map, $key=null, $replace=false);
  74.     
  75.     /**
  76.      * Deletes a Map
  77.      * @param string $key 
  78.      */
  79.     public function removeMap ($key=null);
  80.     
  81.     /**
  82.      * Clears all the Maps
  83.      * @postcondition !getAllMaps()
  84.      */
  85.     public function resetMaps ();
  86.     
  87.     /**
  88.      * Maps information into the Mapper
  89.      * @param array $data where key=>"form field name", value=>user data
  90.      * @param string $key Map reference key
  91.      */
  92.     public function map ($data, $key=null);
  93.     
  94.     
  95.     
  96.     /** ACCESSOR METHODS **/
  97.     /**
  98.      * Gets the selected Map
  99.      * @param string $key 
  100.      * @return Gumbo_Interface_Map 
  101.      */
  102.     public function getMap ($key=null);
  103.     
  104.     /**
  105.      * Returns all Maps
  106.      * @return Gumbo_Interface_Map[] 
  107.      */
  108.     public function getAllMaps ();
  109.     
  110.     /**
  111.      * Returns if the Map exists
  112.      * @param string $key reference key string
  113.      * @return bool 
  114.      */
  115.     public function isMap ($key=null);
  116.     
  117. }
  118.  
  119. ?>