[CLEANUP] Replace wrong/old file copyright comments
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Persistence / ObjectStorage.php
1 <?php
2 namespace TYPO3\CMS\Extbase\Persistence;
3
4 /***************************************************************
5 * Copyright notice
6 *
7 * (c) 2010-2012 Extbase Team (http://forge.typo3.org/projects/typo3v4-mvc)
8 * Extbase is a backport of TYPO3 Flow. All credits go to the TYPO3 Flow team.
9 * All rights reserved
10 *
11 * This script is part of the TYPO3 project. The TYPO3 project is
12 * free software; you can redistribute it and/or modify
13 * it under the terms of the GNU General Public License as published by
14 * the Free Software Foundation; either version 2 of the License, or
15 * (at your option) any later version.
16 *
17 * The GNU General Public License can be found at
18 * http://www.gnu.org/copyleft/gpl.html.
19 * A copy is found in the textfile GPL.txt and important notices to the license
20 * from the author is found in LICENSE.txt distributed with these scripts.
21 *
22 *
23 * This script is distributed in the hope that it will be useful,
24 * but WITHOUT ANY WARRANTY; without even the implied warranty of
25 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26 * GNU General Public License for more details.
27 *
28 * This copyright notice MUST APPEAR in all copies of the script!
29 ***************************************************************/
30 /**
31 * The storage for objects. It ensures the uniqueness of an object in the storage. It's a remake of the
32 * SplObjectStorage introduced in PHP 5.3.
33 *
34 * Opposed to the SplObjectStorage the ObjectStorage does not implement the Serializable interface.
35 */
36 class ObjectStorage implements \Countable, \Iterator, \ArrayAccess, \TYPO3\CMS\Extbase\Persistence\ObjectMonitoringInterface {
37
38 /**
39 * This field is only needed to make debugging easier:
40 * If you call current() on a class that implements Iterator, PHP will return the first field of the object
41 * instead of calling the current() method of the interface.
42 * We use this unusual behavior of PHP to return the warning below in this case.
43 *
44 * @var string
45 */
46 private $warning = 'You should never see this warning. If you do, you probably used PHP array functions like current() on the TYPO3\\CMS\\Extbase\\Persistence\\ObjectStorage. To retrieve the first result, you can use the rewind() and current() methods.';
47
48 /**
49 * An array holding the objects and the stored information. The key of the array items ist the
50 * spl_object_hash of the given object.
51 *
52 * array(
53 * spl_object_hash =>
54 * array(
55 * 'obj' => $object,
56 * 'inf' => $information
57 * )
58 * )
59 *
60 * @var array
61 */
62 protected $storage = array();
63
64 /**
65 * A flag indication if the object storage was modified after reconstitution (eg. by adding a new object)
66 *
67 * @var boolean
68 */
69 protected $isModified = FALSE;
70
71 /**
72 * Rewinds the iterator to the first storage element.
73 *
74 * @return void
75 */
76 public function rewind() {
77 reset($this->storage);
78 }
79
80 /**
81 * Checks if the array pointer of the storage points to a valid position.
82 *
83 * @return boolean
84 */
85 public function valid() {
86 return current($this->storage) !== FALSE;
87 }
88
89 /**
90 * Returns the index at which the iterator currently is.
91 *
92 * This is different from the SplObjectStorage as the key in this implementation is the object hash (string).
93 *
94 * @return string The index corresponding to the position of the iterator.
95 */
96 public function key() {
97 return key($this->storage);
98 }
99
100 /**
101 * Returns the current storage entry.
102 *
103 * @return object The object at the current iterator position.
104 */
105 public function current() {
106 $item = current($this->storage);
107 return $item['obj'];
108 }
109
110 /**
111 * Moves to the next entry.
112 *
113 * @return void
114 */
115 public function next() {
116 next($this->storage);
117 }
118
119 /**
120 * Returns the number of objects in the storage.
121 *
122 * @return integer The number of objects in the storage.
123 */
124 public function count() {
125 return count($this->storage);
126 }
127
128 /**
129 * Associates data to an object in the storage. offsetSet() is an alias of attach().
130 *
131 * @param object $object The object to add.
132 * @param mixed $information The data to associate with the object.
133 * @return void
134 */
135 public function offsetSet($object, $information) {
136 $this->isModified = TRUE;
137 $this->storage[spl_object_hash($object)] = array('obj' => $object, 'inf' => $information);
138 }
139
140 /**
141 * Checks whether an object exists in the storage.
142 *
143 * @param object $object The object to look for.
144 * @return boolean
145 */
146 public function offsetExists($object) {
147 return isset($this->storage[spl_object_hash($object)]);
148 }
149
150 /**
151 * Removes an object from the storage. offsetUnset() is an alias of detach().
152 *
153 * @param object $object The object to remove.
154 * @return void
155 */
156 public function offsetUnset($object) {
157 $this->isModified = TRUE;
158 unset($this->storage[spl_object_hash($object)]);
159 }
160
161 /**
162 * Returns the data associated with an object.
163 *
164 * @param object $object The object to look for.
165 * @return mixed The data associated with an object in the storage.
166 */
167 public function offsetGet($object) {
168 return $this->storage[spl_object_hash($object)]['inf'];
169 }
170
171 /**
172 * Checks if the storage contains a specific object.
173 *
174 * @param object $object The object to look for.
175 * @return boolean
176 */
177 public function contains($object) {
178 return $this->offsetExists($object);
179 }
180
181 /**
182 * Adds an object in the storage, and optionaly associate it to some data.
183 *
184 * @param object $object The object to add.
185 * @param mixed $information The data to associate with the object.
186 * @return void
187 */
188 public function attach($object, $information = NULL) {
189 $this->offsetSet($object, $information);
190 }
191
192 /**
193 * Removes an object from the storage.
194 *
195 * @param object $object The object to remove.
196 * @return void
197 */
198 public function detach($object) {
199 $this->offsetUnset($object);
200 }
201
202 /**
203 * Returns the data, or info, associated with the object pointed by the current iterator position.
204 *
205 * @return mixed The data associated with the current iterator position.
206 */
207 public function getInfo() {
208 $item = current($this->storage);
209 return $item['inf'];
210 }
211
212 /**
213 * Associates data, or info, with the object currently pointed to by the iterator.
214 *
215 * @param mixed $data
216 * @return void
217 */
218 public function setInfo($data) {
219 $this->isModified = TRUE;
220 $key = key($this->storage);
221 $this->storage[$key]['inf'] = $data;
222 }
223
224 /**
225 * Adds all objects-data pairs from a different storage in the current storage.
226 *
227 * @param \TYPO3\CMS\Extbase\Persistence\ObjectStorage $objectStorage
228 * @return void
229 */
230 public function addAll(\TYPO3\CMS\Extbase\Persistence\ObjectStorage $objectStorage) {
231 foreach ($objectStorage as $object) {
232 $this->attach($object, $objectStorage->getInfo());
233 }
234 }
235
236 /**
237 * Removes objects contained in another storage from the current storage.
238 *
239 * @param \TYPO3\CMS\Extbase\Persistence\ObjectStorage $objectStorage The storage containing the elements to remove.
240 * @return void
241 */
242 public function removeAll(\TYPO3\CMS\Extbase\Persistence\ObjectStorage $objectStorage) {
243 foreach ($objectStorage as $object) {
244 $this->detach($object);
245 }
246 }
247
248 /**
249 * Returns this object storage as an array
250 *
251 * @return array The object storage
252 */
253 public function toArray() {
254 $array = array();
255 $storage = array_values($this->storage);
256 foreach ($storage as $item) {
257 $array[] = $item['obj'];
258 }
259 return $array;
260 }
261
262 /**
263 * Dummy method to avoid serialization.
264 *
265 * @throws \RuntimeException
266 * @return void
267 */
268 public function serialize() {
269 throw new \RuntimeException('An ObjectStorage instance cannot be serialized.', 1267700868);
270 }
271
272 /**
273 * Dummy method to avoid unserialization.
274 *
275 * @param $serialized
276 * @throws \RuntimeException
277 * @return void
278 */
279 public function unserialize($serialized) {
280 throw new \RuntimeException('A ObjectStorage instance cannot be unserialized.', 1267700870);
281 }
282
283 /**
284 * Register the storage's clean state, e.g. after it has been reconstituted from the database.
285 *
286 * @return void
287 */
288 public function _memorizeCleanState() {
289 $this->isModified = FALSE;
290 }
291
292 /**
293 * Returns TRUE if the storage was modified after reconstitution.
294 *
295 * @return boolean
296 */
297 public function _isDirty() {
298 return $this->isModified;
299 }
300 }
301
302 ?>