2 /***************************************************************
5 * (c) 2009 Jochen Rau <jochen.rau@typoplanet.de>
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.
14 * The GNU General Public License can be found at
15 * http://www.gnu.org/copyleft/gpl.html.
17 * This script is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU General Public License for more details.
22 * This copyright notice MUST APPEAR in all copies of the script!
23 ***************************************************************/
26 * A data map to map a single table configured in $TCA on a domain object.
29 * @subpackage Persistence\Mapper
32 class Tx_Extbase_Persistence_Mapper_DataMap
{
35 * The domain class name
42 * The table name corresponding to the domain class configured in $TCA
49 * An array of column maps configured in $TCA
53 protected $columnMaps;
56 * Constructs this DataMap
58 * @param string $className The class name. This determines the table to fetch the configuration for
60 // TODO Refactor to factory pattern (DataMapFactory) and value object (DataMap)
61 public function __construct($className, $tableName = '', array $mapping = array()) {
62 $this->setClassName($className);
63 if (empty($tableName)) {
64 $this->setTableName(strtolower($className));
66 $this->setTableName($tableName);
68 $this->initialize($mapping);
72 * Sets the name of the class the colum map represents
76 public function setClassName($className) {
77 $this->className
= $className;
81 * Returns the name of the class the column map represents
83 * @return string The class name
85 public function getClassName() {
86 return $this->className
;
90 * Sets the name of the table the colum map represents
94 public function setTableName($tableName) {
95 $this->tableName
= $tableName;
99 * Returns the name of the table the column map represents
101 * @return string The table name
103 public function getTableName() {
104 return $this->tableName
;
108 * Initializes the data map by adding column maps for all the configured columns in the $TCA.
109 * It also resolves the type of values the column is holding and the typo of relation the column
114 protected function initialize(array $mapping) {
115 $this->addCommonColumns();
116 $columnConfigurations = array();
117 foreach ($this->getColumnsDefinition() as $columnName => $columnDefinition) {
118 $columnConfigurations[$columnName] = $columnDefinition['config'];
119 $columnConfigurations[$columnName]['mapOnProperty'] = Tx_Extbase_Utility_Extension
::convertUnderscoredToLowerCamelCase($columnName);
121 $columnConfigurations = t3lib_div
::array_merge_recursive_overrule($columnConfigurations, $mapping);
122 foreach ($columnConfigurations as $columnName => $columnConfiguration) {
123 $columnMap = new Tx_Extbase_Persistence_Mapper_ColumnMap($columnName, $columnConfiguration['mapOnProperty']);
124 $this->setPropertyType($columnMap, $columnConfiguration);
125 $this->setRelations($columnMap, $columnConfiguration);
126 $this->addColumnMap($columnMap);
131 * Returns the TCA columns array of the specified table
133 * @param string $tableName An optional table name to fetch the columns definition from
134 * @return array The TCA columns definition
136 public function getColumnsDefinition($tableName = '') {
137 $tableName = strlen($tableName) > 0 ?
$tableName : $this->getTableName();
138 if (TYPO3_MODE
=== 'FE') {
139 $GLOBALS['TSFE']->includeTCA();
141 t3lib_div
::loadTCA($tableName);
142 $columns = is_array($GLOBALS['TCA'][$tableName]['columns']) ?
$GLOBALS['TCA'][$tableName]['columns'] : array();
147 * Adds available common columns (e.g. tstamp or crdate) to the data map. It takes the configured column names
152 protected function addCommonColumns() {
153 $this->addColumn('uid', NULL, Tx_Extbase_Persistence_PropertyType
::LONG
);
154 if ($this->hasPidColumn()) {
155 $this->addColumn('pid', NULL, Tx_Extbase_Persistence_PropertyType
::LONG
);
157 if ($this->hasTimestampColumn()) {
158 $this->addColumn($this->getTimestampColumnName(), NULL, Tx_Extbase_Persistence_PropertyType
::DATE
);
160 if ($this->hasCreationDateColumn()) {
161 $this->addColumn($this->getCreationDateColumnName(), NULL, Tx_Extbase_Persistence_PropertyType
::DATE
);
163 if ($this->hasCreatorUidColumn()) {
164 $this->addColumn($this->getCreatorUidColumnName(), NULL, Tx_Extbase_Persistence_PropertyType
::LONG
);
166 if ($this->hasDeletedColumn()) {
167 $this->addColumn($this->getDeletedColumnName(), NULL, Tx_Extbase_Persistence_PropertyType
::BOOLEAN
);
169 if ($this->hasHiddenColumn()) {
170 $this->addColumn($this->getHiddenColumnName(), NULL, Tx_Extbase_Persistence_PropertyType
::BOOLEAN
);
175 * This method tries to determine the type of value the column hold by inspectiong the $TCA column configuration
178 * @param string $columnMap The column map
179 * @param string $columnConfiguration The column configuration from $TCA
182 protected function setPropertyType(Tx_Extbase_Persistence_Mapper_ColumnMap
&$columnMap, $columnConfiguration) {
183 $evalConfiguration = t3lib_div
::trimExplode(',', $columnConfiguration['eval']);
184 if (in_array('date', $evalConfiguration) ||
in_array('datetime', $evalConfiguration)) {
185 $columnMap->setPropertyType(Tx_Extbase_Persistence_PropertyType
::DATE
);
186 } elseif ($columnConfiguration['type'] === 'check' && empty($columnConfiguration['items'])) {
187 $columnMap->setPropertyType(Tx_Extbase_Persistence_PropertyType
::BOOLEAN
);
188 } elseif (in_array('int', $evalConfiguration)) {
189 $columnMap->setPropertyType(Tx_Extbase_Persistence_PropertyType
::LONG
);
190 } elseif (in_array('double2', $evalConfiguration)) {
191 $columnMap->setPropertyType(Tx_Extbase_Persistence_PropertyType
::DOUBLE);
193 if (isset($columnConfiguration['foreign_table'])) {
194 if (isset($columnConfiguration['loadingStrategy'])) {
195 $columnMap->setLoadingStrategy($columnConfiguration['loadingStrategy']);
197 $columnMap->setLoadingStrategy(Tx_Extbase_Persistence_Mapper_ColumnMap
::STRATEGY_EAGER
);
199 $columnMap->setPropertyType(Tx_Extbase_Persistence_PropertyType
::REFERENCE
);
201 $columnMap->setPropertyType(Tx_Extbase_Persistence_PropertyType
::STRING);
207 * This method tries to determine the type of type of relation to other tables and sets it based on
208 * the $TCA column configuration
210 * @param Tx_Extbase_Persistence_Mapper_ColumnMap $columnMap The column map
211 * @param string $columnConfiguration The column configuration from $TCA
214 protected function setRelations(Tx_Extbase_Persistence_Mapper_ColumnMap
&$columnMap, $columnConfiguration) {
215 if (isset($columnConfiguration) && $columnConfiguration['type'] !== 'passthrough') {
216 if (isset($columnConfiguration['foreign_table']) && !isset($columnConfiguration['MM']) && !isset($columnConfiguration['foreign_selector'])) {
217 if ($columnConfiguration['maxitems'] == 1) {
218 $this->setOneToOneRelation($columnMap, $columnConfiguration);
220 $this->setOneToManyRelation($columnMap, $columnConfiguration);
222 } elseif (isset($columnConfiguration['MM']) ||
isset($columnConfiguration['foreign_selector'])) {
223 $this->setManyToManyRelation($columnMap, $columnConfiguration);
225 $columnMap->setTypeOfRelation(Tx_Extbase_Persistence_Mapper_ColumnMap
::RELATION_NONE
);
231 * This method sets the configuration for a 1:1 relation based on
232 * the $TCA column configuration
234 * @param string $columnMap The column map
235 * @param string $columnConfiguration The column configuration from $TCA
238 protected function setOneToOneRelation(Tx_Extbase_Persistence_Mapper_ColumnMap
&$columnMap, $columnConfiguration) {
239 $columnMap->setTypeOfRelation(Tx_Extbase_Persistence_Mapper_ColumnMap
::RELATION_HAS_ONE
);
240 $columnMap->setChildTableName($columnConfiguration['foreign_table']);
241 $columnMap->setChildTableWhereStatement($columnConfiguration['foreign_table_where']);
242 $columnMap->setChildSortbyFieldName($columnConfiguration['foreign_sortby']);
243 $columnMap->setParentKeyFieldName($columnConfiguration['foreign_field']);
244 $columnMap->setParentTableFieldName($columnConfiguration['foreign_table_field']);
248 * This method sets the configuration for a 1:n relation based on
249 * the $TCA column configuration
251 * @param string $columnMap The column map
252 * @param string $columnConfiguration The column configuration from $TCA
255 protected function setOneToManyRelation(Tx_Extbase_Persistence_Mapper_ColumnMap
&$columnMap, $columnConfiguration) {
256 $columnMap->setTypeOfRelation(Tx_Extbase_Persistence_Mapper_ColumnMap
::RELATION_HAS_MANY
);
257 $columnMap->setChildTableName($columnConfiguration['foreign_table']);
258 $columnMap->setChildTableWhereStatement($columnConfiguration['foreign_table_where']);
259 $columnMap->setChildSortbyFieldName($columnConfiguration['foreign_sortby']);
260 $columnMap->setParentKeyFieldName($columnConfiguration['foreign_field']);
261 $columnMap->setParentTableFieldName($columnConfiguration['foreign_table_field']);
265 * This method sets the configuration for a m:n relation based on
266 * the $TCA column configuration
268 * @param string $columnMap The column map
269 * @param string $columnConfiguration The column configuration from $TCA
272 protected function setManyToManyRelation(Tx_Extbase_Persistence_Mapper_ColumnMap
&$columnMap, $columnConfiguration) {
273 // TODO support multi table relationships
274 $columnMap->setTypeOfRelation(Tx_Extbase_Persistence_Mapper_ColumnMap
::RELATION_HAS_AND_BELONGS_TO_MANY
);
275 if ($columnConfiguration['type'] === 'inline') {
276 $columns = $this->getColumnsDefinition($columnConfiguration['foreign_table']);
277 $childKeyFieldName = $this->determineChildKeyFieldName($columnConfiguration);
278 $columnMap->setChildTableName($columns[$childKeyFieldName]['config']['foreign_table']);
279 $columnMap->setRelationTableName($columnConfiguration['foreign_table']);
280 $columnMap->setParentKeyFieldName($columnConfiguration['foreign_field']);
281 $columnMap->setChildKeyFieldName($childKeyFieldName);
282 $columnMap->setChildSortByFieldName($columnConfiguration['foreign_sortby']);
284 $columnMap->setChildTableName($columnConfiguration['foreign_table']);
285 $columnMap->setChildTableWhereStatement($columnConfiguration['foreign_table_where']);
286 $columnMap->setRelationTableName($columnConfiguration['MM']);
287 if (is_array($columnConfiguration['MM_match_fields'])) {
288 $columnMap->setRelationTableMatchFields($columnConfiguration['MM_match_fields']);
290 if (is_array($columnConfiguration['MM_insert_fields'])) {
291 $columnMap->setRelationTableInsertFields($columnConfiguration['MM_insert_fields']);
293 $columnMap->setRelationTableWhereStatement($columnConfiguration['MM_table_where']);
294 if (!empty($columnConfiguration['MM_opposite_field'])) {
295 $columnMap->setParentKeyFieldName('uid_foreign');
296 $columnMap->setChildKeyFieldName('uid_local');
297 $columnMap->setChildSortByFieldName('sorting_foreign');
299 $columnMap->setParentKeyFieldName('uid_local');
300 $columnMap->setChildKeyFieldName('uid_foreign');
301 $columnMap->setChildSortByFieldName('sorting');
307 * This method returns the foreign key field name in the relation table. For IRRE setups it will return
308 * the foreign_label; if not present the foreign_selector. Default is uid_foreign.
310 * @param string $columnConfiguration The column configuration of the parent table relation field
311 * @return string The foreign key field name of the relation table
313 public function determineChildKeyFieldName($columnConfiguration) {
314 if (isset($columnConfiguration['foreign_label'])) {
315 $childKeyFieldName = $columnConfiguration['foreign_label'];
316 } elseif (isset($columnConfiguration['foreign_selector'])) {
317 $childKeyFieldName = $columnConfiguration['foreign_selector'];
319 $childKeyFieldName = 'uid_foreign';
321 return $childKeyFieldName;
325 * Sets the column maps.
327 * @param array $columnMaps The column maps stored in a flat array.
330 public function setColumnMaps(array $columnMaps) {
331 $this->columnMaps
= $columnMaps;
335 * Adds a given column map to the data map.
337 * @param Tx_Extbase_Persistence_Mapper_ColumnMap $columnMap The column map
340 public function addColumnMap(Tx_Extbase_Persistence_Mapper_ColumnMap
$columnMap) {
341 $this->columnMaps
[$columnMap->getPropertyName()] = $columnMap;
345 * Builds a column map out of the given column name, type of value (optional), and type of
346 * relation (optional) and adds it to the data map.
348 * @param string $columnName The column name
349 * @param string $propertyName The property name
350 * @param string $propertyType The type of value (default: string)
351 * @param string $typeOfRelation The type of relation (default: none)
352 * @return Tx_Extbase_Persistence_Mapper_DataMap Returns itself for a fluent interface
354 public function addColumn($columnName, $propertyName = '', $propertyType = Tx_Extbase_Persistence_PropertyType
::STRING, $typeOfRelation = Tx_Extbase_Persistence_Mapper_ColumnMap
::RELATION_NONE
) {
355 if (empty($propertyName)) {
356 $propertyName = Tx_Extbase_Utility_Extension
::convertUnderscoredToLowerCamelCase($columnName);
359 $columnMap = new Tx_Extbase_Persistence_Mapper_ColumnMap($columnName, $propertyName);
360 $columnMap->setPropertyType($propertyType);
361 $columnMap->setTypeOfRelation($typeOfRelation);
362 $this->addColumnMap($columnMap);
367 * Returns all column maps
369 * @return array The column maps
371 public function getColumnMaps() {
372 return $this->columnMaps
;
376 * Returns the column map corresponding to the given property name.
378 * @param string $propertyName
379 * @return Tx_Extbase_Persistence_Mapper_ColumnMap|NULL The column map or NULL if no corresponding column map was found.
381 public function getColumnMap($propertyName) {
382 return $this->columnMaps
[$propertyName];
386 * Returns TRUE if the property is persistable (configured in $TCA)
388 * @param string $propertyName The property name
389 * @return boolean TRUE if the property is persistable (configured in $TCA)
391 public function isPersistableProperty($propertyName) {
392 return isset($this->columnMaps
[$propertyName]);
396 * Check if versioning is enabled .
400 public function isVersionable() {
401 return ($GLOBALS['TCA'] [$this->tableName
] ['ctrl'] ['versioningWS'] === '1');
405 * Returns TRUE if the table has a pid column holding the id of the page the record is virtually stored on.
406 * Currently we don't support tables without a pid column.
408 * @return boolean The result
410 public function hasPidColumn() {
411 // TODO Should we implement a check for having a pid column?
416 * Returns the name of a column holding the timestamp the record was modified
418 * @return string The field name
420 public function getTimestampColumnName() {
421 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['tstamp'];
425 * Returns TRUE if the table has a column holding the timestamp the record was modified
427 * @return boolean The result
429 public function hasTimestampColumn() {
430 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['tstamp']);
434 * Returns the name of a column holding the creation date timestamp
436 * @return string The field name
438 public function getCreationDateColumnName() {
439 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['crdate'];
443 * Returns TRUE if the table has olumn holding the creation date timestamp
445 * @return boolean The result
447 public function hasCreationDateColumn() {
448 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['crdate']);
452 * Returns the name of a column holding the uid of the back-end user who created this record
454 * @return string The field name
456 public function getCreatorUidColumnName() {
457 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['cruser_id'];
461 * Returns TRUE if the table has a column holding the uid of the back-end user who created this record
463 * @return boolean The result
465 public function hasCreatorUidColumn() {
466 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['cruser_id']);
470 * Returns the name of a column indicating the 'deleted' state of the row
472 * @return string The field name
474 public function getDeletedColumnName() {
475 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['delete'];
479 * Returns TRUE if the table has a column indicating the 'deleted' state of the row
481 * @return boolean The result
483 public function hasDeletedColumn() {
484 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['delete']);
488 * Returns the name of a column indicating the 'hidden' state of the row
490 * @return string The field name
492 public function getHiddenColumnName() {
493 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['disabled'];
497 * Returns TRUE if the table has a column indicating the 'hidden' state of the row
499 * @return boolean The result
501 public function hasHiddenColumn() {
502 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['disabled']);
506 * Returns the name of a column holding the timestamp the record should not displayed before
508 * @return string The field name
510 public function getStartTimeColumnName() {
511 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['starttime'];
515 * Returns TRUE if the table has a column holding the timestamp the record should not displayed before
517 * @return boolean The result
519 public function hasStartTimeColumn() {
520 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['starttime']);
524 * Returns the name of a column holding the timestamp the record should not displayed afterwards
526 * @return string The field name
528 public function getEndTimeColumnName() {
529 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['endtime'];
533 * Returns TRUE if the table has a column holding the timestamp the record should not displayed afterwards
535 * @return boolean The result
537 public function hasEndTimeColumn() {
538 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['endtime']);
542 * Returns the name of a column holding the uid of the front-end user group which is allowed to edit this record
544 * @return string The field name
546 public function getFrontEndUserGroupColumnName() {
547 return $GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['fe_group'];
551 * Returns TRUE if the table has a column holding the uid of the front-end user group which is allowed to edit this record
553 * @return boolean The result
555 public function hasFrontEndUserGroupColumn() {
556 return !empty($GLOBALS['TCA'][$this->getTableName()]['ctrl']['enablecolumns']['fe_group']);
560 * Converts a field name to the property name. It respects property name aliases defined in $TCA.
562 * @param string $fieldName The field name
563 * @return string $propertyName The property name
565 public function convertFieldNameToPropertyName($fieldName) {
566 $propertyName = $fieldName;
567 return $propertyName; // TODO Implement aliases for field names (see also convertPropertyNameToFieldName())
571 * Converts a preoperty name to the field name. It respects property name aliases defined in $TCA.
573 * @param string $fieldName The field name
574 * @return string $propertyName The property name
576 public function convertPropertyNameToFieldName($propertyName) {
577 $fieldName = $propertyName;
582 * Converts the given string into the given type
584 * @param integer $type one of the constants defined in Tx_Extbase_Persistence_PropertyType
585 * @param string $string a string representing a value of the given type
587 * @return string|int|float|DateTime|boolean
589 public function convertFieldValueToPropertyValue($type, $string) {
591 case Tx_Extbase_Persistence_PropertyType
::LONG
:
592 return (int) $string;
593 case Tx_Extbase_Persistence_PropertyType
::DOUBLE:
594 case Tx_Extbase_Persistence_PropertyType
::DECIMAL
:
595 return (float) $string;
596 case Tx_Extbase_Persistence_PropertyType
::DATE
:
597 return new DateTime(date('r', $string));
598 case Tx_Extbase_Persistence_PropertyType
::BOOLEAN
:
599 return (boolean
) $string;
606 * Converts a value from a property type to a database field type
608 * @param mixed $propertyValue The property value
609 * @return mixed The converted value
611 public function convertPropertyValueToFieldValue($propertyValue) {
612 if (is_bool($propertyValue)) {
613 $convertedValue = $propertyValue ?
1 : 0;
614 } elseif ($propertyValue instanceof Tx_Extbase_DomainObject_AbstractDomainObject
) {
615 $convertedValue = $propertyValue->getUid();
616 } elseif (is_a($propertyValue, 'DateTime')) {
617 $convertedValue = $propertyValue->format('U');
618 } elseif (is_int($propertyValue)) {
619 $convertedValue = $propertyValue;
621 $convertedValue = $propertyValue;
623 return $convertedValue;