ExpressionBuilder.php 9.3 KB

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