[CLEANUP] Improve the @param/@return/@var PHPDoc
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Persistence / Generic / LazyObjectStorage.php
1 <?php
2 namespace TYPO3\CMS\Extbase\Persistence\Generic;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 use TYPO3\CMS\Extbase\DomainObject\DomainObjectInterface;
18
19 /**
20 * A proxy that can replace any object and replaces itself in it's parent on
21 * first access (call, get, set, isset, unset).
22 */
23 class LazyObjectStorage extends \TYPO3\CMS\Extbase\Persistence\ObjectStorage implements \TYPO3\CMS\Extbase\Persistence\Generic\LoadingStrategyInterface {
24
25 /**
26 * This field is only needed to make debugging easier:
27 * If you call current() on a class that implements Iterator, PHP will return the first field of the object
28 * instead of calling the current() method of the interface.
29 * We use this unusual behavior of PHP to return the warning below in this case.
30 *
31 * @var string
32 */
33 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\\Generic\\LazyObjectStorage. To retrieve the first result, you can use the rewind() and current() methods.';
34
35 /**
36 * @var \TYPO3\CMS\Extbase\Persistence\Generic\Mapper\DataMapper
37 * @inject
38 */
39 protected $dataMapper;
40
41 /**
42 * The object this property is contained in.
43 *
44 * @var \TYPO3\CMS\Extbase\DomainObject\DomainObjectInterface
45 */
46 protected $parentObject;
47
48 /**
49 * The name of the property represented by this proxy.
50 *
51 * @var string
52 */
53 protected $propertyName;
54
55 /**
56 * The raw field value.
57 *
58 * @var mixed
59 */
60 protected $fieldValue;
61
62 /**
63 * @var bool
64 */
65 protected $isInitialized = FALSE;
66
67 /**
68 * Returns the state of the initialization
69 *
70 * @return bool
71 */
72 public function isInitialized() {
73 return $this->isInitialized;
74 }
75
76 /**
77 * Constructs this proxy instance.
78 *
79 * @param DomainObjectInterface $parentObject The object instance this proxy is part of
80 * @param string $propertyName The name of the proxied property in it's parent
81 * @param mixed $fieldValue The raw field value.
82 */
83 public function __construct($parentObject, $propertyName, $fieldValue) {
84 $this->parentObject = $parentObject;
85 $this->propertyName = $propertyName;
86 $this->fieldValue = $fieldValue;
87 reset($this->storage);
88 }
89
90 /**
91 * This is a function lazy load implementation.
92 *
93 * @return void
94 */
95 protected function initialize() {
96 if (!$this->isInitialized) {
97 $this->isInitialized = TRUE;
98 $objects = $this->dataMapper->fetchRelated($this->parentObject, $this->propertyName, $this->fieldValue, FALSE);
99 foreach ($objects as $object) {
100 parent::attach($object);
101 }
102 $this->_memorizeCleanState();
103 if (!$this->isStorageAlreadyMemorizedInParentCleanState()) {
104 $this->parentObject->_memorizeCleanState($this->propertyName);
105 }
106 }
107 }
108
109 /**
110 * @return bool
111 */
112 protected function isStorageAlreadyMemorizedInParentCleanState() {
113 return $this->parentObject->_getCleanProperty($this->propertyName) === $this;
114 }
115
116 // Delegation to the ObjectStorage methods below
117 /**
118 * @param \TYPO3\CMS\Extbase\Persistence\ObjectStorage $storage
119 *
120 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::addAll
121 */
122 public function addAll($storage) {
123 $this->initialize();
124 parent::addAll($storage);
125 }
126
127 /**
128 * @param object $object The object to add.
129 * @param mixed $data The data to associate with the object.
130 *
131 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::attach
132 */
133 public function attach($object, $data = NULL) {
134 $this->initialize();
135 parent::attach($object, $data);
136 }
137
138 /**
139 * @param object $object The object to look for.
140 * @return bool
141 *
142 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::contains
143 */
144 public function contains($object) {
145 $this->initialize();
146 return parent::contains($object);
147 }
148
149 /**
150 * Counts the elements in the storage array
151 *
152 * @throws Exception
153 * @return int The number of elements in the ObjectStorage
154 */
155 public function count() {
156 $columnMap = $this->dataMapper->getDataMap(get_class($this->parentObject))->getColumnMap($this->propertyName);
157 $numberOfElements = NULL;
158 if (!$this->isInitialized && $columnMap->getTypeOfRelation() === Mapper\ColumnMap::RELATION_HAS_MANY) {
159 $numberOfElements = $this->dataMapper->countRelated($this->parentObject, $this->propertyName, $this->fieldValue);
160 } else {
161 $this->initialize();
162 $numberOfElements = count($this->storage);
163 }
164 if (is_null($numberOfElements)) {
165 throw new \TYPO3\CMS\Extbase\Persistence\Generic\Exception('The number of elements could not be determined.', 1252514486);
166 }
167 return $numberOfElements;
168 }
169
170 /**
171 * @return object The object at the current iterator position.
172 *
173 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::current
174 */
175 public function current() {
176 $this->initialize();
177 return parent::current();
178 }
179
180 /**
181 * @param object $object The object to remove.
182 *
183 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::detach
184 */
185 public function detach($object) {
186 $this->initialize();
187 parent::detach($object);
188 }
189
190 /**
191 * @return string The index corresponding to the position of the iterator.
192 *
193 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::key
194 */
195 public function key() {
196 $this->initialize();
197 return parent::key();
198 }
199
200 /**
201 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::next
202 */
203 public function next() {
204 $this->initialize();
205 parent::next();
206 }
207
208 /**
209 * @param object $object The object to look for.
210 * @return bool
211 *
212 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::offsetExists
213 */
214 public function offsetExists($object) {
215 $this->initialize();
216 return parent::offsetExists($object);
217 }
218
219 /**
220 * @param object $object The object to look for.
221 * @return mixed
222 *
223 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::offsetGet
224 */
225 public function offsetGet($object) {
226 $this->initialize();
227 return parent::offsetGet($object);
228 }
229
230 /**
231 * @param object $object The object to add.
232 * @param mixed $info The data to associate with the object.
233 *
234 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::offsetSet
235 */
236 public function offsetSet($object, $info) {
237 $this->initialize();
238 parent::offsetSet($object, $info);
239 }
240
241 /**
242 * @param object $object The object to remove.
243 * @return void
244 *
245 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::offsetUnset
246 */
247 public function offsetUnset($object) {
248 $this->initialize();
249 parent::offsetUnset($object);
250 }
251
252 /**
253 * @param \TYPO3\CMS\Extbase\Persistence\ObjectStorage $storage The storage containing the elements to remove.
254 * @return void
255 *
256 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::removeAll
257 */
258 public function removeAll($storage) {
259 $this->initialize();
260 parent::removeAll($storage);
261 }
262
263 /**
264 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::rewind
265 */
266 public function rewind() {
267 $this->initialize();
268 parent::rewind();
269 }
270
271 /**
272 * @return bool
273 *
274 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::valid
275 */
276 public function valid() {
277 $this->initialize();
278 return parent::valid();
279 }
280
281 /**
282 * @return array
283 *
284 * @see \TYPO3\CMS\Extbase\Persistence\ObjectStorage::toArray
285 */
286 public function toArray() {
287 $this->initialize();
288 return parent::toArray();
289 }
290
291 /**
292 * @param mixed $object
293 * @return int|NULL
294 */
295 public function getPosition($object) {
296 $this->initialize();
297 return parent::getPosition($object);
298 }
299
300 }