vendor/doctrine/orm/lib/Doctrine/ORM/Query/ResultSetMapping.php

   1 <?php
   2 /*
   3  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   4  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   5  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   6  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   7  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   8  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   9  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  10  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  11  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  12  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  13  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14  *
  15  * This software consists of voluntary contributions made by many individuals
  16  * and is licensed under the MIT license. For more information, see
  17  * <http://www.doctrine-project.org>.
  18  */
  19
  20 namespace Doctrine\ORM\Query;
  21
  22 /**
  23  * A ResultSetMapping describes how a result set of an SQL query maps to a Doctrine result.
  24  *
  25  * IMPORTANT NOTE:
  26  * The properties of this class are only public for fast internal READ access and to (drastically)
  27  * reduce the size of serialized instances for more effective caching due to better (un-)serialization
  28  * performance.
  29  *
  30  * <b>Users should use the public methods.</b>
  31  *
  32  * @author Roman Borschel <roman@code-factory.org>
  33  * @since 2.0
  34  * @todo Think about whether the number of lookup maps can be reduced.
  35  */
  36 class ResultSetMapping
  37 {
  38     /**
  39      * @ignore
  40      * @var boolean Whether the result is mixed (contains scalar values together with field values).
  41      */
  42     public $isMixed = false;
  43
  44     /**
  45      * @ignore
  46      * @var array Maps alias names to class names.
  47      */
  48     public $aliasMap = array();
  49
  50     /**
  51      * @ignore
  52      * @var array Maps alias names to related association field names.
  53      */
  54     public $relationMap = array();
  55
  56     /**
  57      * @ignore
  58      * @var array Maps alias names to parent alias names.
  59      */
  60     public $parentAliasMap = array();
  61
  62     /**
  63      * @ignore
  64      * @var array Maps column names in the result set to field names for each class.
  65      */
  66     public $fieldMappings = array();
  67
  68     /**
  69      * @ignore
  70      * @var array Maps column names in the result set to the alias/field name to use in the mapped result.
  71      */
  72     public $scalarMappings = array();
  73
  74     /**
  75      * @ignore
  76      * @var array Maps column names in the result set to the alias/field type to use in the mapped result.
  77      */
  78     public $typeMappings = array();
  79
  80     /**
  81      * @ignore
  82      * @var array Maps entities in the result set to the alias name to use in the mapped result.
  83      */
  84     public $entityMappings = array();
  85
  86     /**
  87      * @ignore
  88      * @var array Maps column names of meta columns (foreign keys, discriminator columns, ...) to field names.
  89      */
  90     public $metaMappings = array();
  91
  92     /**
  93      * @ignore
  94      * @var array Maps column names in the result set to the alias they belong to.
  95      */
  96     public $columnOwnerMap = array();
  97
  98     /**
  99      * @ignore
 100      * @var array List of columns in the result set that are used as discriminator columns.
 101      */
 102     public $discriminatorColumns = array();
 103
 104     /**
 105      * @ignore
 106      * @var array Maps alias names to field names that should be used for indexing.
 107      */
 108     public $indexByMap = array();
 109
 110     /**
 111      * @ignore
 112      * @var array Map from column names to class names that declare the field the column is mapped to.
 113      */
 114     public $declaringClasses = array();
 115
 116     /**
 117      * @var array This is necessary to hydrate derivate foreign keys correctly.
 118      */
 119     public $isIdentifierColumn = array();
 120
 121     /**
 122      * Adds an entity result to this ResultSetMapping.
 123      *
 124      * @param string $class The class name of the entity.
 125      * @param string $alias The alias for the class. The alias must be unique among all entity
 126      *                      results or joined entity results within this ResultSetMapping.
 127      * @param string $resultAlias The result alias with which the entity result should be
 128      *                            placed in the result structure.
 129      * @return ResultSetMapping This ResultSetMapping instance.
 130      * @todo Rename: addRootEntity
 131      */
 132     public function addEntityResult($class, $alias, $resultAlias = null)
 133     {
 134         $this->aliasMap[$alias] = $class;
 135         $this->entityMappings[$alias] = $resultAlias;
 136
 137         if ($resultAlias !== null) {
 138             $this->isMixed = true;
 139         }
 140
 141         return $this;
 142     }
 143
 144     /**
 145      * Sets a discriminator column for an entity result or joined entity result.
 146      * The discriminator column will be used to determine the concrete class name to
 147      * instantiate.
 148      *
 149      * @param string $alias The alias of the entity result or joined entity result the discriminator
 150      *                      column should be used for.
 151      * @param string $discrColumn The name of the discriminator column in the SQL result set.
 152      * @return ResultSetMapping This ResultSetMapping instance.
 153      * @todo Rename: addDiscriminatorColumn
 154      */
 155     public function setDiscriminatorColumn($alias, $discrColumn)
 156     {
 157         $this->discriminatorColumns[$alias] = $discrColumn;
 158         $this->columnOwnerMap[$discrColumn] = $alias;
 159
 160         return $this;
 161     }
 162
 163     /**
 164      * Sets a field to use for indexing an entity result or joined entity result.
 165      *
 166      * @param string $alias The alias of an entity result or joined entity result.
 167      * @param string $fieldName The name of the field to use for indexing.
 168      * @return ResultSetMapping This ResultSetMapping instance.
 169      */
 170     public function addIndexBy($alias, $fieldName)
 171     {
 172         $found = false;
 173
 174         foreach ($this->fieldMappings as $columnName => $columnFieldName) {
 175             if ( ! ($columnFieldName === $fieldName && $this->columnOwnerMap[$columnName] === $alias)) continue;
 176
 177             $this->addIndexByColumn($alias, $columnName);
 178             $found = true;
 179
 180             break;
 181         }
 182
 183         /* TODO: check if this exception can be put back, for now it's gone because of assumptions made by some ORM internals
 184         if ( ! $found) {
 185             $message = sprintf(
 186                 'Cannot add index by for DQL alias %s and field %s without calling addFieldResult() for them before.',
 187                 $alias,
 188                 $fieldName
 189             );
 190
 191             throw new \LogicException($message);
 192         }
 193         */
 194
 195         return $this;
 196     }
 197
 198     /**
 199      * Set to index by a scalar result column name
 200      *
 201      * @param $resultColumnName
 202      * @return ResultSetMapping This ResultSetMapping instance.
 203      */
 204     public function addIndexByScalar($resultColumnName)
 205     {
 206         $this->indexByMap['scalars'] = $resultColumnName;
 207
 208         return $this;
 209     }
 210
 211     /**
 212      * Sets a column to use for indexing an entity or joined entity result by the given alias name.
 213      *
 214      * @param $alias
 215      * @param $resultColumnName
 216      * @return ResultSetMapping This ResultSetMapping instance.
 217      */
 218     public function addIndexByColumn($alias, $resultColumnName)
 219     {
 220         $this->indexByMap[$alias] = $resultColumnName;
 221
 222         return $this;
 223     }
 224
 225     /**
 226      * Checks whether an entity result or joined entity result with a given alias has
 227      * a field set for indexing.
 228      *
 229      * @param string $alias
 230      * @return boolean
 231      * @todo Rename: isIndexed($alias)
 232      */
 233     public function hasIndexBy($alias)
 234     {
 235         return isset($this->indexByMap[$alias]);
 236     }
 237
 238     /**
 239      * Checks whether the column with the given name is mapped as a field result
 240      * as part of an entity result or joined entity result.
 241      *
 242      * @param string $columnName The name of the column in the SQL result set.
 243      * @return boolean
 244      * @todo Rename: isField
 245      */
 246     public function isFieldResult($columnName)
 247     {
 248         return isset($this->fieldMappings[$columnName]);
 249     }
 250
 251     /**
 252      * Adds a field to the result that belongs to an entity or joined entity.
 253      *
 254      * @param string $alias The alias of the root entity or joined entity to which the field belongs.
 255      * @param string $columnName The name of the column in the SQL result set.
 256      * @param string $fieldName The name of the field on the declaring class.
 257      * @param string $declaringClass The name of the class that declares/owns the specified field.
 258      *                               When $alias refers to a superclass in a mapped hierarchy but
 259      *                               the field $fieldName is defined on a subclass, specify that here.
 260      *                               If not specified, the field is assumed to belong to the class
 261      *                               designated by $alias.
 262      * @return ResultSetMapping This ResultSetMapping instance.
 263      * @todo Rename: addField
 264      */
 265     public function addFieldResult($alias, $columnName, $fieldName, $declaringClass = null)
 266     {
 267         // column name (in result set) => field name
 268         $this->fieldMappings[$columnName] = $fieldName;
 269         // column name => alias of owner
 270         $this->columnOwnerMap[$columnName] = $alias;
 271         // field name => class name of declaring class
 272         $this->declaringClasses[$columnName] = $declaringClass ?: $this->aliasMap[$alias];
 273
 274         if ( ! $this->isMixed && $this->scalarMappings) {
 275             $this->isMixed = true;
 276         }
 277
 278         return $this;
 279     }
 280
 281     /**
 282      * Adds a joined entity result.
 283      *
 284      * @param string $class The class name of the joined entity.
 285      * @param string $alias The unique alias to use for the joined entity.
 286      * @param string $parentAlias The alias of the entity result that is the parent of this joined result.
 287      * @param object $relation The association field that connects the parent entity result with the joined entity result.
 288      * @return ResultSetMapping This ResultSetMapping instance.
 289      * @todo Rename: addJoinedEntity
 290      */
 291     public function addJoinedEntityResult($class, $alias, $parentAlias, $relation)
 292     {
 293         $this->aliasMap[$alias]       = $class;
 294         $this->parentAliasMap[$alias] = $parentAlias;
 295         $this->relationMap[$alias]    = $relation;
 296
 297         return $this;
 298     }
 299
 300     /**
 301      * Adds a scalar result mapping.
 302      *
 303      * @param string $columnName The name of the column in the SQL result set.
 304      * @param string $alias The result alias with which the scalar result should be placed in the result structure.
 305      * @param string $type The column type
 306      *
 307      * @return ResultSetMapping This ResultSetMapping instance.
 308      *
 309      * @todo Rename: addScalar
 310      */
 311     public function addScalarResult($columnName, $alias, $type = 'string')
 312     {
 313         $this->scalarMappings[$columnName] = $alias;
 314         $this->typeMappings[$columnName]   = $type;
 315
 316         if ( ! $this->isMixed && $this->fieldMappings) {
 317             $this->isMixed = true;
 318         }
 319
 320         return $this;
 321     }
 322
 323     /**
 324      * Checks whether a column with a given name is mapped as a scalar result.
 325      *
 326      * @param string $columName The name of the column in the SQL result set.
 327      * @return boolean
 328      * @todo Rename: isScalar
 329      */
 330     public function isScalarResult($columnName)
 331     {
 332         return isset($this->scalarMappings[$columnName]);
 333     }
 334
 335     /**
 336      * Gets the name of the class of an entity result or joined entity result,
 337      * identified by the given unique alias.
 338      *
 339      * @param string $alias
 340      * @return string
 341      */
 342     public function getClassName($alias)
 343     {
 344         return $this->aliasMap[$alias];
 345     }
 346
 347     /**
 348      * Gets the field alias for a column that is mapped as a scalar value.
 349      *
 350      * @param string $columnName The name of the column in the SQL result set.
 351      * @return string
 352      */
 353     public function getScalarAlias($columnName)
 354     {
 355         return $this->scalarMappings[$columnName];
 356     }
 357
 358     /**
 359      * Gets the name of the class that owns a field mapping for the specified column.
 360      *
 361      * @param string $columnName
 362      * @return string
 363      */
 364     public function getDeclaringClass($columnName)
 365     {
 366         return $this->declaringClasses[$columnName];
 367     }
 368
 369     /**
 370      *
 371      * @param string $alias
 372      * @return AssociationMapping
 373      */
 374     public function getRelation($alias)
 375     {
 376         return $this->relationMap[$alias];
 377     }
 378
 379     /**
 380      *
 381      * @param string $alias
 382      * @return boolean
 383      */
 384     public function isRelation($alias)
 385     {
 386         return isset($this->relationMap[$alias]);
 387     }
 388
 389     /**
 390      * Gets the alias of the class that owns a field mapping for the specified column.
 391      *
 392      * @param string $columnName
 393      * @return string
 394      */
 395     public function getEntityAlias($columnName)
 396     {
 397         return $this->columnOwnerMap[$columnName];
 398     }
 399
 400     /**
 401      * Gets the parent alias of the given alias.
 402      *
 403      * @param string $alias
 404      * @return string
 405      */
 406     public function getParentAlias($alias)
 407     {
 408         return $this->parentAliasMap[$alias];
 409     }
 410
 411     /**
 412      * Checks whether the given alias has a parent alias.
 413      *
 414      * @param string $alias
 415      * @return boolean
 416      */
 417     public function hasParentAlias($alias)
 418     {
 419         return isset($this->parentAliasMap[$alias]);
 420     }
 421
 422     /**
 423      * Gets the field name for a column name.
 424      *
 425      * @param string $columnName
 426      * @return string
 427      */
 428     public function getFieldName($columnName)
 429     {
 430         return $this->fieldMappings[$columnName];
 431     }
 432
 433     /**
 434      *
 435      * @return array
 436      */
 437     public function getAliasMap()
 438     {
 439         return $this->aliasMap;
 440     }
 441
 442     /**
 443      * Gets the number of different entities that appear in the mapped result.
 444      *
 445      * @return integer
 446      */
 447     public function getEntityResultCount()
 448     {
 449         return count($this->aliasMap);
 450     }
 451
 452     /**
 453      * Checks whether this ResultSetMapping defines a mixed result.
 454      * Mixed results can only occur in object and array (graph) hydration. In such a
 455      * case a mixed result means that scalar values are mixed with objects/array in
 456      * the result.
 457      *
 458      * @return boolean
 459      */
 460     public function isMixedResult()
 461     {
 462         return $this->isMixed;
 463     }
 464
 465     /**
 466      * Adds a meta column (foreign key or discriminator column) to the result set.
 467      *
 468      * @param string $alias
 469      * @param string $columnName
 470      * @param string $fieldName
 471      * @param bool
 472      * @return ResultSetMapping This ResultSetMapping instance.
 473      */
 474     public function addMetaResult($alias, $columnName, $fieldName, $isIdentifierColumn = false)
 475     {
 476         $this->metaMappings[$columnName] = $fieldName;
 477         $this->columnOwnerMap[$columnName] = $alias;
 478
 479         if ($isIdentifierColumn) {
 480             $this->isIdentifierColumn[$alias][$columnName] = true;
 481         }
 482
 483         return $this;
 484     }
 485 }