vendor/doctrine/dbal/lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.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\DBAL\Query\Expression;
  21
  22 use Doctrine\DBAL\Connection;
  23
  24 /**
  25  * ExpressionBuilder class is responsible to dynamically create SQL query parts.
  26  *
  27  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  28  * @link        www.doctrine-project.com
  29  * @since       2.1
  30  * @author      Guilherme Blanco <guilhermeblanco@hotmail.com>
  31  * @author      Benjamin Eberlei <kontakt@beberlei.de>
  32  */
  33 class ExpressionBuilder
  34 {
  35     const EQ  = '=';
  36     const NEQ = '<>';
  37     const LT  = '<';
  38     const LTE = '<=';
  39     const GT  = '>';
  40     const GTE = '>=';
  41
  42     /**
  43      * @var Doctrine\DBAL\Connection DBAL Connection
  44      */
  45     private $connection = null;
  46
  47     /**
  48      * Initializes a new <tt>ExpressionBuilder</tt>.
  49      *
  50      * @param \Doctrine\DBAL\Connection $connection DBAL Connection
  51      */
  52     public function __construct(Connection $connection)
  53     {
  54         $this->connection = $connection;
  55     }
  56
  57     /**
  58      * Creates a conjunction of the given boolean expressions.
  59      *
  60      * Example:
  61      *
  62      *     [php]
  63      *     // (u.type = ?) AND (u.role = ?)
  64      *     $expr->andX('u.type = ?', 'u.role = ?'));
  65      *
  66      * @param mixed $x Optional clause. Defaults = null, but requires
  67      *                 at least one defined when converting to string.
  68      * @return CompositeExpression
  69      */
  70     public function andX($x = null)
  71     {
  72         return new CompositeExpression(CompositeExpression::TYPE_AND, func_get_args());
  73     }
  74
  75     /**
  76      * Creates a disjunction of the given boolean expressions.
  77      *
  78      * Example:
  79      *
  80      *     [php]
  81      *     // (u.type = ?) OR (u.role = ?)
  82      *     $qb->where($qb->expr()->orX('u.type = ?', 'u.role = ?'));
  83      *
  84      * @param mixed $x Optional clause. Defaults = null, but requires
  85      *                 at least one defined when converting to string.
  86      * @return CompositeExpression
  87      */
  88     public function orX($x = null)
  89     {
  90         return new CompositeExpression(CompositeExpression::TYPE_OR, func_get_args());
  91     }
  92
  93     /**
  94      * Creates a comparison expression.
  95      *
  96      * @param mixed $x Left expression
  97      * @param string $operator One of the ExpressionBuilder::* constants.
  98      * @param mixed $y Right expression
  99      * @return string
 100      */
 101     public function comparison($x, $operator, $y)
 102     {
 103         return $x . ' ' . $operator . ' ' . $y;
 104     }
 105
 106     /**
 107      * Creates an equality comparison expression with the given arguments.
 108      *
 109      * First argument is considered the left expression and the second is the right expression.
 110      * When converted to string, it will generated a <left expr> = <right expr>. Example:
 111      *
 112      *     [php]
 113      *     // u.id = ?
 114      *     $expr->eq('u.id', '?');
 115      *
 116      * @param mixed $x Left expression
 117      * @param mixed $y Right expression
 118      * @return string
 119      */
 120     public function eq($x, $y)
 121     {
 122         return $this->comparison($x, self::EQ, $y);
 123     }
 124
 125     /**
 126      * Creates a non equality comparison expression with the given arguments.
 127      * First argument is considered the left expression and the second is the right expression.
 128      * When converted to string, it will generated a <left expr> <> <right expr>. Example:
 129      *
 130      *     [php]
 131      *     // u.id <> 1
 132      *     $q->where($q->expr()->neq('u.id', '1'));
 133      *
 134      * @param mixed $x Left expression
 135      * @param mixed $y Right expression
 136      * @return string
 137      */
 138     public function neq($x, $y)
 139     {
 140         return $this->comparison($x, self::NEQ, $y);
 141     }
 142
 143     /**
 144      * Creates a lower-than comparison expression with the given arguments.
 145      * First argument is considered the left expression and the second is the right expression.
 146      * When converted to string, it will generated a <left expr> < <right expr>. Example:
 147      *
 148      *     [php]
 149      *     // u.id < ?
 150      *     $q->where($q->expr()->lt('u.id', '?'));
 151      *
 152      * @param mixed $x Left expression
 153      * @param mixed $y Right expression
 154      * @return string
 155      */
 156     public function lt($x, $y)
 157     {
 158         return $this->comparison($x, self::LT, $y);
 159     }
 160
 161     /**
 162      * Creates a lower-than-equal comparison expression with the given arguments.
 163      * First argument is considered the left expression and the second is the right expression.
 164      * When converted to string, it will generated a <left expr> <= <right expr>. Example:
 165      *
 166      *     [php]
 167      *     // u.id <= ?
 168      *     $q->where($q->expr()->lte('u.id', '?'));
 169      *
 170      * @param mixed $x Left expression
 171      * @param mixed $y Right expression
 172      * @return string
 173      */
 174     public function lte($x, $y)
 175     {
 176         return $this->comparison($x, self::LTE, $y);
 177     }
 178
 179     /**
 180      * Creates a greater-than comparison expression with the given arguments.
 181      * First argument is considered the left expression and the second is the right expression.
 182      * When converted to string, it will generated a <left expr> > <right expr>. Example:
 183      *
 184      *     [php]
 185      *     // u.id > ?
 186      *     $q->where($q->expr()->gt('u.id', '?'));
 187      *
 188      * @param mixed $x Left expression
 189      * @param mixed $y Right expression
 190      * @return string
 191      */
 192     public function gt($x, $y)
 193     {
 194         return $this->comparison($x, self::GT, $y);
 195     }
 196
 197     /**
 198      * Creates a greater-than-equal comparison expression with the given arguments.
 199      * First argument is considered the left expression and the second is the right expression.
 200      * When converted to string, it will generated a <left expr> >= <right expr>. Example:
 201      *
 202      *     [php]
 203      *     // u.id >= ?
 204      *     $q->where($q->expr()->gte('u.id', '?'));
 205      *
 206      * @param mixed $x Left expression
 207      * @param mixed $y Right expression
 208      * @return string
 209      */
 210     public function gte($x, $y)
 211     {
 212         return $this->comparison($x, self::GTE, $y);
 213     }
 214
 215     /**
 216      * Creates an IS NULL expression with the given arguments.
 217      *
 218      * @param string $x Field in string format to be restricted by IS NULL
 219      *
 220      * @return string
 221      */
 222     public function isNull($x)
 223     {
 224         return $x . ' IS NULL';
 225     }
 226
 227     /**
 228      * Creates an IS NOT NULL expression with the given arguments.
 229      *
 230      * @param string $x Field in string format to be restricted by IS NOT NULL
 231      *
 232      * @return string
 233      */
 234     public function isNotNull($x)
 235     {
 236         return $x . ' IS NOT NULL';
 237     }
 238
 239     /**
 240      * Creates a LIKE() comparison expression with the given arguments.
 241      *
 242      * @param string $x Field in string format to be inspected by LIKE() comparison.
 243      * @param mixed $y Argument to be used in LIKE() comparison.
 244      *
 245      * @return string
 246      */
 247     public function like($x, $y)
 248     {
 249         return $this->comparison($x, 'LIKE', $y);
 250     }
 251
 252     /**
 253      * Quotes a given input parameter.
 254      *
 255      * @param mixed $input Parameter to be quoted.
 256      * @param string $type Type of the parameter.
 257      *
 258      * @return string
 259      */
 260     public function literal($input, $type = null)
 261     {
 262         return $this->connection->quote($input, $type);
 263     }
 264 }