IQueryBuilder.php 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Joas Schilling <coding@schilljs.com>
  6. * @author Lukas Reschke <lukas@statuscode.ch>
  7. * @author Robin Appelman <robin@icewind.nl>
  8. *
  9. * @license AGPL-3.0
  10. *
  11. * This code is free software: you can redistribute it and/or modify
  12. * it under the terms of the GNU Affero General Public License, version 3,
  13. * as published by the Free Software Foundation.
  14. *
  15. * This program is distributed in the hope that it will be useful,
  16. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18. * GNU Affero General Public License for more details.
  19. *
  20. * You should have received a copy of the GNU Affero General Public License, version 3,
  21. * along with this program. If not, see <http://www.gnu.org/licenses/>
  22. *
  23. */
  24. namespace OCP\DB\QueryBuilder;
  25. use Doctrine\DBAL\Connection;
  26. /**
  27. * This class provides a wrapper around Doctrine's QueryBuilder
  28. * @since 8.2.0
  29. */
  30. interface IQueryBuilder {
  31. /**
  32. * @since 9.0.0
  33. */
  34. const PARAM_NULL = \PDO::PARAM_NULL;
  35. /**
  36. * @since 9.0.0
  37. */
  38. const PARAM_BOOL = \PDO::PARAM_BOOL;
  39. /**
  40. * @since 9.0.0
  41. */
  42. const PARAM_INT = \PDO::PARAM_INT;
  43. /**
  44. * @since 9.0.0
  45. */
  46. const PARAM_STR = \PDO::PARAM_STR;
  47. /**
  48. * @since 9.0.0
  49. */
  50. const PARAM_LOB = \PDO::PARAM_LOB;
  51. /**
  52. * @since 9.0.0
  53. */
  54. const PARAM_DATE = 'datetime';
  55. /**
  56. * @since 9.0.0
  57. */
  58. const PARAM_INT_ARRAY = Connection::PARAM_INT_ARRAY;
  59. /**
  60. * @since 9.0.0
  61. */
  62. const PARAM_STR_ARRAY = Connection::PARAM_STR_ARRAY;
  63. /**
  64. * Enable/disable automatic prefixing of table names with the oc_ prefix
  65. *
  66. * @param bool $enabled If set to true table names will be prefixed with the
  67. * owncloud database prefix automatically.
  68. * @since 8.2.0
  69. */
  70. public function automaticTablePrefix($enabled);
  71. /**
  72. * Gets an ExpressionBuilder used for object-oriented construction of query expressions.
  73. * This producer method is intended for convenient inline usage. Example:
  74. *
  75. * <code>
  76. * $qb = $conn->getQueryBuilder()
  77. * ->select('u')
  78. * ->from('users', 'u')
  79. * ->where($qb->expr()->eq('u.id', 1));
  80. * </code>
  81. *
  82. * For more complex expression construction, consider storing the expression
  83. * builder object in a local variable.
  84. *
  85. * @return \OCP\DB\QueryBuilder\IExpressionBuilder
  86. * @since 8.2.0
  87. */
  88. public function expr();
  89. /**
  90. * Gets an FunctionBuilder used for object-oriented construction of query functions.
  91. * This producer method is intended for convenient inline usage. Example:
  92. *
  93. * <code>
  94. * $qb = $conn->getQueryBuilder()
  95. * ->select('u')
  96. * ->from('users', 'u')
  97. * ->where($qb->fun()->md5('u.id'));
  98. * </code>
  99. *
  100. * For more complex function construction, consider storing the function
  101. * builder object in a local variable.
  102. *
  103. * @return \OCP\DB\QueryBuilder\IFunctionBuilder
  104. * @since 12.0.0
  105. */
  106. public function func();
  107. /**
  108. * Gets the type of the currently built query.
  109. *
  110. * @return integer
  111. * @since 8.2.0
  112. */
  113. public function getType();
  114. /**
  115. * Gets the associated DBAL Connection for this query builder.
  116. *
  117. * @return \OCP\IDBConnection
  118. * @since 8.2.0
  119. */
  120. public function getConnection();
  121. /**
  122. * Gets the state of this query builder instance.
  123. *
  124. * @return integer Either QueryBuilder::STATE_DIRTY or QueryBuilder::STATE_CLEAN.
  125. * @since 8.2.0
  126. */
  127. public function getState();
  128. /**
  129. * Executes this query using the bound parameters and their types.
  130. *
  131. * Uses {@see Connection::executeQuery} for select statements and {@see Connection::executeUpdate}
  132. * for insert, update and delete statements.
  133. *
  134. * @return \Doctrine\DBAL\Driver\Statement|int
  135. * @since 8.2.0
  136. */
  137. public function execute();
  138. /**
  139. * Gets the complete SQL string formed by the current specifications of this QueryBuilder.
  140. *
  141. * <code>
  142. * $qb = $conn->getQueryBuilder()
  143. * ->select('u')
  144. * ->from('User', 'u')
  145. * echo $qb->getSQL(); // SELECT u FROM User u
  146. * </code>
  147. *
  148. * @return string The SQL query string.
  149. * @since 8.2.0
  150. */
  151. public function getSQL();
  152. /**
  153. * Sets a query parameter for the query being constructed.
  154. *
  155. * <code>
  156. * $qb = $conn->getQueryBuilder()
  157. * ->select('u')
  158. * ->from('users', 'u')
  159. * ->where('u.id = :user_id')
  160. * ->setParameter(':user_id', 1);
  161. * </code>
  162. *
  163. * @param string|integer $key The parameter position or name.
  164. * @param mixed $value The parameter value.
  165. * @param string|null|int $type One of the IQueryBuilder::PARAM_* constants.
  166. *
  167. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  168. * @since 8.2.0
  169. */
  170. public function setParameter($key, $value, $type = null);
  171. /**
  172. * Sets a collection of query parameters for the query being constructed.
  173. *
  174. * <code>
  175. * $qb = $conn->getQueryBuilder()
  176. * ->select('u')
  177. * ->from('users', 'u')
  178. * ->where('u.id = :user_id1 OR u.id = :user_id2')
  179. * ->setParameters(array(
  180. * ':user_id1' => 1,
  181. * ':user_id2' => 2
  182. * ));
  183. * </code>
  184. *
  185. * @param array $params The query parameters to set.
  186. * @param array $types The query parameters types to set.
  187. *
  188. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  189. * @since 8.2.0
  190. */
  191. public function setParameters(array $params, array $types = array());
  192. /**
  193. * Gets all defined query parameters for the query being constructed indexed by parameter index or name.
  194. *
  195. * @return array The currently defined query parameters indexed by parameter index or name.
  196. * @since 8.2.0
  197. */
  198. public function getParameters();
  199. /**
  200. * Gets a (previously set) query parameter of the query being constructed.
  201. *
  202. * @param mixed $key The key (index or name) of the bound parameter.
  203. *
  204. * @return mixed The value of the bound parameter.
  205. * @since 8.2.0
  206. */
  207. public function getParameter($key);
  208. /**
  209. * Gets all defined query parameter types for the query being constructed indexed by parameter index or name.
  210. *
  211. * @return array The currently defined query parameter types indexed by parameter index or name.
  212. * @since 8.2.0
  213. */
  214. public function getParameterTypes();
  215. /**
  216. * Gets a (previously set) query parameter type of the query being constructed.
  217. *
  218. * @param mixed $key The key (index or name) of the bound parameter type.
  219. *
  220. * @return mixed The value of the bound parameter type.
  221. * @since 8.2.0
  222. */
  223. public function getParameterType($key);
  224. /**
  225. * Sets the position of the first result to retrieve (the "offset").
  226. *
  227. * @param integer $firstResult The first result to return.
  228. *
  229. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  230. * @since 8.2.0
  231. */
  232. public function setFirstResult($firstResult);
  233. /**
  234. * Gets the position of the first result the query object was set to retrieve (the "offset").
  235. * Returns NULL if {@link setFirstResult} was not applied to this QueryBuilder.
  236. *
  237. * @return integer The position of the first result.
  238. * @since 8.2.0
  239. */
  240. public function getFirstResult();
  241. /**
  242. * Sets the maximum number of results to retrieve (the "limit").
  243. *
  244. * @param integer $maxResults The maximum number of results to retrieve.
  245. *
  246. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  247. * @since 8.2.0
  248. */
  249. public function setMaxResults($maxResults);
  250. /**
  251. * Gets the maximum number of results the query object was set to retrieve (the "limit").
  252. * Returns NULL if {@link setMaxResults} was not applied to this query builder.
  253. *
  254. * @return integer The maximum number of results.
  255. * @since 8.2.0
  256. */
  257. public function getMaxResults();
  258. /**
  259. * Specifies an item that is to be returned in the query result.
  260. * Replaces any previously specified selections, if any.
  261. *
  262. * <code>
  263. * $qb = $conn->getQueryBuilder()
  264. * ->select('u.id', 'p.id')
  265. * ->from('users', 'u')
  266. * ->leftJoin('u', 'phonenumbers', 'p', 'u.id = p.user_id');
  267. * </code>
  268. *
  269. * @param mixed ...$selects The selection expressions.
  270. *
  271. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  272. * @since 8.2.0
  273. */
  274. public function select(...$selects);
  275. /**
  276. * Specifies an item that is to be returned with a different name in the query result.
  277. *
  278. * <code>
  279. * $qb = $conn->getQueryBuilder()
  280. * ->selectAlias('u.id', 'user_id')
  281. * ->from('users', 'u')
  282. * ->leftJoin('u', 'phonenumbers', 'p', 'u.id = p.user_id');
  283. * </code>
  284. *
  285. * @param mixed $select The selection expressions.
  286. * @param string $alias The column alias used in the constructed query.
  287. *
  288. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  289. * @since 8.2.1
  290. */
  291. public function selectAlias($select, $alias);
  292. /**
  293. * Specifies an item that is to be returned uniquely in the query result.
  294. *
  295. * <code>
  296. * $qb = $conn->getQueryBuilder()
  297. * ->selectDistinct('type')
  298. * ->from('users');
  299. * </code>
  300. *
  301. * @param mixed $select The selection expressions.
  302. *
  303. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  304. * @since 9.0.0
  305. */
  306. public function selectDistinct($select);
  307. /**
  308. * Adds an item that is to be returned in the query result.
  309. *
  310. * <code>
  311. * $qb = $conn->getQueryBuilder()
  312. * ->select('u.id')
  313. * ->addSelect('p.id')
  314. * ->from('users', 'u')
  315. * ->leftJoin('u', 'phonenumbers', 'u.id = p.user_id');
  316. * </code>
  317. *
  318. * @param mixed ...$select The selection expression.
  319. *
  320. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  321. * @since 8.2.0
  322. */
  323. public function addSelect(...$select);
  324. /**
  325. * Turns the query being built into a bulk delete query that ranges over
  326. * a certain table.
  327. *
  328. * <code>
  329. * $qb = $conn->getQueryBuilder()
  330. * ->delete('users', 'u')
  331. * ->where('u.id = :user_id');
  332. * ->setParameter(':user_id', 1);
  333. * </code>
  334. *
  335. * @param string $delete The table whose rows are subject to the deletion.
  336. * @param string $alias The table alias used in the constructed query.
  337. *
  338. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  339. * @since 8.2.0
  340. */
  341. public function delete($delete = null, $alias = null);
  342. /**
  343. * Turns the query being built into a bulk update query that ranges over
  344. * a certain table
  345. *
  346. * <code>
  347. * $qb = $conn->getQueryBuilder()
  348. * ->update('users', 'u')
  349. * ->set('u.password', md5('password'))
  350. * ->where('u.id = ?');
  351. * </code>
  352. *
  353. * @param string $update The table whose rows are subject to the update.
  354. * @param string $alias The table alias used in the constructed query.
  355. *
  356. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  357. * @since 8.2.0
  358. */
  359. public function update($update = null, $alias = null);
  360. /**
  361. * Turns the query being built into an insert query that inserts into
  362. * a certain table
  363. *
  364. * <code>
  365. * $qb = $conn->getQueryBuilder()
  366. * ->insert('users')
  367. * ->values(
  368. * array(
  369. * 'name' => '?',
  370. * 'password' => '?'
  371. * )
  372. * );
  373. * </code>
  374. *
  375. * @param string $insert The table into which the rows should be inserted.
  376. *
  377. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  378. * @since 8.2.0
  379. */
  380. public function insert($insert = null);
  381. /**
  382. * Creates and adds a query root corresponding to the table identified by the
  383. * given alias, forming a cartesian product with any existing query roots.
  384. *
  385. * <code>
  386. * $qb = $conn->getQueryBuilder()
  387. * ->select('u.id')
  388. * ->from('users', 'u')
  389. * </code>
  390. *
  391. * @param string $from The table.
  392. * @param string|null $alias The alias of the table.
  393. *
  394. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  395. * @since 8.2.0
  396. */
  397. public function from($from, $alias = null);
  398. /**
  399. * Creates and adds a join to the query.
  400. *
  401. * <code>
  402. * $qb = $conn->getQueryBuilder()
  403. * ->select('u.name')
  404. * ->from('users', 'u')
  405. * ->join('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  406. * </code>
  407. *
  408. * @param string $fromAlias The alias that points to a from clause.
  409. * @param string $join The table name to join.
  410. * @param string $alias The alias of the join table.
  411. * @param string $condition The condition for the join.
  412. *
  413. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  414. * @since 8.2.0
  415. */
  416. public function join($fromAlias, $join, $alias, $condition = null);
  417. /**
  418. * Creates and adds a join to the query.
  419. *
  420. * <code>
  421. * $qb = $conn->getQueryBuilder()
  422. * ->select('u.name')
  423. * ->from('users', 'u')
  424. * ->innerJoin('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  425. * </code>
  426. *
  427. * @param string $fromAlias The alias that points to a from clause.
  428. * @param string $join The table name to join.
  429. * @param string $alias The alias of the join table.
  430. * @param string $condition The condition for the join.
  431. *
  432. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  433. * @since 8.2.0
  434. */
  435. public function innerJoin($fromAlias, $join, $alias, $condition = null);
  436. /**
  437. * Creates and adds a left join to the query.
  438. *
  439. * <code>
  440. * $qb = $conn->getQueryBuilder()
  441. * ->select('u.name')
  442. * ->from('users', 'u')
  443. * ->leftJoin('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  444. * </code>
  445. *
  446. * @param string $fromAlias The alias that points to a from clause.
  447. * @param string $join The table name to join.
  448. * @param string $alias The alias of the join table.
  449. * @param string $condition The condition for the join.
  450. *
  451. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  452. * @since 8.2.0
  453. */
  454. public function leftJoin($fromAlias, $join, $alias, $condition = null);
  455. /**
  456. * Creates and adds a right join to the query.
  457. *
  458. * <code>
  459. * $qb = $conn->getQueryBuilder()
  460. * ->select('u.name')
  461. * ->from('users', 'u')
  462. * ->rightJoin('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  463. * </code>
  464. *
  465. * @param string $fromAlias The alias that points to a from clause.
  466. * @param string $join The table name to join.
  467. * @param string $alias The alias of the join table.
  468. * @param string $condition The condition for the join.
  469. *
  470. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  471. * @since 8.2.0
  472. */
  473. public function rightJoin($fromAlias, $join, $alias, $condition = null);
  474. /**
  475. * Sets a new value for a column in a bulk update query.
  476. *
  477. * <code>
  478. * $qb = $conn->getQueryBuilder()
  479. * ->update('users', 'u')
  480. * ->set('u.password', md5('password'))
  481. * ->where('u.id = ?');
  482. * </code>
  483. *
  484. * @param string $key The column to set.
  485. * @param string $value The value, expression, placeholder, etc.
  486. *
  487. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  488. * @since 8.2.0
  489. */
  490. public function set($key, $value);
  491. /**
  492. * Specifies one or more restrictions to the query result.
  493. * Replaces any previously specified restrictions, if any.
  494. *
  495. * <code>
  496. * $qb = $conn->getQueryBuilder()
  497. * ->select('u.name')
  498. * ->from('users', 'u')
  499. * ->where('u.id = ?');
  500. *
  501. * // You can optionally programatically build and/or expressions
  502. * $qb = $conn->getQueryBuilder();
  503. *
  504. * $or = $qb->expr()->orx();
  505. * $or->add($qb->expr()->eq('u.id', 1));
  506. * $or->add($qb->expr()->eq('u.id', 2));
  507. *
  508. * $qb->update('users', 'u')
  509. * ->set('u.password', md5('password'))
  510. * ->where($or);
  511. * </code>
  512. *
  513. * @param mixed $predicates The restriction predicates.
  514. *
  515. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  516. * @since 8.2.0
  517. */
  518. public function where(...$predicates);
  519. /**
  520. * Adds one or more restrictions to the query results, forming a logical
  521. * conjunction with any previously specified restrictions.
  522. *
  523. * <code>
  524. * $qb = $conn->getQueryBuilder()
  525. * ->select('u')
  526. * ->from('users', 'u')
  527. * ->where('u.username LIKE ?')
  528. * ->andWhere('u.is_active = 1');
  529. * </code>
  530. *
  531. * @param mixed ...$where The query restrictions.
  532. *
  533. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  534. *
  535. * @see where()
  536. * @since 8.2.0
  537. */
  538. public function andWhere(...$where);
  539. /**
  540. * Adds one or more restrictions to the query results, forming a logical
  541. * disjunction with any previously specified restrictions.
  542. *
  543. * <code>
  544. * $qb = $conn->getQueryBuilder()
  545. * ->select('u.name')
  546. * ->from('users', 'u')
  547. * ->where('u.id = 1')
  548. * ->orWhere('u.id = 2');
  549. * </code>
  550. *
  551. * @param mixed ...$where The WHERE statement.
  552. *
  553. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  554. *
  555. * @see where()
  556. * @since 8.2.0
  557. */
  558. public function orWhere(...$where);
  559. /**
  560. * Specifies a grouping over the results of the query.
  561. * Replaces any previously specified groupings, if any.
  562. *
  563. * <code>
  564. * $qb = $conn->getQueryBuilder()
  565. * ->select('u.name')
  566. * ->from('users', 'u')
  567. * ->groupBy('u.id');
  568. * </code>
  569. *
  570. * @param mixed ...$groupBys The grouping expression.
  571. *
  572. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  573. * @since 8.2.0
  574. */
  575. public function groupBy(...$groupBys);
  576. /**
  577. * Adds a grouping expression to the query.
  578. *
  579. * <code>
  580. * $qb = $conn->getQueryBuilder()
  581. * ->select('u.name')
  582. * ->from('users', 'u')
  583. * ->groupBy('u.lastLogin');
  584. * ->addGroupBy('u.createdAt')
  585. * </code>
  586. *
  587. * @param mixed ...$groupBy The grouping expression.
  588. *
  589. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  590. * @since 8.2.0
  591. */
  592. public function addGroupBy(...$groupBy);
  593. /**
  594. * Sets a value for a column in an insert query.
  595. *
  596. * <code>
  597. * $qb = $conn->getQueryBuilder()
  598. * ->insert('users')
  599. * ->values(
  600. * array(
  601. * 'name' => '?'
  602. * )
  603. * )
  604. * ->setValue('password', '?');
  605. * </code>
  606. *
  607. * @param string $column The column into which the value should be inserted.
  608. * @param string $value The value that should be inserted into the column.
  609. *
  610. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  611. * @since 8.2.0
  612. */
  613. public function setValue($column, $value);
  614. /**
  615. * Specifies values for an insert query indexed by column names.
  616. * Replaces any previous values, if any.
  617. *
  618. * <code>
  619. * $qb = $conn->getQueryBuilder()
  620. * ->insert('users')
  621. * ->values(
  622. * array(
  623. * 'name' => '?',
  624. * 'password' => '?'
  625. * )
  626. * );
  627. * </code>
  628. *
  629. * @param array $values The values to specify for the insert query indexed by column names.
  630. *
  631. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  632. * @since 8.2.0
  633. */
  634. public function values(array $values);
  635. /**
  636. * Specifies a restriction over the groups of the query.
  637. * Replaces any previous having restrictions, if any.
  638. *
  639. * @param mixed ...$having The restriction over the groups.
  640. *
  641. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  642. * @since 8.2.0
  643. */
  644. public function having(...$having);
  645. /**
  646. * Adds a restriction over the groups of the query, forming a logical
  647. * conjunction with any existing having restrictions.
  648. *
  649. * @param mixed ...$having The restriction to append.
  650. *
  651. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  652. * @since 8.2.0
  653. */
  654. public function andHaving(...$having);
  655. /**
  656. * Adds a restriction over the groups of the query, forming a logical
  657. * disjunction with any existing having restrictions.
  658. *
  659. * @param mixed ...$having The restriction to add.
  660. *
  661. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  662. * @since 8.2.0
  663. */
  664. public function orHaving(...$having);
  665. /**
  666. * Specifies an ordering for the query results.
  667. * Replaces any previously specified orderings, if any.
  668. *
  669. * @param string $sort The ordering expression.
  670. * @param string $order The ordering direction.
  671. *
  672. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  673. * @since 8.2.0
  674. */
  675. public function orderBy($sort, $order = null);
  676. /**
  677. * Adds an ordering to the query results.
  678. *
  679. * @param string $sort The ordering expression.
  680. * @param string $order The ordering direction.
  681. *
  682. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  683. * @since 8.2.0
  684. */
  685. public function addOrderBy($sort, $order = null);
  686. /**
  687. * Gets a query part by its name.
  688. *
  689. * @param string $queryPartName
  690. *
  691. * @return mixed
  692. * @since 8.2.0
  693. */
  694. public function getQueryPart($queryPartName);
  695. /**
  696. * Gets all query parts.
  697. *
  698. * @return array
  699. * @since 8.2.0
  700. */
  701. public function getQueryParts();
  702. /**
  703. * Resets SQL parts.
  704. *
  705. * @param array|null $queryPartNames
  706. *
  707. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  708. * @since 8.2.0
  709. */
  710. public function resetQueryParts($queryPartNames = null);
  711. /**
  712. * Resets a single SQL part.
  713. *
  714. * @param string $queryPartName
  715. *
  716. * @return \OCP\DB\QueryBuilder\IQueryBuilder This QueryBuilder instance.
  717. * @since 8.2.0
  718. */
  719. public function resetQueryPart($queryPartName);
  720. /**
  721. * Creates a new named parameter and bind the value $value to it.
  722. *
  723. * This method provides a shortcut for PDOStatement::bindValue
  724. * when using prepared statements.
  725. *
  726. * The parameter $value specifies the value that you want to bind. If
  727. * $placeholder is not provided bindValue() will automatically create a
  728. * placeholder for you. An automatic placeholder will be of the name
  729. * ':dcValue1', ':dcValue2' etc.
  730. *
  731. * For more information see {@link http://php.net/pdostatement-bindparam}
  732. *
  733. * Example:
  734. * <code>
  735. * $value = 2;
  736. * $q->eq( 'id', $q->bindValue( $value ) );
  737. * $stmt = $q->executeQuery(); // executed with 'id = 2'
  738. * </code>
  739. *
  740. * @license New BSD License
  741. * @link http://www.zetacomponents.org
  742. *
  743. * @param mixed $value
  744. * @param mixed $type
  745. * @param string $placeHolder The name to bind with. The string must start with a colon ':'.
  746. *
  747. * @return IParameter
  748. * @since 8.2.0
  749. */
  750. public function createNamedParameter($value, $type = self::PARAM_STR, $placeHolder = null);
  751. /**
  752. * Creates a new positional parameter and bind the given value to it.
  753. *
  754. * Attention: If you are using positional parameters with the query builder you have
  755. * to be very careful to bind all parameters in the order they appear in the SQL
  756. * statement , otherwise they get bound in the wrong order which can lead to serious
  757. * bugs in your code.
  758. *
  759. * Example:
  760. * <code>
  761. * $qb = $conn->getQueryBuilder();
  762. * $qb->select('u.*')
  763. * ->from('users', 'u')
  764. * ->where('u.username = ' . $qb->createPositionalParameter('Foo', IQueryBuilder::PARAM_STR))
  765. * ->orWhere('u.username = ' . $qb->createPositionalParameter('Bar', IQueryBuilder::PARAM_STR))
  766. * </code>
  767. *
  768. * @param mixed $value
  769. * @param integer $type
  770. *
  771. * @return IParameter
  772. * @since 8.2.0
  773. */
  774. public function createPositionalParameter($value, $type = self::PARAM_STR);
  775. /**
  776. * Creates a new parameter
  777. *
  778. * Example:
  779. * <code>
  780. * $qb = $conn->getQueryBuilder();
  781. * $qb->select('u.*')
  782. * ->from('users', 'u')
  783. * ->where('u.username = ' . $qb->createParameter('name'))
  784. * ->setParameter('name', 'Bar', IQueryBuilder::PARAM_STR))
  785. * </code>
  786. *
  787. * @param string $name
  788. *
  789. * @return IParameter
  790. * @since 8.2.0
  791. */
  792. public function createParameter($name);
  793. /**
  794. * Creates a new function
  795. *
  796. * Attention: Column names inside the call have to be quoted before hand
  797. *
  798. * Example:
  799. * <code>
  800. * $qb = $conn->getQueryBuilder();
  801. * $qb->select($qb->createFunction('COUNT(*)'))
  802. * ->from('users', 'u')
  803. * echo $qb->getSQL(); // SELECT COUNT(*) FROM `users` u
  804. * </code>
  805. * <code>
  806. * $qb = $conn->getQueryBuilder();
  807. * $qb->select($qb->createFunction('COUNT(`column`)'))
  808. * ->from('users', 'u')
  809. * echo $qb->getSQL(); // SELECT COUNT(`column`) FROM `users` u
  810. * </code>
  811. *
  812. * @param string $call
  813. *
  814. * @return IQueryFunction
  815. * @since 8.2.0
  816. */
  817. public function createFunction($call);
  818. /**
  819. * Used to get the id of the last inserted element
  820. * @return int
  821. * @throws \BadMethodCallException When being called before an insert query has been run.
  822. * @since 9.0.0
  823. */
  824. public function getLastInsertId();
  825. /**
  826. * Returns the table name quoted and with database prefix as needed by the implementation
  827. *
  828. * @param string $table
  829. * @return string
  830. * @since 9.0.0
  831. */
  832. public function getTableName($table);
  833. /**
  834. * Returns the column name quoted and with table alias prefix as needed by the implementation
  835. *
  836. * @param string $column
  837. * @param string $tableAlias
  838. * @return string
  839. * @since 9.0.0
  840. */
  841. public function getColumnName($column, $tableAlias = '');
  842. }