vendor/phpcr/phpcr-utils/src/PHPCR/Util/QOM/QueryBuilder.php line 535

  1. <?php
  3. namespace PHPCR\Util\QOM;
  5. use InvalidArgumentException;
  6. use PHPCR\Query\QOM\ColumnInterface;
  7. use PHPCR\Query\QOM\ConstraintInterface;
  8. use PHPCR\Query\QOM\DynamicOperandInterface;
  9. use PHPCR\Query\QOM\JoinConditionInterface;
  10. use PHPCR\Query\QOM\OrderingInterface;
  11. use PHPCR\Query\QOM\QueryObjectModelConstantsInterface;
  12. use PHPCR\Query\QOM\QueryObjectModelFactoryInterface;
  13. use PHPCR\Query\QOM\QueryObjectModelInterface;
  14. use PHPCR\Query\QOM\SourceInterface;
  15. use PHPCR\Query\QueryInterface;
  16. use PHPCR\Query\QueryResultInterface;
  17. use RuntimeException;
  19. /**
  20.  * QueryBuilder class is responsible for dynamically create QOM queries.
  21.  *
  22.  * @license http://www.apache.org/licenses Apache License Version 2.0, January 2004
  23.  * @license http://opensource.org/licenses/MIT MIT License
  24.  * @author      Nacho Martín <nitram.ohcan@gmail.com>
  25.  * @author      Guilherme Blanco <guilhermeblanco@hotmail.com>
  26.  * @author      Benjamin Eberlei <kontakt@beberlei.de>
  27.  */
  28. class QueryBuilder
  29. {
  30.     /** The builder states. */
  31.     const STATE_DIRTY = 0;
  32.     const STATE_CLEAN = 1;
  34.     /**
  35.      * @var int The state of the query object. Can be dirty or clean.
  36.      */
  37.     private $state = self::STATE_CLEAN;
  39.     /**
  40.      * @var QueryObjectModelFactoryInterface QOMFactory
  41.      */
  42.     private $qomFactory;
  44.     /**
  45.      * @var int The maximum number of results to retrieve.
  46.      */
  47.     private $firstResult = null;
  49.     /**
  50.      * @var int The maximum number of results to retrieve.
  51.      */
  52.     private $maxResults = null;
  54.     /**
  55.      * @var array with the orderings that determine the order of the result
  56.      */
  57.     private $orderings = [];
  59.     /**
  60.      * @var ConstraintInterface to apply to the query.
  61.      */
  62.     private $constraint = null;
  64.     /**
  65.      * @var array with the columns to be selected.
  66.      */
  67.     private $columns = [];
  69.     /**
  70.      * @var SourceInterface source of the query.
  71.      */
  72.     private $source = null;
  74.     /**
  75.      * QOM tree.
  76.      *
  77.      * @var QueryObjectModelInterface
  78.      */
  79.     private $query = null;
  81.     /**
  82.      * @var array The query parameters.
  83.      */
  84.     private $params = [];
  86.     /**
  87.      * Initializes a new QueryBuilder.
  88.      *
  89.      * @param QueryObjectModelFactoryInterface $qomFactory
  90.      */
  91.     public function __construct(QueryObjectModelFactoryInterface $qomFactory)
  92.     {
  93.         $this->qomFactory = $qomFactory;
  94.     }
  96.     /**
  97.      * Get a query builder instance from an existing query.
  98.      *
  99.      * @param string $statement the statement in the specified language
  100.      * @param string $language  the query language
  101.      *
  102.      * @throws InvalidArgumentException
  103.      *
  104.      * @return QueryBuilder This QueryBuilder instance.
  105.      */
  106.     public function setFromQuery($statement, $language)
  107.     {
  108.         if (QueryInterface::JCR_SQL2 === $language) {
  109.             $converter = new Sql2ToQomQueryConverter($this->qomFactory);
  110.             $statement = $converter->parse($statement);
  111.         }
  113.         if (!$statement instanceof QueryObjectModelInterface) {
  114.             throw new InvalidArgumentException("Language '$language' not supported");
  115.         }
  117.         $this->state = self::STATE_DIRTY;
  118.         $this->source = $statement->getSource();
  119.         $this->constraint = $statement->getConstraint();
  120.         $this->orderings = $statement->getOrderings();
  121.         $this->columns = $statement->getColumns();
  123.         return $this;
  124.     }
  126.     /**
  127.      * Get the associated QOMFactory for this query builder.
  128.      *
  129.      * @return QueryObjectModelFactoryInterface
  130.      */
  131.     public function getQOMFactory()
  132.     {
  133.         return $this->qomFactory;
  134.     }
  136.     /**
  137.      * Shortcut for getQOMFactory().
  138.      */
  139.     public function qomf()
  140.     {
  141.         return $this->getQOMFactory();
  142.     }
  144.     /**
  145.      * sets the position of the first result to retrieve (the "offset").
  146.      *
  147.      * @param int $firstResult The First result to return.
  148.      *
  149.      * @return QueryBuilder This QueryBuilder instance.
  150.      */
  151.     public function setFirstResult($firstResult)
  152.     {
  153.         $this->firstResult = $firstResult;
  155.         return $this;
  156.     }
  158.     /**
  159.      * Gets the position of the first result the query object was set to retrieve (the "offset").
  160.      * Returns NULL if {@link setFirstResult} was not applied to this QueryBuilder.
  161.      *
  162.      * @return int The position of the first result.
  163.      */
  164.     public function getFirstResult()
  165.     {
  166.         return $this->firstResult;
  167.     }
  169.     /**
  170.      * Sets the maximum number of results to retrieve (the "limit").
  171.      *
  172.      * @param int $maxResults The maximum number of results to retrieve.
  173.      *
  174.      * @return QueryBuilder This QueryBuilder instance.
  175.      */
  176.     public function setMaxResults($maxResults)
  177.     {
  178.         $this->maxResults = $maxResults;
  180.         return $this;
  181.     }
  183.     /**
  184.      * Gets the maximum number of results the query object was set to retrieve (the "limit").
  185.      * Returns NULL if {@link setMaxResults} was not applied to this query builder.
  186.      *
  187.      * @return int Maximum number of results.
  188.      */
  189.     public function getMaxResults()
  190.     {
  191.         return $this->maxResults;
  192.     }
  194.     /**
  195.      * Gets the array of orderings.
  196.      *
  197.      * @return OrderingInterface[] Orderings to apply.
  198.      */
  199.     public function getOrderings()
  200.     {
  201.         return $this->orderings;
  202.     }
  204.     /**
  205.      * Adds an ordering to the query results.
  206.      *
  207.      * @param DynamicOperandInterface $sort  The ordering expression.
  208.      * @param string                  $order The ordering direction.
  209.      *
  210.      * @throws InvalidArgumentException
  211.      *
  212.      * @return QueryBuilder This QueryBuilder instance.
  213.      */
  214.     public function addOrderBy(DynamicOperandInterface $sort, $order = 'ASC')
  215.     {
  216.         $order = strtoupper($order);
  218.         if (!in_array($order, ['ASC', 'DESC'])) {
  219.             throw new InvalidArgumentException('Order must be one of "ASC" or "DESC"');
  220.         }
  222.         $this->state = self::STATE_DIRTY;
  223.         if ($order === 'DESC') {
  224.             $ordering = $this->qomFactory->descending($sort);
  225.         } else {
  226.             $ordering = $this->qomFactory->ascending($sort);
  227.         }
  228.         $this->orderings[] = $ordering;
  230.         return $this;
  231.     }
  233.     /**
  234.      * Specifies an ordering for the query results.
  235.      * Replaces any previously specified orderings, if any.
  236.      *
  237.      * @param DynamicOperandInterface $sort  The ordering expression.
  238.      * @param string                  $order The ordering direction.
  239.      *
  240.      * @return QueryBuilder This QueryBuilder instance.
  241.      */
  242.     public function orderBy(DynamicOperandInterface $sort, $order = 'ASC')
  243.     {
  244.         $this->orderings = [];
  245.         $this->addOrderBy($sort, $order);
  247.         return $this;
  248.     }
  250.     /**
  251.      * Specifies one restriction (may be simple or composed).
  252.      * Replaces any previously specified restrictions, if any.
  253.      *
  254.      * @param ConstraintInterface $constraint
  255.      *
  256.      * @return QueryBuilder This QueryBuilder instance.
  257.      */
  258.     public function where(ConstraintInterface $constraint)
  259.     {
  260.         $this->state = self::STATE_DIRTY;
  261.         $this->constraint = $constraint;
  263.         return $this;
  264.     }
  266.     /**
  267.      * Returns the constraint to apply.
  268.      *
  269.      * @return ConstraintInterface the constraint to be applied
  270.      */
  271.     public function getConstraint()
  272.     {
  273.         return $this->constraint;
  274.     }
  276.     /**
  277.      * Creates a new constraint formed by applying a logical AND to the
  278.      * existing constraint and the new one.
  279.      *
  280.      * Order of ands is important:
  281.      *
  282.      * Given $this->constraint = $constraint1
  283.      * running andWhere($constraint2)
  284.      * resulting constraint will be $constraint1 AND $constraint2
  285.      *
  286.      * If there is no previous constraint then it will simply store the
  287.      * provided one
  288.      *
  289.      * @param ConstraintInterface $constraint
  290.      *
  291.      * @return QueryBuilder This QueryBuilder instance.
  292.      */
  293.     public function andWhere(ConstraintInterface $constraint)
  294.     {
  295.         $this->state = self::STATE_DIRTY;
  297.         if ($this->constraint) {
  298.             $this->constraint = $this->qomFactory->andConstraint($this->constraint, $constraint);
  299.         } else {
  300.             $this->constraint = $constraint;
  301.         }
  303.         return $this;
  304.     }
  306.     /**
  307.      * Creates a new constraint formed by applying a logical OR to the
  308.      * existing constraint and the new one.
  309.      *
  310.      * Order of ands is important:
  311.      *
  312.      * Given $this->constraint = $constraint1
  313.      * running orWhere($constraint2)
  314.      * resulting constraint will be $constraint1 OR $constraint2
  315.      *
  316.      * If there is no previous constraint then it will simply store the
  317.      * provided one
  318.      *
  319.      * @param ConstraintInterface $constraint
  320.      *
  321.      * @return QueryBuilder This QueryBuilder instance.
  322.      */
  323.     public function orWhere(ConstraintInterface $constraint)
  324.     {
  325.         $this->state = self::STATE_DIRTY;
  327.         if ($this->constraint) {
  328.             $this->constraint = $this->qomFactory->orConstraint($this->constraint, $constraint);
  329.         } else {
  330.             $this->constraint = $constraint;
  331.         }
  333.         return $this;
  334.     }
  336.     /**
  337.      * Returns the columns to be selected.
  338.      *
  339.      * @return ColumnInterface[] The columns to be selected
  340.      */
  341.     public function getColumns()
  342.     {
  343.         return $this->columns;
  344.     }
  346.     /**
  347.      * Sets the columns to be selected.
  348.      *
  349.      * @param ColumnInterface[] $columns The columns to be selected
  350.      *
  351.      * @return QueryBuilder This QueryBuilder instance.
  352.      */
  353.     public function setColumns(array $columns)
  354.     {
  355.         $this->columns = $columns;
  357.         return $this;
  358.     }
  360.     /**
  361.      * Identifies a property in the specified or default selector to include in the tabular view of query results.
  362.      * Replaces any previously specified columns to be selected if any.
  363.      *
  364.      * @param string $selectorName
  365.      * @param string $propertyName
  366.      * @param string $columnName
  367.      *
  368.      * @return QueryBuilder This QueryBuilder instance.
  369.      */
  370.     public function select($selectorName, $propertyName, $columnName = null)
  371.     {
  372.         $this->state = self::STATE_DIRTY;
  373.         $this->columns = [$this->qomFactory->column($selectorName, $propertyName, $columnName)];
  375.         return $this;
  376.     }
  378.     /**
  379.      * Adds a property in the specified or default selector to include in the tabular view of query results.
  380.      *
  381.      * @param string $selectorName
  382.      * @param string $propertyName
  383.      * @param string $columnName
  384.      *
  385.      * @return QueryBuilder This QueryBuilder instance.
  386.      */
  387.     public function addSelect($selectorName, $propertyName, $columnName = null)
  388.     {
  389.         $this->state = self::STATE_DIRTY;
  391.         $this->columns[] = $this->qomFactory->column($selectorName, $propertyName, $columnName);
  393.         return $this;
  394.     }
  396.     /**
  397.      * Sets the default Selector or the node-tuple Source. Can be a selector
  398.      * or a join.
  399.      *
  400.      * @param SourceInterface $source
  401.      *
  402.      * @return QueryBuilder This QueryBuilder instance.
  403.      */
  404.     public function from(SourceInterface $source)
  405.     {
  406.         $this->state = self::STATE_DIRTY;
  407.         $this->source = $source;
  409.         return $this;
  410.     }
  412.     /**
  413.      * Gets the default Selector.
  414.      *
  415.      * @return SourceInterface The default selector.
  416.      */
  417.     public function getSource()
  418.     {
  419.         return $this->source;
  420.     }
  422.     /**
  423.      * Performs an inner join between the stored source and the supplied source.
  424.      *
  425.      * @param SourceInterface        $rightSource
  426.      * @param JoinConditionInterface $joinCondition
  427.      *
  428.      * @throws RuntimeException if there is not an existing source.
  429.      *
  430.      * @return QueryBuilder This QueryBuilder instance.
  431.      */
  432.     public function join(SourceInterface $rightSource, JoinConditionInterface $joinCondition)
  433.     {
  434.         return $this->innerJoin($rightSource, $joinCondition);
  435.     }
  437.     /**
  438.      * Performs an inner join between the stored source and the supplied source.
  439.      *
  440.      * @param SourceInterface        $rightSource
  441.      * @param JoinConditionInterface $joinCondition
  442.      *
  443.      * @throws RuntimeException if there is not an existing source.
  444.      *
  445.      * @return QueryBuilder This QueryBuilder instance.
  446.      */
  447.     public function innerJoin(SourceInterface $rightSource, JoinConditionInterface $joinCondition)
  448.     {
  449.         return $this->joinWithType($rightSource, QueryObjectModelConstantsInterface::JCR_JOIN_TYPE_INNER, $joinCondition);
  450.     }
  452.     /**
  453.      * Performs an left outer join between the stored source and the supplied source.
  454.      *
  455.      * @param SourceInterface        $rightSource
  456.      * @param JoinConditionInterface $joinCondition
  457.      *
  458.      * @throws RuntimeException if there is not an existing source.
  459.      *
  460.      * @return QueryBuilder This QueryBuilder instance.
  461.      */
  462.     public function leftJoin(SourceInterface $rightSource, JoinConditionInterface $joinCondition)
  463.     {
  464.         return $this->joinWithType($rightSource, QueryObjectModelConstantsInterface::JCR_JOIN_TYPE_LEFT_OUTER, $joinCondition);
  465.     }
  467.     /**
  468.      * Performs a right outer join between the stored source and the supplied source.
  469.      *
  470.      * @param SourceInterface        $rightSource
  471.      * @param JoinConditionInterface $joinCondition
  472.      *
  473.      * @throws RuntimeException if there is not an existing source.
  474.      *
  475.      * @return QueryBuilder This QueryBuilder instance.
  476.      */
  477.     public function rightJoin(SourceInterface $rightSource, JoinConditionInterface $joinCondition)
  478.     {
  479.         return $this->joinWithType($rightSource, QueryObjectModelConstantsInterface::JCR_JOIN_TYPE_RIGHT_OUTER, $joinCondition);
  480.     }
  482.     /**
  483.      * Performs an join between the stored source and the supplied source.
  484.      *
  485.      * @param SourceInterface        $rightSource
  486.      * @param string                 $joinType      as specified in PHPCR\Query\QOM\QueryObjectModelConstantsInterface
  487.      * @param JoinConditionInterface $joinCondition
  488.      *
  489.      * @throws RuntimeException if there is not an existing source.
  490.      *
  491.      * @return QueryBuilder This QueryBuilder instance.
  492.      */
  493.     public function joinWithType(SourceInterface $rightSource, $joinType, JoinConditionInterface $joinCondition)
  494.     {
  495.         if (!$this->source) {
  496.             throw new RuntimeException('Cannot perform a join without a previous call to from');
  497.         }
  499.         $this->state = self::STATE_DIRTY;
  500.         $this->source = $this->qomFactory->join($this->source, $rightSource, $joinType, $joinCondition);
  502.         return $this;
  503.     }
  505.     /**
  506.      * Gets the query built.
  507.      *
  508.      * @return QueryObjectModelInterface
  509.      */
  510.     public function getQuery()
  511.     {
  512.         if ($this->query !== null && $this->state === self::STATE_CLEAN) {
  513.             return $this->query;
  514.         }
  516.         $this->state = self::STATE_CLEAN;
  517.         $this->query = $this->qomFactory->createQuery($this->source, $this->constraint, $this->orderings, $this->columns);
  519.         if ($this->firstResult) {
  520.             $this->query->setOffset($this->firstResult);
  521.         }
  523.         if ($this->maxResults) {
  524.             $this->query->setLimit($this->maxResults);
  525.         }
  527.         return $this->query;
  528.     }
  530.     /**
  531.      * Executes the query setting firstResult and maxResults.
  532.      *
  533.      * @return QueryResultInterface
  534.      */
  535.     public function execute()
  536.     {
  537.         if ($this->query === null || $this->state === self::STATE_DIRTY) {
  538.             $this->query = $this->getQuery();
  539.         }
  541.         foreach ($this->params as $key => $value) {
  542.             $this->query->bindValue($key, $value);
  543.         }
  545.         return $this->query->execute();
  546.     }
  548.     /**
  549.      * Sets a query parameter for the query being constructed.
  550.      *
  551.      * @param string $key   The parameter name.
  552.      * @param mixed  $value The parameter value.
  553.      *
  554.      * @return QueryBuilder This QueryBuilder instance.
  555.      */
  556.     public function setParameter($key, $value)
  557.     {
  558.         $this->params[$key] = $value;
  560.         return $this;
  561.     }
  563.     /**
  564.      * Gets a (previously set) query parameter of the query being constructed.
  565.      *
  566.      * @param string $key The key (name) of the bound parameter.
  567.      *
  568.      * @return mixed The value of the bound parameter.
  569.      */
  570.     public function getParameter($key)
  571.     {
  572.         return isset($this->params[$key]) ? $this->params[$key] : null;
  573.     }
  575.     /**
  576.      * Sets a collection of query parameters for the query being constructed.
  577.      *
  578.      * @param array $params The query parameters to set.
  579.      *
  580.      * @return QueryBuilder This QueryBuilder instance.
  581.      */
  582.     public function setParameters(array $params)
  583.     {
  584.         $this->params = $params;
  586.         return $this;
  587.     }
  589.     /**
  590.      * Gets all defined query parameters for the query being constructed.
  591.      *
  592.      * @return array The currently defined query parameters.
  593.      */
  594.     public function getParameters()
  595.     {
  596.         return $this->params;
  597.     }
  598. }