Expr.php 18KB

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