1: <?php
  2: /**
  3:  * PHP version 5
  4:  * @package    generalDriver
  5:  * @author     Christian Schiffler <c.schiffler@cyberspectrum.de>
  6:  * @author     Stefan Heimes <stefan_heimes@hotmail.com>
  7:  * @author     Tristan Lins <tristan.lins@bit3.de>
  8:  * @copyright  The MetaModels team.
  9:  * @license    LGPL.
 10:  * @filesource
 11:  */
 12: 
 13: namespace DcGeneral\Data;
 14: 
 15: use DcGeneral\Exception\DcGeneralInvalidArgumentException;
 16: 
 17: /**
 18:  * Interface ModelInterface.
 19:  *
 20:  * This interface describes a model used in data providers.
 21:  *
 22:  * @package DcGeneral\Data
 23:  */
 24: interface ModelInterface extends \IteratorAggregate
 25: {
 26:     /**
 27:      * Copy this model, without the id.
 28:      *
 29:      * @return void
 30:      */
 31:     public function __clone();
 32: 
 33:     /**
 34:      * Get the id for this model.
 35:      *
 36:      * @return mixed The Id for this model.
 37:      */
 38:     public function getId();
 39: 
 40:     /**
 41:      * Fetch the property with the given name from the model.
 42:      *
 43:      * This method returns null if an unknown property is retrieved.
 44:      *
 45:      * @param string $strPropertyName The property name to be retrieved.
 46:      *
 47:      * @return mixed The value of the given property.
 48:      */
 49:     public function getProperty($strPropertyName);
 50: 
 51:     /**
 52:      * Fetch all properties from the model as an name => value array.
 53:      *
 54:      * @return array
 55:      */
 56:     public function getPropertiesAsArray();
 57: 
 58:     /**
 59:      * Fetch meta information from model.
 60:      *
 61:      * @param string $strMetaName The meta information to retrieve.
 62:      *
 63:      * @return mixed The set meta information or null if undefined.
 64:      */
 65:     public function getMeta($strMetaName);
 66: 
 67:     /**
 68:      * Set the id for this object.
 69:      *
 70:      * NOTE: when the Id has been set once to a non null value, it can NOT be changed anymore.
 71:      *
 72:      * Normally this should only be called from inside of the implementing provider.
 73:      *
 74:      * @param mixed $mixId Could be a integer, string or anything else - depends on the provider implementation.
 75:      *
 76:      * @return void
 77:      */
 78:     public function setId($mixId);
 79: 
 80:     /**
 81:      * Update the property value in the model.
 82:      *
 83:      * @param string $strPropertyName The property name to be set.
 84:      *
 85:      * @param mixed  $varValue        The value to be set.
 86:      *
 87:      * @return void
 88:      */
 89:     public function setProperty($strPropertyName, $varValue);
 90: 
 91:     /**
 92:      * Update all properties in the model.
 93:      *
 94:      * @param array $arrProperties The property values as name => value pairs.
 95:      *
 96:      * @return void
 97:      */
 98:     public function setPropertiesAsArray($arrProperties);
 99: 
100:     /**
101:      * Update meta information in the model.
102:      *
103:      * @param string $strMetaName The meta information name.
104:      *
105:      * @param mixed  $varValue    The meta information value to store.
106:      *
107:      * @return void
108:      */
109:     public function setMeta($strMetaName, $varValue);
110: 
111:     /**
112:      * Check if this model have any properties.
113:      *
114:      * @return boolean true if any property has been stored, false otherwise.
115:      */
116:     public function hasProperties();
117: 
118:     /**
119:      * Return the data provider name.
120:      *
121:      * @return string the name of the corresponding data provider.
122:      */
123:     public function getProviderName();
124: 
125:     /**
126:      * Read all values from a value bag.
127:      *
128:      * If the value is not present in the value bag, it will get skipped.
129:      *
130:      * If the value for a property in the bag is invalid, an exception will get thrown.
131:      *
132:      * @param PropertyValueBagInterface $valueBag The value bag where to read from.
133:      *
134:      * @return ModelInterface
135:      *
136:      * @throws DcGeneralInvalidArgumentException When a property in the value bag has been marked as invalid.
137:      */
138:     public function readFromPropertyValueBag(PropertyValueBagInterface $valueBag);
139: 
140:     /**
141:      * Write values to a value bag.
142:      *
143:      * @param PropertyValueBagInterface $valueBag The value bag where to write to.
144:      *
145:      * @return ModelInterface
146:      */
147:     public function writeToPropertyValueBag(PropertyValueBagInterface $valueBag);
148: }
149: