[BUGFIX] Unused argument in getItemUidList()
[Packages/TYPO3.CMS.git] / t3lib / collection / AbstractRecordCollection.php
1 <?php
2 /***************************************************************
3 * Copyright notice
4 *
5 * (c) 2011 Steffen Ritter <typo3@steffen-ritter.net>
6 * All rights reserved
7 *
8 * This script is part of the TYPO3 project. The TYPO3 project is
9 * free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
13 *
14 * The GNU General Public License can be found at
15 * http://www.gnu.org/copyleft/gpl.html.
16 * A copy is found in the textfile GPL.txt and important notices to the license
17 * from the author is found in LICENSE.txt distributed with these scripts.
18 *
19 *
20 * This script is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU General Public License for more details.
24 *
25 * This copyright notice MUST APPEAR in all copies of the script!
26 ***************************************************************/
27
28
29 /**
30 * Abstract implementation of a RecordCollection
31 *
32 * RecordCollection is a collections of TCA-Records.
33 * The collection is meant to be stored in TCA-table sys_collections and is manageable
34 * via TCEforms.
35 *
36 * A RecordCollection might be used to group a set of records (e.g. news, images, contentElements)
37 * for output in frontend
38 *
39 * The AbstractRecordCollection uses SplDoublyLinkedList for internal storage
40 *
41 * @author Steffen Ritter <typo3@steffen-ritter.net>
42 * @abstract
43 * @package TYPO3
44 * @subpackage t3lib
45 */
46 abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collection_RecordCollection, t3lib_collection_Persistable, t3lib_collection_Sortable {
47 /**
48 * The table name collections are stored to
49 *
50 * @var string
51 */
52 protected static $storageTableName = 'sys_collection';
53
54 /**
55 * The table name collections are stored to
56 *
57 * @var string
58 */
59 protected static $storageItemsField = 'items';
60
61 /**
62 * Uid of the storage
63 *
64 * @var int
65 */
66 protected $uid = 0;
67
68 /**
69 * Collection title
70 *
71 * @var string
72 */
73 protected $title;
74
75 /**
76 * Collection description
77 *
78 * @var string
79 */
80 protected $description;
81
82 /**
83 * Table name of the records stored in this collection
84 *
85 * @var string
86 */
87 protected $itemTableName;
88
89 /**
90 * The local storage
91 *
92 * @var SplDoublyLinkedList
93 */
94 protected $storage;
95
96 /**
97 * Creates this object.
98 */
99 public function __construct() {
100 $this->storage = new SplDoublyLinkedList();
101 }
102
103 /**
104 * (PHP 5 &gt;= 5.1.0)<br/>
105 * Return the current element
106 *
107 * @link http://php.net/manual/en/iterator.current.php
108 * @return mixed Can return any type.
109 */
110 public function current() {
111 return $this->storage->current();
112 }
113
114 /**
115 * (PHP 5 &gt;= 5.1.0)<br/>
116 * Move forward to next element
117 *
118 * @link http://php.net/manual/en/iterator.next.php
119 * @return void Any returned value is ignored.
120 */
121 public function next() {
122 $this->storage->next();
123 }
124
125 /**
126 * (PHP 5 &gt;= 5.1.0)<br/>
127 * Return the key of the current element
128 *
129 * @link http://php.net/manual/en/iterator.key.php
130 * @return integer
131 * 0 on failure.
132 */
133 public function key() {
134 $currentRecord = $this->storage->current();
135 return $currentRecord['uid'];
136 }
137
138 /**
139 * (PHP 5 &gt;= 5.1.0)<br/>
140 * Checks if current position is valid
141 *
142 * @link http://php.net/manual/en/iterator.valid.php
143 * @return boolean The return value will be casted to boolean and then evaluated.
144 * Returns true on success or false on failure.
145 */
146 public function valid() {
147 return $this->storage->valid();
148 }
149
150 /**
151 * (PHP 5 &gt;= 5.1.0)<br/>
152 * Rewind the Iterator to the first element
153 *
154 * @link http://php.net/manual/en/iterator.rewind.php
155 * @return void Any returned value is ignored.
156 */
157 public function rewind() {
158 $this->storage->rewind();
159 }
160
161 /**
162 * (PHP 5 &gt;= 5.1.0)<br/>
163 * String representation of object
164 *
165 * @link http://php.net/manual/en/serializable.serialize.php
166 * @return string the string representation of the object or &null;
167 */
168 public function serialize() {
169 $data = array(
170 'uid' => $this->getIdentifier(),
171 );
172 return serialize($data);
173 }
174
175 /**
176 * (PHP 5 &gt;= 5.1.0)<br/>
177 * Constructs the object
178 *
179 * @link http://php.net/manual/en/serializable.unserialize.php
180 * @param string $serialized <p>
181 * The string representation of the object.
182 * </p>
183 * @return mixed the original value unserialized.
184 */
185 public function unserialize($serialized) {
186 $data = unserialize($serialized);
187 return self::load($data['uid']);
188 }
189
190 /**
191 * (PHP 5 &gt;= 5.1.0)<br/>
192 * Count elements of an object
193 *
194 * @link http://php.net/manual/en/countable.count.php
195 * @return int The custom count as an integer.
196 * </p>
197 * <p>
198 * The return value is cast to an integer.
199 */
200 public function count() {
201 return $this->storage->count();
202 }
203
204 /**
205 * Getter for the title
206 *
207 * @return string
208 */
209 public function getTitle() {
210 return $this->title;
211 }
212
213 /**
214 * Getter for the description
215 *
216 * @return string
217 */
218 public function getDescription() {
219 return $this->description;
220 }
221
222 /**
223 * Setter for the title
224 *
225 * @param string $title
226 * @return void
227 */
228 public function setTitle($title) {
229 $this->title = $title;
230 }
231
232 /**
233 * Setter for the description
234 *
235 * @param string $desc
236 * @return void
237 */
238 public function setDescription($desc) {
239 $this->description = $desc;
240 }
241
242 /**
243 * Setter for the name of the data-source table
244 *
245 * @return string
246 */
247 public function getItemTableName() {
248 return $this->itemTableName;
249 }
250
251 /**
252 * Setter for the name of the data-source table
253 *
254 * @param string $tableName
255 * @return void
256 */
257 public function setItemTableName($tableName) {
258 $this->itemTableName = $tableName;
259 }
260
261 /**
262 * Sorts collection via given callBackFunction
263 *
264 * The comparison function given as must return an integer less than, equal to, or greater than
265 * zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
266 *
267 * @param $callbackFunction
268 * @see http://www.php.net/manual/en/function.usort.php
269 * @return void
270 */
271 public function usort($callbackFunction) {
272 // TODO: Implement usort() method with TCEforms in mind
273 throw new RuntimeException('This method is not yet supported.', 1322545589);
274 }
275
276 /**
277 * Moves the item within the collection
278 *
279 * the item at $currentPosition will be moved to
280 * $newPosition. Ommiting $newPosition will move to top.
281 *
282 * @param int $currentPosition
283 * @param int $newPosition
284 * @return void
285 */
286 public function moveItemAt($currentPosition, $newPosition = 0) {
287 // TODO: Implement usort() method with TCEforms in mind
288 throw new RuntimeException('This method is not yet supported.', 1322545626);
289 }
290
291
292 /**
293 * Returns the uid of the collection
294 *
295 * @return integer
296 */
297 public function getIdentifier() {
298 return $this->uid;
299 }
300
301 /**
302 * Sets the identifier of the collection
303 *
304 * @param int $id
305 * @return void
306 */
307 public function setIdentifier($id) {
308 $this->uid = intval($id);
309 }
310
311
312 /**
313 * Loads the collections with the given id from persistence
314 *
315 * For memory reasons, per default only f.e. title, database-table,
316 * identifier (what ever static data is defined) is loaded.
317 * Entries can be load on first access.
318 *
319 * @static
320 * @param integer $id Id of database record to be loaded
321 * @param boolean $fillItems Populates the entries directly on load, might be bad for memory on large collections
322 * @return t3lib_collection_Collection
323 */
324 public static function load($id, $fillItems = FALSE) {
325 t3lib_div::loadTCA(static::$storageTableName);
326
327 $collectionRecord = $GLOBALS['TYPO3_DB']->exec_SELECTgetSingleRow(
328 '*',
329 static::$storageTableName,
330 'uid=' . intval($id) . t3lib_BEfunc::deleteClause(static::$storageTableName)
331 );
332
333 return self::create($collectionRecord, $fillItems);
334 }
335
336 /**
337 * Creates a new collection objects and reconstitutes the
338 * given database record to the new object.
339 *
340 * @static
341 * @param array $collectionRecord Database record
342 * @param bool $fillItems Populates the entries directly on load, might be bad for memory on large collections
343 * @return t3lib_collection_Collection
344 */
345 public static function create(array $collectionRecord, $fillItems = FALSE) {
346 $collection = new static();
347 $collection->fromArray($collectionRecord);
348
349 if ($fillItems) {
350 $collection->loadContents();
351 }
352
353 return $collection;
354 }
355
356 /**
357 * Persists current collection state to underlying storage
358 *
359 * @return void
360 */
361 public function persist() {
362 $uid = $this->getIdentifier() == 0 ? 'NEW' . rand(100000, 999999) : $this->getIdentifier();
363 $data = array(
364 trim(static::$storageTableName) => array(
365 $uid => $this->getPersistableDataArray()
366 )
367 );
368 // new records always must have a pid
369 if ($this->getIdentifier() == 0) {
370 $data[trim(static::$storageTableName)][$uid]['pid'] = 0;
371 }
372
373 /** @var t3lib_TCEmain $tce */
374 $tce = t3lib_div::makeInstance('t3lib_TCEmain');
375 $tce->stripslashes_values = 0;
376 $tce->start($data, array());
377 $tce->process_datamap();
378 }
379
380 /**
381 * Returns an array of the persistable properties and contents
382 * which are processable by TCEmain.
383 *
384 * for internal usage in persist only.
385 *
386 * @abstract
387 * @return array
388 */
389 abstract protected function getPersistableDataArray();
390
391 /**
392 * Generates comma-separated list of entry uids for usage in TCEmain
393 *
394 * also allow to add table name, if it might be needed by TCEmain for
395 * storing the relation
396 *
397 * @param boolean $includeTableName
398 * @return string
399 */
400 protected function getItemUidList($includeTableName = TRUE) {
401 $list = array();
402 foreach ($this->storage as $entry) {
403 $list[] = ($includeTableName ? $this->getItemTableName() . '_' : '') . $entry['uid'];
404 }
405 return implode(',', $list);
406 }
407
408 /**
409 * Builds an array representation of this collection
410 *
411 * @return array
412 */
413 public function toArray() {
414 $itemArray = array();
415 foreach ($this->storage as $item) {
416 $itemArray[] = $item;
417 }
418 return array(
419 'uid' => $this->getIdentifier(),
420 'title' => $this->getTitle(),
421 'description' => $this->getDescription(),
422 'table_name' => $this->getItemTableName(),
423 'items' => $itemArray
424 );
425 }
426
427 /**
428 * Loads the properties of this collection from an array
429 *
430 * @param array $array
431 * @return void
432 */
433 public function fromArray(array $array) {
434 $this->uid = $array['uid'];
435 $this->title = $array['title'];
436 $this->description = $array['description'];
437 $this->itemTableName = $array['table_name'];
438 }
439 }
440 ?>