vendor/doctrine/orm/lib/Doctrine/ORM/Query/Expr.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  * This class is used to generate DQL expressions via a set of PHP static functions
  24  *
  25  *
  26  * @link    www.doctrine-project.org
  27  * @since   2.0
  28  * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
  29  * @author  Jonathan Wage <jonwage@gmail.com>
  30  * @author  Roman Borschel <roman@code-factory.org>
  31  * @author  Benjamin Eberlei <kontakt@beberlei.de>
  32  * @todo Rename: ExpressionBuilder
  33  */
  34 class Expr
  35 {
  36     /**
  37      * Creates a conjunction of the given boolean expressions.
  38      *
  39      * Example:
  40      *
  41      *     [php]
  42      *     // (u.type = ?1) AND (u.role = ?2)
  43      *     $expr->andX($expr->eq('u.type', ':1'), $expr->eq('u.role', ':2'));
  44      *
  45      * @param \Doctrine\ORM\Query\Expr\Comparison |
  46      *          \Doctrine\ORM\Query\Expr\Func |
  47      *          \Doctrine\ORM\Query\Expr\Orx
  48     *               $x Optional clause. Defaults = null, but requires at least one defined when converting to string.
  49      * @return Expr\Andx
  50      */
  51     public function andX($x = null)
  52     {
  53         return new Expr\Andx(func_get_args());
  54     }
  55
  56     /**
  57      * Creates a disjunction of the given boolean expressions.
  58      *
  59      * Example:
  60      *
  61      *     [php]
  62      *     // (u.type = ?1) OR (u.role = ?2)
  63      *     $q->where($q->expr()->orX('u.type = ?1', 'u.role = ?2'));
  64      *
  65      * @param mixed $x Optional clause. Defaults = null, but requires
  66      *                 at least one defined when converting to string.
  67      * @return Expr\Orx
  68      */
  69     public function orX($x = null)
  70     {
  71         return new Expr\Orx(func_get_args());
  72     }
  73
  74     /**
  75      * Creates an ASCending order expression.
  76      *
  77      * @param $sort
  78      * @return Expr\OrderBy
  79      */
  80     public function asc($expr)
  81     {
  82         return new Expr\OrderBy($expr, 'ASC');
  83     }
  84
  85     /**
  86      * Creates a DESCending order expression.
  87      *
  88      * @param $sort
  89      * @return Expr\OrderBy
  90      */
  91     public function desc($expr)
  92     {
  93         return new Expr\OrderBy($expr, 'DESC');
  94     }
  95
  96     /**
  97      * Creates an equality comparison expression with the given arguments.
  98      *
  99      * First argument is considered the left expression and the second is the right expression.
 100      * When converted to string, it will generated a <left expr> = <right expr>. Example:
 101      *
 102      *     [php]
 103      *     // u.id = ?1
 104      *     $expr->eq('u.id', '?1');
 105      *
 106      * @param mixed $x Left expression
 107      * @param mixed $y Right expression
 108      * @return Expr\Comparison
 109      */
 110     public function eq($x, $y)
 111     {
 112         return new Expr\Comparison($x, Expr\Comparison::EQ, $y);
 113     }
 114
 115     /**
 116      * Creates an instance of Expr\Comparison, with the given arguments.
 117      * First argument is considered the left expression and the second is the right expression.
 118      * When converted to string, it will generated a <left expr> <> <right expr>. Example:
 119      *
 120      *     [php]
 121      *     // u.id <> ?1
 122      *     $q->where($q->expr()->neq('u.id', '?1'));
 123      *
 124      * @param mixed $x Left expression
 125      * @param mixed $y Right expression
 126      * @return Expr\Comparison
 127      */
 128     public function neq($x, $y)
 129     {
 130         return new Expr\Comparison($x, Expr\Comparison::NEQ, $y);
 131     }
 132
 133     /**
 134      * Creates an instance of Expr\Comparison, with the given arguments.
 135      * First argument is considered the left expression and the second is the right expression.
 136      * When converted to string, it will generated a <left expr> < <right expr>. Example:
 137      *
 138      *     [php]
 139      *     // u.id < ?1
 140      *     $q->where($q->expr()->lt('u.id', '?1'));
 141      *
 142      * @param mixed $x Left expression
 143      * @param mixed $y Right expression
 144      * @return Expr\Comparison
 145      */
 146     public function lt($x, $y)
 147     {
 148         return new Expr\Comparison($x, Expr\Comparison::LT, $y);
 149     }
 150
 151     /**
 152      * Creates an instance of Expr\Comparison, with the given arguments.
 153      * First argument is considered the left expression and the second is the right expression.
 154      * When converted to string, it will generated a <left expr> <= <right expr>. Example:
 155      *
 156      *     [php]
 157      *     // u.id <= ?1
 158      *     $q->where($q->expr()->lte('u.id', '?1'));
 159      *
 160      * @param mixed $x Left expression
 161      * @param mixed $y Right expression
 162      * @return Expr\Comparison
 163      */
 164     public function lte($x, $y)
 165     {
 166         return new Expr\Comparison($x, Expr\Comparison::LTE, $y);
 167     }
 168
 169     /**
 170      * Creates an instance of Expr\Comparison, with the given arguments.
 171      * First argument is considered the left expression and the second is the right expression.
 172      * When converted to string, it will generated a <left expr> > <right expr>. Example:
 173      *
 174      *     [php]
 175      *     // u.id > ?1
 176      *     $q->where($q->expr()->gt('u.id', '?1'));
 177      *
 178      * @param mixed $x Left expression
 179      * @param mixed $y Right expression
 180      * @return Expr\Comparison
 181      */
 182     public function gt($x, $y)
 183     {
 184         return new Expr\Comparison($x, Expr\Comparison::GT, $y);
 185     }
 186
 187     /**
 188      * Creates an instance of Expr\Comparison, with the given arguments.
 189      * First argument is considered the left expression and the second is the right expression.
 190      * When converted to string, it will generated a <left expr> >= <right expr>. Example:
 191      *
 192      *     [php]
 193      *     // u.id >= ?1
 194      *     $q->where($q->expr()->gte('u.id', '?1'));
 195      *
 196      * @param mixed $x Left expression
 197      * @param mixed $y Right expression
 198      * @return Expr\Comparison
 199      */
 200     public function gte($x, $y)
 201     {
 202         return new Expr\Comparison($x, Expr\Comparison::GTE, $y);
 203     }
 204
 205     /**
 206      * Creates an instance of AVG() function, with the given argument.
 207      *
 208      * @param mixed $x Argument to be used in AVG() function.
 209      * @return Expr\Func
 210      */
 211     public function avg($x)
 212     {
 213         return new Expr\Func('AVG', array($x));
 214     }
 215
 216     /**
 217      * Creates an instance of MAX() function, with the given argument.
 218      *
 219      * @param mixed $x Argument to be used in MAX() function.
 220      * @return Expr\Func
 221      */
 222     public function max($x)
 223     {
 224         return new Expr\Func('MAX', array($x));
 225     }
 226
 227     /**
 228      * Creates an instance of MIN() function, with the given argument.
 229      *
 230      * @param mixed $x Argument to be used in MIN() function.
 231      * @return Expr\Func
 232      */
 233     public function min($x)
 234     {
 235         return new Expr\Func('MIN', array($x));
 236     }
 237
 238     /**
 239      * Creates an instance of COUNT() function, with the given argument.
 240      *
 241      * @param mixed $x Argument to be used in COUNT() function.
 242      * @return Expr\Func
 243      */
 244     public function count($x)
 245     {
 246         return new Expr\Func('COUNT', array($x));
 247     }
 248
 249     /**
 250      * Creates an instance of COUNT(DISTINCT) function, with the given argument.
 251      *
 252      * @param mixed $x Argument to be used in COUNT(DISTINCT) function.
 253      * @return string
 254      */
 255     public function countDistinct($x)
 256     {
 257         return 'COUNT(DISTINCT ' . implode(', ', func_get_args()) . ')';
 258     }
 259
 260     /**
 261      * Creates an instance of EXISTS() function, with the given DQL Subquery.
 262      *
 263      * @param mixed $subquery DQL Subquery to be used in EXISTS() function.
 264      * @return Expr\Func
 265      */
 266     public function exists($subquery)
 267     {
 268         return new Expr\Func('EXISTS', array($subquery));
 269     }
 270
 271     /**
 272      * Creates an instance of ALL() function, with the given DQL Subquery.
 273      *
 274      * @param mixed $subquery DQL Subquery to be used in ALL() function.
 275      * @return Expr\Func
 276      */
 277     public function all($subquery)
 278     {
 279         return new Expr\Func('ALL', array($subquery));
 280     }
 281
 282     /**
 283      * Creates a SOME() function expression with the given DQL subquery.
 284      *
 285      * @param mixed $subquery DQL Subquery to be used in SOME() function.
 286      * @return Expr\Func
 287      */
 288     public function some($subquery)
 289     {
 290         return new Expr\Func('SOME', array($subquery));
 291     }
 292
 293     /**
 294      * Creates an ANY() function expression with the given DQL subquery.
 295      *
 296      * @param mixed $subquery DQL Subquery to be used in ANY() function.
 297      * @return Expr\Func
 298      */
 299     public function any($subquery)
 300     {
 301         return new Expr\Func('ANY', array($subquery));
 302     }
 303
 304     /**
 305      * Creates a negation expression of the given restriction.
 306      *
 307      * @param mixed $restriction Restriction to be used in NOT() function.
 308      * @return Expr\Func
 309      */
 310     public function not($restriction)
 311     {
 312         return new Expr\Func('NOT', array($restriction));
 313     }
 314
 315     /**
 316      * Creates an ABS() function expression with the given argument.
 317      *
 318      * @param mixed $x Argument to be used in ABS() function.
 319      * @return Expr\Func
 320      */
 321     public function abs($x)
 322     {
 323         return new Expr\Func('ABS', array($x));
 324     }
 325
 326     /**
 327      * Creates a product mathematical expression with the given arguments.
 328      *
 329      * First argument is considered the left expression and the second is the right expression.
 330      * When converted to string, it will generated a <left expr> * <right expr>. Example:
 331      *
 332      *     [php]
 333      *     // u.salary * u.percentAnualSalaryIncrease
 334      *     $q->expr()->prod('u.salary', 'u.percentAnualSalaryIncrease')
 335      *
 336      * @param mixed $x Left expression
 337      * @param mixed $y Right expression
 338      * @return Expr\Math
 339      */
 340     public function prod($x, $y)
 341     {
 342         return new Expr\Math($x, '*', $y);
 343     }
 344
 345     /**
 346      * Creates a difference mathematical expression with the given arguments.
 347      * First argument is considered the left expression and the second is the right expression.
 348      * When converted to string, it will generated a <left expr> - <right expr>. Example:
 349      *
 350      *     [php]
 351      *     // u.monthlySubscriptionCount - 1
 352      *     $q->expr()->diff('u.monthlySubscriptionCount', '1')
 353      *
 354      * @param mixed $x Left expression
 355      * @param mixed $y Right expression
 356      * @return Expr\Math
 357      */
 358     public function diff($x, $y)
 359     {
 360         return new Expr\Math($x, '-', $y);
 361     }
 362
 363     /**
 364      * Creates a sum mathematical expression with the given arguments.
 365      * First argument is considered the left expression and the second is the right expression.
 366      * When converted to string, it will generated a <left expr> + <right expr>. Example:
 367      *
 368      *     [php]
 369      *     // u.numChildren + 1
 370      *     $q->expr()->diff('u.numChildren', '1')
 371      *
 372      * @param mixed $x Left expression
 373      * @param mixed $y Right expression
 374      * @return Expr\Math
 375      */
 376     public function sum($x, $y)
 377     {
 378         return new Expr\Math($x, '+', $y);
 379     }
 380
 381     /**
 382      * Creates a quotient mathematical expression with the given arguments.
 383      * First argument is considered the left expression and the second is the right expression.
 384      * When converted to string, it will generated a <left expr> / <right expr>. Example:
 385      *
 386      *     [php]
 387      *     // u.total / u.period
 388      *     $expr->quot('u.total', 'u.period')
 389      *
 390      * @param mixed $x Left expression
 391      * @param mixed $y Right expression
 392      * @return Expr\Math
 393      */
 394     public function quot($x, $y)
 395     {
 396         return new Expr\Math($x, '/', $y);
 397     }
 398
 399     /**
 400      * Creates a SQRT() function expression with the given argument.
 401      *
 402      * @param mixed $x Argument to be used in SQRT() function.
 403      * @return Expr\Func
 404      */
 405     public function sqrt($x)
 406     {
 407         return new Expr\Func('SQRT', array($x));
 408     }
 409
 410     /**
 411      * Creates an IN() expression with the given arguments.
 412      *
 413      * @param string $x Field in string format to be restricted by IN() function
 414      * @param mixed $y Argument to be used in IN() function.
 415      * @return Expr\Func
 416      */
 417     public function in($x, $y)
 418     {
 419         if (is_array($y)) {
 420             foreach ($y as &$literal) {
 421                 if ( ! ($literal instanceof Expr\Literal)) {
 422                     $literal = $this->_quoteLiteral($literal);
 423                 }
 424             }
 425         }
 426         return new Expr\Func($x . ' IN', (array) $y);
 427     }
 428
 429     /**
 430      * Creates a NOT IN() expression with the given arguments.
 431      *
 432      * @param string $x Field in string format to be restricted by NOT IN() function
 433      * @param mixed $y Argument to be used in NOT IN() function.
 434      * @return Expr\Func
 435      */
 436     public function notIn($x, $y)
 437     {
 438         if (is_array($y)) {
 439             foreach ($y as &$literal) {
 440                 if ( ! ($literal instanceof Expr\Literal)) {
 441                     $literal = $this->_quoteLiteral($literal);
 442                 }
 443             }
 444         }
 445         return new Expr\Func($x . ' NOT IN', (array) $y);
 446     }
 447
 448     /**
 449      * Creates an IS NULL expression with the given arguments.
 450      *
 451      * @param string $x Field in string format to be restricted by IS NULL
 452      * @return string
 453      */
 454     public function isNull($x)
 455     {
 456         return $x . ' IS NULL';
 457     }
 458
 459     /**
 460      * Creates an IS NOT NULL expression with the given arguments.
 461      *
 462      * @param string $x Field in string format to be restricted by IS NOT NULL
 463      * @return string
 464      */
 465     public function isNotNull($x)
 466     {
 467         return $x . ' IS NOT NULL';
 468     }
 469
 470     /**
 471      * Creates a LIKE() comparison expression with the given arguments.
 472      *
 473      * @param string $x Field in string format to be inspected by LIKE() comparison.
 474      * @param mixed $y Argument to be used in LIKE() comparison.
 475      * @return Expr\Comparison
 476      */
 477     public function like($x, $y)
 478     {
 479         return new Expr\Comparison($x, 'LIKE', $y);
 480     }
 481
 482     /**
 483      * Creates a CONCAT() function expression with the given arguments.
 484      *
 485      * @param mixed $x First argument to be used in CONCAT() function.
 486      * @param mixed $x Second argument to be used in CONCAT() function.
 487      * @return Expr\Func
 488      */
 489     public function concat($x, $y)
 490     {
 491         return new Expr\Func('CONCAT', array($x, $y));
 492     }
 493
 494     /**
 495      * Creates a SUBSTRING() function expression with the given arguments.
 496      *
 497      * @param mixed $x Argument to be used as string to be cropped by SUBSTRING() function.
 498      * @param integer $from Initial offset to start cropping string. May accept negative values.
 499      * @param integer $len Length of crop. May accept negative values.
 500      * @return Expr\Func
 501      */
 502     public function substring($x, $from, $len = null)
 503     {
 504         $args = array($x, $from);
 505         if (null !== $len) {
 506             $args[] = $len;
 507         }
 508         return new Expr\Func('SUBSTRING', $args);
 509     }
 510
 511     /**
 512      * Creates a LOWER() function expression with the given argument.
 513      *
 514      * @param mixed $x Argument to be used in LOWER() function.
 515      * @return Expr\Func A LOWER function expression.
 516      */
 517     public function lower($x)
 518     {
 519         return new Expr\Func('LOWER', array($x));
 520     }
 521
 522     /**
 523      * Creates an UPPER() function expression with the given argument.
 524      *
 525      * @param mixed $x Argument to be used in UPPER() function.
 526      * @return Expr\Func An UPPER function expression.
 527      */
 528     public function upper($x)
 529     {
 530         return new Expr\Func('UPPER', array($x));
 531     }
 532
 533     /**
 534      * Creates a LENGTH() function expression with the given argument.
 535      *
 536      * @param mixed $x Argument to be used as argument of LENGTH() function.
 537      * @return Expr\Func A LENGTH function expression.
 538      */
 539     public function length($x)
 540     {
 541         return new Expr\Func('LENGTH', array($x));
 542     }
 543
 544     /**
 545      * Creates a literal expression of the given argument.
 546      *
 547      * @param mixed $literal Argument to be converted to literal.
 548      * @return Expr\Literal
 549      */
 550     public function literal($literal)
 551     {
 552         return new Expr\Literal($this->_quoteLiteral($literal));
 553     }
 554
 555     /**
 556      * Quotes a literal value, if necessary, according to the DQL syntax.
 557      *
 558      * @param mixed $literal The literal value.
 559      * @return string
 560      */
 561     private function _quoteLiteral($literal)
 562     {
 563         if (is_numeric($literal) && !is_string($literal)) {
 564             return (string) $literal;
 565         } else if (is_bool($literal)) {
 566             return $literal ? "true" : "false";
 567         } else {
 568             return "'" . str_replace("'", "''", $literal) . "'";
 569         }
 570     }
 571
 572     /**
 573      * Creates an instance of BETWEEN() function, with the given argument.
 574      *
 575      * @param mixed $val Valued to be inspected by range values.
 576      * @param integer $x Starting range value to be used in BETWEEN() function.
 577      * @param integer $y End point value to be used in BETWEEN() function.
 578      * @return Expr\Func A BETWEEN expression.
 579      */
 580     public function between($val, $x, $y)
 581     {
 582         return $val . ' BETWEEN ' . $x . ' AND ' . $y;
 583     }
 584
 585     /**
 586      * Creates an instance of TRIM() function, with the given argument.
 587      *
 588      * @param mixed $x Argument to be used as argument of TRIM() function.
 589      * @return Expr\Func a TRIM expression.
 590      */
 591     public function trim($x)
 592     {
 593         return new Expr\Func('TRIM', $x);
 594     }
 595 }