6 * a DataObject is a generic object
7 * to store data under given keys.
9 * it allows getting, adding, updating and deleting
12 * a validation callback can be provided
13 * to ensure, that the stored data
22 private $arrData = array();
25 * callback to validate all stored data
27 private $cloValidator = null;
30 * @param $cloValidator - optional validator callback to validate stored data
31 * @param $arrData - optional list of data to store in object
33 * @throws UnexpectedParameterTypeException - if validator callback is not a callable
35 * initiates the data-object and stores the validator callback. if no
36 * callback is given, a default callback is stored, which validates against
39 * if optional data are given, they are passed to DataObject::add(), to be stored
43 public function __construct($cloValidator = null, array $arrData = array()) {
45 if(!is_null($cloValidator) && !is_callable($cloValidator))
46 throw new UnexpectedParameterTypeException('callable', $cloValidator);
48 $this->cloValidator = (!is_null($cloValidator)) ? $cloValidator : function() {return true; };
56 * @param $arrData - list of data to store in object
58 * @throws \Exception - if a key is already in use
59 * @throws \Exception - if the final data-set do not validate
61 * add the list of data to the existing ones. the given data
62 * must have the following format:
64 * [key] => data, [..])
66 * if a key in the given data is already used in stored
67 * data the addition is aborted and an exception is
70 * the stored data are only modified on success
73 public function add(array $arrData) {
75 $arrMergedData = array_merge($this->arrData, $arrData);
77 foreach($arrData AS $strKey => $mixData)
78 if(array_key_exists($strKey, $this->arrData))
79 throw new \Exception("could not store data, key is already in use: $strKey");
81 $cloValidator = $this->cloValidator;
83 if(!$cloValidator($arrMergedData))
84 throw new \Exception("given data do not validate");
86 $this->arrData = $arrMergedData;
91 * @param $arrData - list of data to update
93 * @throws \Exception - if the final data-set do not validate
95 * update the stored data with the given data-set. for
96 * the structure of $arrData have a look at DataObject:add()
98 * existing keys are overwritten with new values. new
99 * keys are added to the data-set.
101 * if validation of final set fails, an exception is
102 * thrown. no data are modified on failure.
105 public function update(array $arrData) {
107 $arrMergedData = array_merge($this->arrData, $arrData);
109 $cloValidator = $this->cloValidator;
111 if(!$cloValidator($arrMergedData))
112 throw new \Exception("given data do not validate");
114 $this->arrData = $arrMergedData;
119 * @param $strKey - the key of the value to delete
121 * @throws UnexpectedParameterTypeException - if given key is not a string
123 * delete the value stored under the given key.
124 * if given key do not exists, nothing is done!
127 public function delete($strKey) {
129 if(!is_string($strKey))
130 throw new UnexpectedParameterTypeException('string', $strKey);
132 if($this->exists($strKey))
133 unset($this->arrData[$strKey]);
138 * @param $strKey - the key to check
140 * @throws UnexpectedParameterTypeException - if given key is not a string
142 * @return (boolean) true, if key exists
143 * @return (boolean) false, if key do not exists
145 * check if the given key exists
148 public function exists($strKey) {
150 if(!is_string($strKey))
151 throw new UnexpectedParameterTypeException('string', $strKey);
153 if(!array_key_exists($strKey, $this->arrData))
161 * @param $strKey - the key to get the value from
163 * @throws UnexpectedParameterTypeException - if given key is not a string
164 * @throws \Exception - if given key is unknown
166 * @return (mixed) the value stored under the given key
168 * return the value stored under the given key
171 public function get($strKey) {
173 if(!is_string($strKey))
174 throw new UnexpectedParameterTypeException('string', $strKey);
176 if(!$this->exists($strKey))
177 throw new \Exception("unknown key: $strKey");
179 return $this->arrData[$strKey];
184 * return all stored data in the structure of:
185 * array([key] => data
186 * [key] => data, [..])
189 public function getAll() {
191 return $this->arrData;