[TASK] Streamline phpdoc annotations in EXT:extbase
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Persistence / Generic / PersistenceManager.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\Persistence\ObjectStorage;
18 use TYPO3\CMS\Extbase\Persistence\QueryInterface;
19
20 /**
21 * The Extbase Persistence Manager
22 */
23 class PersistenceManager implements \TYPO3\CMS\Extbase\Persistence\PersistenceManagerInterface, \TYPO3\CMS\Core\SingletonInterface
24 {
25 /**
26 * @var array
27 */
28 protected $newObjects = [];
29
30 /**
31 * @var ObjectStorage
32 */
33 protected $changedObjects;
34
35 /**
36 * @var ObjectStorage
37 */
38 protected $addedObjects;
39
40 /**
41 * @var ObjectStorage
42 */
43 protected $removedObjects;
44
45 /**
46 * @var \TYPO3\CMS\Extbase\Persistence\Generic\QueryFactoryInterface
47 */
48 protected $queryFactory;
49
50 /**
51 * @var \TYPO3\CMS\Extbase\Persistence\Generic\BackendInterface
52 */
53 protected $backend;
54
55 /**
56 * @var \TYPO3\CMS\Extbase\Persistence\Generic\Session
57 */
58 protected $persistenceSession;
59
60 /**
61 * @param \TYPO3\CMS\Extbase\Persistence\Generic\QueryFactoryInterface $queryFactory
62 * @internal only to be used within Extbase, not part of TYPO3 Core API.
63 */
64 public function injectQueryFactory(\TYPO3\CMS\Extbase\Persistence\Generic\QueryFactoryInterface $queryFactory)
65 {
66 $this->queryFactory = $queryFactory;
67 }
68
69 /**
70 * @param \TYPO3\CMS\Extbase\Persistence\Generic\BackendInterface $backend
71 * @internal only to be used within Extbase, not part of TYPO3 Core API.
72 */
73 public function injectBackend(\TYPO3\CMS\Extbase\Persistence\Generic\BackendInterface $backend)
74 {
75 $this->backend = $backend;
76 }
77
78 /**
79 * @param \TYPO3\CMS\Extbase\Persistence\Generic\Session $persistenceSession
80 * @internal only to be used within Extbase, not part of TYPO3 Core API.
81 */
82 public function injectPersistenceSession(\TYPO3\CMS\Extbase\Persistence\Generic\Session $persistenceSession)
83 {
84 $this->persistenceSession = $persistenceSession;
85 }
86
87 /**
88 * Create new instance
89 * @internal only to be used within Extbase, not part of TYPO3 Core API.
90 */
91 public function __construct()
92 {
93 $this->addedObjects = new ObjectStorage();
94 $this->removedObjects = new ObjectStorage();
95 $this->changedObjects = new ObjectStorage();
96 }
97
98 /**
99 * Registers a repository
100 *
101 * @param string $className The class name of the repository to be registered
102 * @internal only to be used within Extbase, not part of TYPO3 Core API.
103 */
104 public function registerRepositoryClassName($className)
105 {
106 }
107
108 /**
109 * Returns the number of records matching the query.
110 *
111 * @param QueryInterface $query
112 * @return int
113 */
114 public function getObjectCountByQuery(QueryInterface $query)
115 {
116 return $this->backend->getObjectCountByQuery($query);
117 }
118
119 /**
120 * Returns the object data matching the $query.
121 *
122 * @param QueryInterface $query
123 * @return array
124 */
125 public function getObjectDataByQuery(QueryInterface $query)
126 {
127 return $this->backend->getObjectDataByQuery($query);
128 }
129
130 /**
131 * Returns the (internal) identifier for the object, if it is known to the
132 * backend. Otherwise NULL is returned.
133 *
134 * Note: this returns an identifier even if the object has not been
135 * persisted in case of AOP-managed entities. Use isNewObject() if you need
136 * to distinguish those cases.
137 *
138 * @param object $object
139 * @return mixed The identifier for the object if it is known, or NULL
140 */
141 public function getIdentifierByObject($object)
142 {
143 return $this->backend->getIdentifierByObject($object);
144 }
145
146 /**
147 * Returns the object with the (internal) identifier, if it is known to the
148 * backend. Otherwise NULL is returned.
149 *
150 * @param mixed $identifier
151 * @param string $objectType
152 * @param bool $useLazyLoading Set to TRUE if you want to use lazy loading for this object
153 * @return object The object for the identifier if it is known, or NULL
154 */
155 public function getObjectByIdentifier($identifier, $objectType = null, $useLazyLoading = false)
156 {
157 if (isset($this->newObjects[$identifier])) {
158 return $this->newObjects[$identifier];
159 }
160 if ($this->persistenceSession->hasIdentifier($identifier, $objectType)) {
161 return $this->persistenceSession->getObjectByIdentifier($identifier, $objectType);
162 }
163 return $this->backend->getObjectByIdentifier($identifier, $objectType);
164 }
165
166 /**
167 * Commits new objects and changes to objects in the current persistence
168 * session into the backend.
169 */
170 public function persistAll()
171 {
172 // hand in only aggregate roots, leaving handling of subobjects to
173 // the underlying storage layer
174 // reconstituted entities must be fetched from the session and checked
175 // for changes by the underlying backend as well!
176 $this->backend->setAggregateRootObjects($this->addedObjects);
177 $this->backend->setChangedEntities($this->changedObjects);
178 $this->backend->setDeletedEntities($this->removedObjects);
179 $this->backend->commit();
180
181 $this->addedObjects = new ObjectStorage();
182 $this->removedObjects = new ObjectStorage();
183 $this->changedObjects = new ObjectStorage();
184 }
185
186 /**
187 * Return a query object for the given type.
188 *
189 * @param string $type
190 * @return QueryInterface
191 * @internal only to be used within Extbase, not part of TYPO3 Core API.
192 */
193 public function createQueryForType($type)
194 {
195 return $this->queryFactory->create($type);
196 }
197
198 /**
199 * Adds an object to the persistence.
200 *
201 * @param object $object The object to add
202 */
203 public function add($object)
204 {
205 $this->addedObjects->attach($object);
206 $this->removedObjects->detach($object);
207 }
208
209 /**
210 * Removes an object to the persistence.
211 *
212 * @param object $object The object to remove
213 */
214 public function remove($object)
215 {
216 if ($this->addedObjects->contains($object)) {
217 $this->addedObjects->detach($object);
218 } else {
219 $this->removedObjects->attach($object);
220 }
221 }
222
223 /**
224 * Update an object in the persistence.
225 *
226 * @param object $object The modified object
227 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\UnknownObjectException
228 */
229 public function update($object)
230 {
231 if ($this->isNewObject($object)) {
232 throw new \TYPO3\CMS\Extbase\Persistence\Exception\UnknownObjectException('The object of type "' . get_class($object) . '" given to update must be persisted already, but is new.', 1249479819);
233 }
234 $this->changedObjects->attach($object);
235 }
236
237 /**
238 * Injects the Extbase settings, called by Extbase.
239 *
240 * @param array $settings
241 * @throws \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException
242 */
243 public function injectSettings(array $settings)
244 {
245 throw new \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException(__METHOD__, 1476108078);
246 }
247
248 /**
249 * Initializes the persistence manager, called by Extbase.
250 * @internal only to be used within Extbase, not part of TYPO3 Core API.
251 */
252 public function initializeObject()
253 {
254 $this->backend->setPersistenceManager($this);
255 }
256
257 /**
258 * Clears the in-memory state of the persistence.
259 *
260 * Managed instances become detached, any fetches will
261 * return data directly from the persistence "backend".
262 *
263 * @throws \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException
264 * @internal only to be used within Extbase, not part of TYPO3 Core API.
265 */
266 public function clearState()
267 {
268 $this->newObjects = [];
269 $this->addedObjects = new ObjectStorage();
270 $this->removedObjects = new ObjectStorage();
271 $this->changedObjects = new ObjectStorage();
272 $this->persistenceSession->destroy();
273 }
274
275 /**
276 * Checks if the given object has ever been persisted.
277 *
278 * @param object $object The object to check
279 * @return bool TRUE if the object is new, FALSE if the object exists in the persistence session
280 */
281 public function isNewObject($object)
282 {
283 return $this->persistenceSession->hasObject($object) === false;
284 }
285
286 /**
287 * Registers an object which has been created or cloned during this request.
288 *
289 * A "new" object does not necessarily
290 * have to be known by any repository or be persisted in the end.
291 *
292 * Objects registered with this method must be known to the getObjectByIdentifier()
293 * method.
294 *
295 * @param object $object The new object to register
296 * @internal only to be used within Extbase, not part of TYPO3 Core API.
297 */
298 public function registerNewObject($object)
299 {
300 $identifier = $this->getIdentifierByObject($object);
301 $this->newObjects[$identifier] = $object;
302 }
303
304 /**
305 * Converts the given object into an array containing the identity of the domain object.
306 *
307 * @param object $object The object to be converted
308 * @throws Exception\NotImplementedException
309 */
310 public function convertObjectToIdentityArray($object)
311 {
312 throw new \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException(__METHOD__, 1476108103);
313 }
314
315 /**
316 * Recursively iterates through the given array and turns objects
317 * into arrays containing the identity of the domain object.
318 *
319 * @throws \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException
320 * @param array $array The array to be iterated over
321 * @see convertObjectToIdentityArray()
322 */
323 public function convertObjectsToIdentityArrays(array $array)
324 {
325 throw new \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException(__METHOD__, 1476108111);
326 }
327
328 /**
329 * Tear down the persistence
330 *
331 * This method is called in functional tests to reset the storage between tests.
332 * The implementation is optional and depends on the underlying persistence backend.
333 * @internal only to be used within Extbase, not part of TYPO3 Core API.
334 */
335 public function tearDown()
336 {
337 if (method_exists($this->backend, 'tearDown')) {
338 $this->backend->tearDown();
339 }
340 }
341 }