ResultSetMapping.php 16 KB

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