/vendor/propel/runtime/lib/query/Join.php
PHP | 566 lines | 489 code | 13 blank | 64 comment | 10 complexity | ce52d1fdb4557e51e528c7d70a4c8b7e MD5 | raw file
Possible License(s): BSD-3-Clause, BSD-2-Clause
- <?php
- /**
- * This file is part of the Propel package.
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- *
- * @license MIT License
- */
- /**
- * Data object to describe a join between two tables, for example
- * <pre>
- * table_a LEFT JOIN table_b ON table_a.id = table_b.a_id
- * </pre>
- *
- * @author Francois Zaninotto (Propel)
- * @author Hans Lellelid <hans@xmpl.org> (Propel)
- * @author Kaspars Jaudzems <kaspars.jaudzems@inbox.lv> (Propel)
- * @author Frank Y. Kim <frank.kim@clearink.com> (Torque)
- * @author John D. McNally <jmcnally@collab.net> (Torque)
- * @author Brett McLaughlin <bmclaugh@algx.net> (Torque)
- * @author Eric Dobbs <eric@dobbse.net> (Torque)
- * @author Henning P. Schmiedehausen <hps@intermeta.de> (Torque)
- * @author Sam Joseph <sam@neurogrid.com> (Torque)
- * @package propel.runtime.query
- */
- class Join
- {
- // default comparison type
- const EQUAL = "=";
- const INNER_JOIN = 'INNER JOIN';
- // the left parts of the join condition
- protected $left = array();
- // the right parts of the join condition
- protected $right = array();
- // the comparison operators for each pair of columns in the join condition
- protected $operator = array();
- // the type of the join (LEFT JOIN, ...)
- protected $joinType;
- // the number of conditions in the join
- protected $count = 0;
- // the database adapter
- protected $db;
- protected $leftTableName;
- protected $rightTableName;
- protected $leftTableAlias;
- protected $rightTableAlias;
- protected $joinCondition;
- /**
- * Constructor
- * Use it preferably with no arguments, and then use addCondition() and setJoinType()
- * Syntax with arguments used mainly for backwards compatibility
- *
- * @param string $leftColumn The left column of the join condition
- * (may contain an alias name)
- * @param string $rightColumn The right column of the join condition
- * (may contain an alias name)
- * @param string $joinType The type of the join. Valid join types are null (implicit join),
- * Criteria::LEFT_JOIN, Criteria::RIGHT_JOIN, and Criteria::INNER_JOIN
- */
- public function __construct($leftColumn = null, $rightColumn = null, $joinType = null)
- {
- if (null !== $leftColumn) {
- if (is_array($leftColumn)) {
- // join with multiple conditions
- $this->addConditions($leftColumn, $rightColumn);
- } else {
- // simple join
- $this->addCondition($leftColumn, $rightColumn);
- }
- }
- if (null !== $joinType) {
- $this->setJoinType($joinType);
- }
- }
- /**
- * Join condition definition.
- * Warning: doesn't support table aliases. Use the explicit methods to use aliases.
- *
- * @param string $left The left column of the join condition
- * (may contain an alias name)
- * @param string $right The right column of the join condition
- * (may contain an alias name)
- * @param string $operator The comparison operator of the join condition, default Join::EQUAL
- */
- public function addCondition($left, $right, $operator = self::EQUAL)
- {
- if ($pos = strrpos($left, '.')) {
- list($this->leftTableName, $this->left[]) = explode('.', $left);
- } else {
- $this->left[] = $left;
- }
- if ($pos = strrpos($right, '.')) {
- list($this->rightTableName, $this->right[]) = explode('.', $right);
- } else {
- $this->right[] = $right;
- }
- $this->operator[] = $operator;
- $this->count++;
- }
- /**
- * Join condition definition, for several conditions
- *
- * @param array $lefts The left columns of the join condition
- * @param array $rights The right columns of the join condition
- * @param array $operators The comparison operators of the join condition, default Join::EQUAL
- *
- * @throws PropelException
- */
- public function addConditions($lefts, $rights, $operators = array())
- {
- if (count($lefts) != count($rights) ) {
- throw new PropelException("Unable to create join because the left column count isn't equal to the right column count");
- }
- foreach ($lefts as $key => $left) {
- $this->addCondition($left, $rights[$key], isset($operators[$key]) ? $operators[$key] : self::EQUAL);
- }
- }
- /**
- * Join condition definition.
- * @example
- * <code>
- * $join = new Join();
- * $join->setJoinType(Criteria::LEFT_JOIN);
- * $join->addExplicitCondition('book', 'AUTHOR_ID', null, 'author', 'ID', 'a', Join::EQUAL);
- * echo $join->getClause();
- * // LEFT JOIN author a ON (book.AUTHOR_ID=a.ID)
- * </code>
- *
- * @param string $leftTableName
- * @param string $leftColumnName
- * @param string $leftTableAlias
- * @param string $rightTableName
- * @param string $rightColumnName
- * @param string $rightTableAlias
- * @param string $operator The comparison operator of the join condition, default Join::EQUAL
- */
- public function addExplicitCondition($leftTableName, $leftColumnName, $leftTableAlias = null, $rightTableName, $rightColumnName, $rightTableAlias = null, $operator = self::EQUAL)
- {
- $this->leftTableName = $leftTableName;
- $this->leftTableAlias = $leftTableAlias;
- $this->rightTableName = $rightTableName;
- $this->rightTableAlias = $rightTableAlias;
- $this->left []= $leftColumnName;
- $this->right []= $rightColumnName;
- $this->operator []= $operator;
- $this->count++;
- }
- /**
- * Retrieve the number of conditions in the join
- *
- * @return integer The number of conditions in the join
- */
- public function countConditions()
- {
- return $this->count;
- }
- /**
- * Return an array of the join conditions
- *
- * @return array An array of arrays representing (left, comparison, right) for each condition
- */
- public function getConditions()
- {
- $conditions = array();
- for ($i=0; $i < $this->count; $i++) {
- $conditions[] = array(
- 'left' => $this->getLeftColumn($i),
- 'operator' => $this->getOperator($i),
- 'right' => $this->getRightColumn($i)
- );
- }
- return $conditions;
- }
- /**
- * @param string $operator the comparison operator for the join condition
- */
- public function addOperator($operator = null)
- {
- $this->operator []= $operator;
- }
- /**
- * @return the comparison operator for the join condition
- */
- public function getOperator($index = 0)
- {
- return $this->operator[$index];
- }
- public function getOperators()
- {
- return $this->operator;
- }
- /**
- * Set the join type
- *
- * @param string $joinType The type of the join. Valid join types are
- * null (adding the join condition to the where clause),
- * Criteria::LEFT_JOIN(), Criteria::RIGHT_JOIN(), and Criteria::INNER_JOIN()
- */
- public function setJoinType($joinType = null)
- {
- $this->joinType = $joinType;
- }
- /**
- * Get the join type
- *
- * @return string The type of the join, i.e. Criteria::LEFT_JOIN(), ...,
- * or null for adding the join condition to the where Clause
- */
- public function getJoinType()
- {
- return null === $this->joinType ? self::INNER_JOIN : $this->joinType;
- }
- /**
- * Add a left column name to the join condition
- *
- * @example
- * <code>
- * $join->setLeftTableName('book');
- * $join->addLeftColumnName('AUTHOR_ID');
- * </code>
- * @param string $left The name of the left column to add
- */
- public function addLeftColumnName($left)
- {
- $this->left []= $left;
- }
- /**
- * Get the fully qualified name of the left column of the join condition
- *
- * @example
- * <code>
- * $join->addCondition('book.AUTHOR_ID', 'author.ID');
- * echo $join->getLeftColumn(); // 'book.AUTHOR_ID'
- * </code>
- * @param integer $index The number of the condition to use
- * @return string
- */
- public function getLeftColumn($index = 0)
- {
- $tableName = $this->getLeftTableAliasOrName();
- return $tableName ? $tableName . '.' . $this->left[$index] : $this->left[$index];
- }
- /**
- * Get the left column name of the join condition
- *
- * @example
- * <code>
- * $join->addCondition('book.AUTHOR_ID', 'author.ID');
- * echo $join->getLeftColumnName(); // 'AUTHOR_ID'
- * </code>
- * @param integer $index The number of the condition to use
- * @return string
- */
- public function getLeftColumnName($index = 0)
- {
- return $this->left[$index];
- }
- /**
- * Get the list of all the names of left columns of the join condition
- * @return array
- */
- public function getLeftColumns()
- {
- $columns = array();
- foreach ($this->left as $index => $column) {
- $columns []= $this->getLeftColumn($index);
- }
- return $columns;
- }
- public function setLeftTableName($leftTableName)
- {
- $this->leftTableName = $leftTableName;
- return $this;
- }
- public function getLeftTableName()
- {
- return $this->leftTableName;
- }
- public function setLeftTableAlias($leftTableAlias)
- {
- $this->leftTableAlias = $leftTableAlias;
- return $this;
- }
- public function getLeftTableAlias()
- {
- return $this->leftTableAlias;
- }
- public function hasLeftTableAlias()
- {
- return null !== $this->leftTableAlias;
- }
- public function getLeftTableAliasOrName()
- {
- return $this->leftTableAlias ? $this->leftTableAlias : $this->leftTableName;
- }
- public function getLeftTableWithAlias()
- {
- return $this->leftTableAlias ? $this->leftTableName . ' ' . $this->leftTableAlias : $this->leftTableName;
- }
- /**
- * Add a right column name to the join condition
- *
- * @example
- * <code>
- * $join->setRightTableName('author');
- * $join->addRightColumnName('ID');
- * </code>
- * @param string $right The name of the right column to add
- */
- public function addRightColumnName($right)
- {
- $this->right []= $right;
- }
- /**
- * Get the fully qualified name of the right column of the join condition
- *
- * @example
- * <code>
- * $join->addCondition('book.AUTHOR_ID', 'author.ID');
- * echo $join->getLeftColumn(); // 'author.ID'
- * </code>
- * @param integer $index The number of the condition to use
- * @return string
- */
- public function getRightColumn($index = 0)
- {
- $tableName = $this->getRightTableAliasOrName();
- return $tableName ? $tableName . '.' . $this->right[$index] : $this->right[$index];
- }
- /**
- * Get the right column name of the join condition
- *
- * @example
- * <code>
- * $join->addCondition('book.AUTHOR_ID', 'author.ID');
- * echo $join->getLeftColumn(); // 'ID'
- * </code>
- * @param integer $index The number of the condition to use
- * @return string
- */
- public function getRightColumnName($index = 0)
- {
- return $this->right[$index];
- }
- /**
- * @return all right columns of the join condition
- */
- public function getRightColumns()
- {
- $columns = array();
- foreach ($this->right as $index => $column) {
- $columns []= $this->getRightColumn($index);
- }
- return $columns;
- }
- public function setRightTableName($rightTableName)
- {
- $this->rightTableName = $rightTableName;
- return $this;
- }
- public function getRightTableName()
- {
- return $this->rightTableName;
- }
- public function setRightTableAlias($rightTableAlias)
- {
- $this->rightTableAlias = $rightTableAlias;
- return $this;
- }
- public function getRightTableAlias()
- {
- return $this->rightTableAlias;
- }
- public function hasRightTableAlias()
- {
- return null !== $this->rightTableAlias;
- }
- public function getRightTableAliasOrName()
- {
- return $this->rightTableAlias ? $this->rightTableAlias : $this->rightTableName;
- }
- public function getRightTableWithAlias()
- {
- return $this->rightTableAlias ? $this->rightTableName . ' ' . $this->rightTableAlias : $this->rightTableName;
- }
- /**
- * Get the value of db.
- * The DBAdapter which might be used to get db specific
- * variations of sql.
- * @return DBAdapter value of db.
- */
- public function getDB()
- {
- return $this->db;
- }
- /**
- * Set the value of db.
- * The DBAdapter might be used to get db specific variations of sql.
- * @param DBAdapter $db Value to assign to db.
- * @return void
- */
- public function setDB(DBAdapter $db)
- {
- $this->db = $db;
- }
- /**
- * Set a custom join condition
- *
- * @param Criterion $joinCondition a Join condition
- */
- public function setJoinCondition(Criterion $joinCondition)
- {
- $this->joinCondition = $joinCondition;
- }
- /**
- * Get the custom join condition, if previously set
- *
- * @return Criterion
- */
- public function getJoinCondition()
- {
- return $this->joinCondition;
- }
- /**
- * Set the custom join condition Criterion based on the conditions of this join
- *
- * @param Criteria $c A Criteria object to get Criterions from
- */
- public function buildJoinCondition(Criteria $c)
- {
- $joinCondition = null;
- for ($i=0; $i < $this->count; $i++) {
- $criterion = $c->getNewCriterion($this->getLeftColumn($i), $this->getLeftColumn($i) . $this->getOperator($i) . $this->getRightColumn($i), Criteria::CUSTOM);
- if (null === $joinCondition) {
- $joinCondition = $criterion;
- } else {
- $joinCondition = $joinCondition->addAnd($criterion);
- }
- }
- $this->joinCondition = $joinCondition;
- }
- /**
- * Get the join clause for this Join.
- * If the join condition needs binding, uses the passed params array.
- * @example
- * <code>
- * $join = new Join();
- * $join->addExplicitCondition('book', 'AUTHOR_ID', null, 'author', 'ID');
- * $params = array();
- * echo $j->getClause($params);
- * // 'LEFT JOIN author ON (book.AUTHOR_ID=author.ID)'
- * </code>
- *
- * @param array &$params
- *
- * @return string SQL join clause with join condition
- */
- public function getClause(&$params)
- {
- if (null === $this->joinCondition) {
- $conditions = array();
- for ($i=0; $i < $this->count; $i++) {
- $conditions []= $this->getLeftColumn($i) . $this->getOperator($i) . $this->getRightColumn($i);
- }
- $joinCondition = sprintf('(%s)', implode($conditions, ' AND '));
- } else {
- $joinCondition = '';
- $this->getJoinCondition()->appendPsTo($joinCondition, $params);
- }
- $rightTableName = $this->getRightTableWithAlias();
- if (null !== $this->db && $this->db->useQuoteIdentifier()) {
- $rightTableName = $this->db->quoteIdentifierTable($rightTableName);
- }
- return sprintf('%s %s ON %s',
- $this->getJoinType(),
- $rightTableName,
- $joinCondition
- );
- }
- public function equals($join)
- {
- return $join !== null
- && $join instanceof Join
- && $this->joinType == $join->getJoinType()
- && $this->getConditions() == $join->getConditions();
- }
- /**
- * Returns a String representation of the class,
- *
- * @return string A String representation of the class
- */
- public function toString()
- {
- $params = array();
- return $this->getClause($params);
- }
- public function __toString()
- {
- return $this->toString();
- }
- }