select.inc 49 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616
  1. <?php
  2. /**
  3. * @addtogroup database
  4. * @{
  5. */
  6. require_once dirname(__FILE__) . '/query.inc';
  7. /**
  8. * Interface for extendable query objects.
  9. *
  10. * "Extenders" follow the "Decorator" OOP design pattern. That is, they wrap
  11. * and "decorate" another object. In our case, they implement the same interface
  12. * as select queries and wrap a select query, to which they delegate almost all
  13. * operations. Subclasses of this class may implement additional methods or
  14. * override existing methods as appropriate. Extenders may also wrap other
  15. * extender objects, allowing for arbitrarily complex "enhanced" queries.
  16. */
  17. interface QueryExtendableInterface {
  18. /**
  19. * Enhance this object by wrapping it in an extender object.
  20. *
  21. * @param $extender_name
  22. * The base name of the extending class. The base name will be checked
  23. * against the current database connection to allow driver-specific subclasses
  24. * as well, using the same logic as the query objects themselves. For example,
  25. * PagerDefault_mysql is the MySQL-specific override for PagerDefault.
  26. * @return QueryExtendableInterface
  27. * The extender object, which now contains a reference to this object.
  28. */
  29. public function extend($extender_name);
  30. }
  31. /**
  32. * Interface definition for a Select Query object.
  33. */
  34. interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableInterface, QueryExtendableInterface, QueryPlaceholderInterface {
  35. /* Alter accessors to expose the query data to alter hooks. */
  36. /**
  37. * Returns a reference to the fields array for this query.
  38. *
  39. * Because this method returns by reference, alter hooks may edit the fields
  40. * array directly to make their changes. If just adding fields, however, the
  41. * use of addField() is preferred.
  42. *
  43. * Note that this method must be called by reference as well:
  44. *
  45. * @code
  46. * $fields =& $query->getFields();
  47. * @endcode
  48. *
  49. * @return
  50. * A reference to the fields array structure.
  51. */
  52. public function &getFields();
  53. /**
  54. * Returns a reference to the expressions array for this query.
  55. *
  56. * Because this method returns by reference, alter hooks may edit the expressions
  57. * array directly to make their changes. If just adding expressions, however, the
  58. * use of addExpression() is preferred.
  59. *
  60. * Note that this method must be called by reference as well:
  61. *
  62. * @code
  63. * $fields =& $query->getExpressions();
  64. * @endcode
  65. *
  66. * @return
  67. * A reference to the expression array structure.
  68. */
  69. public function &getExpressions();
  70. /**
  71. * Returns a reference to the order by array for this query.
  72. *
  73. * Because this method returns by reference, alter hooks may edit the order-by
  74. * array directly to make their changes. If just adding additional ordering
  75. * fields, however, the use of orderBy() is preferred.
  76. *
  77. * Note that this method must be called by reference as well:
  78. *
  79. * @code
  80. * $fields =& $query->getOrderBy();
  81. * @endcode
  82. *
  83. * @return
  84. * A reference to the expression array structure.
  85. */
  86. public function &getOrderBy();
  87. /**
  88. * Returns a reference to the group-by array for this query.
  89. *
  90. * Because this method returns by reference, alter hooks may edit the group-by
  91. * array directly to make their changes. If just adding additional grouping
  92. * fields, however, the use of groupBy() is preferred.
  93. *
  94. * Note that this method must be called by reference as well:
  95. *
  96. * @code
  97. * $fields =& $query->getGroupBy();
  98. * @endcode
  99. *
  100. * @return
  101. * A reference to the group-by array structure.
  102. */
  103. public function &getGroupBy();
  104. /**
  105. * Returns a reference to the tables array for this query.
  106. *
  107. * Because this method returns by reference, alter hooks may edit the tables
  108. * array directly to make their changes. If just adding tables, however, the
  109. * use of the join() methods is preferred.
  110. *
  111. * Note that this method must be called by reference as well:
  112. *
  113. * @code
  114. * $fields =& $query->getTables();
  115. * @endcode
  116. *
  117. * @return
  118. * A reference to the tables array structure.
  119. */
  120. public function &getTables();
  121. /**
  122. * Returns a reference to the union queries for this query. This include
  123. * queries for UNION, UNION ALL, and UNION DISTINCT.
  124. *
  125. * Because this method returns by reference, alter hooks may edit the tables
  126. * array directly to make their changes. If just adding union queries,
  127. * however, the use of the union() method is preferred.
  128. *
  129. * Note that this method must be called by reference as well:
  130. *
  131. * @code
  132. * $fields =& $query->getUnion();
  133. * @endcode
  134. *
  135. * @return
  136. * A reference to the union query array structure.
  137. */
  138. public function &getUnion();
  139. /**
  140. * Compiles and returns an associative array of the arguments for this prepared statement.
  141. *
  142. * @param $queryPlaceholder
  143. * When collecting the arguments of a subquery, the main placeholder
  144. * object should be passed as this parameter.
  145. *
  146. * @return
  147. * An associative array of all placeholder arguments for this query.
  148. */
  149. public function getArguments(QueryPlaceholderInterface $queryPlaceholder = NULL);
  150. /* Query building operations */
  151. /**
  152. * Sets this query to be DISTINCT.
  153. *
  154. * @param $distinct
  155. * TRUE to flag this query DISTINCT, FALSE to disable it.
  156. * @return SelectQueryInterface
  157. * The called object.
  158. */
  159. public function distinct($distinct = TRUE);
  160. /**
  161. * Adds a field to the list to be SELECTed.
  162. *
  163. * @param $table_alias
  164. * The name of the table from which the field comes, as an alias. Generally
  165. * you will want to use the return value of join() here to ensure that it is
  166. * valid.
  167. * @param $field
  168. * The name of the field.
  169. * @param $alias
  170. * The alias for this field. If not specified, one will be generated
  171. * automatically based on the $table_alias and $field. The alias will be
  172. * checked for uniqueness, so the requested alias may not be the alias
  173. * that is assigned in all cases.
  174. * @return
  175. * The unique alias that was assigned for this field.
  176. */
  177. public function addField($table_alias, $field, $alias = NULL);
  178. /**
  179. * Add multiple fields from the same table to be SELECTed.
  180. *
  181. * This method does not return the aliases set for the passed fields. In the
  182. * majority of cases that is not a problem, as the alias will be the field
  183. * name. However, if you do need to know the alias you can call getFields()
  184. * and examine the result to determine what alias was created. Alternatively,
  185. * simply use addField() for the few fields you care about and this method for
  186. * the rest.
  187. *
  188. * @param $table_alias
  189. * The name of the table from which the field comes, as an alias. Generally
  190. * you will want to use the return value of join() here to ensure that it is
  191. * valid.
  192. * @param $fields
  193. * An indexed array of fields present in the specified table that should be
  194. * included in this query. If not specified, $table_alias.* will be generated
  195. * without any aliases.
  196. * @return SelectQueryInterface
  197. * The called object.
  198. */
  199. public function fields($table_alias, array $fields = array());
  200. /**
  201. * Adds an expression to the list of "fields" to be SELECTed.
  202. *
  203. * An expression can be any arbitrary string that is valid SQL. That includes
  204. * various functions, which may in some cases be database-dependent. This
  205. * method makes no effort to correct for database-specific functions.
  206. *
  207. * @param $expression
  208. * The expression string. May contain placeholders.
  209. * @param $alias
  210. * The alias for this expression. If not specified, one will be generated
  211. * automatically in the form "expression_#". The alias will be checked for
  212. * uniqueness, so the requested alias may not be the alias that is assigned
  213. * in all cases.
  214. * @param $arguments
  215. * Any placeholder arguments needed for this expression.
  216. * @return
  217. * The unique alias that was assigned for this expression.
  218. */
  219. public function addExpression($expression, $alias = NULL, $arguments = array());
  220. /**
  221. * Default Join against another table in the database.
  222. *
  223. * This method is a convenience method for innerJoin().
  224. *
  225. * @param $table
  226. * The table against which to join.
  227. * @param $alias
  228. * The alias for the table. In most cases this should be the first letter
  229. * of the table, or the first letter of each "word" in the table.
  230. * @param $condition
  231. * The condition on which to join this table. If the join requires values,
  232. * this clause should use a named placeholder and the value or values to
  233. * insert should be passed in the 4th parameter. For the first table joined
  234. * on a query, this value is ignored as the first table is taken as the base
  235. * table. The token %alias can be used in this string to be replaced with
  236. * the actual alias. This is useful when $alias is modified by the database
  237. * system, for example, when joining the same table more than once.
  238. * @param $arguments
  239. * An array of arguments to replace into the $condition of this join.
  240. * @return
  241. * The unique alias that was assigned for this table.
  242. */
  243. public function join($table, $alias = NULL, $condition = NULL, $arguments = array());
  244. /**
  245. * Inner Join against another table in the database.
  246. *
  247. * @param $table
  248. * The table against which to join.
  249. * @param $alias
  250. * The alias for the table. In most cases this should be the first letter
  251. * of the table, or the first letter of each "word" in the table.
  252. * @param $condition
  253. * The condition on which to join this table. If the join requires values,
  254. * this clause should use a named placeholder and the value or values to
  255. * insert should be passed in the 4th parameter. For the first table joined
  256. * on a query, this value is ignored as the first table is taken as the base
  257. * table. The token %alias can be used in this string to be replaced with
  258. * the actual alias. This is useful when $alias is modified by the database
  259. * system, for example, when joining the same table more than once.
  260. * @param $arguments
  261. * An array of arguments to replace into the $condition of this join.
  262. * @return
  263. * The unique alias that was assigned for this table.
  264. */
  265. public function innerJoin($table, $alias = NULL, $condition = NULL, $arguments = array());
  266. /**
  267. * Left Outer Join against another table in the database.
  268. *
  269. * @param $table
  270. * The table against which to join.
  271. * @param $alias
  272. * The alias for the table. In most cases this should be the first letter
  273. * of the table, or the first letter of each "word" in the table.
  274. * @param $condition
  275. * The condition on which to join this table. If the join requires values,
  276. * this clause should use a named placeholder and the value or values to
  277. * insert should be passed in the 4th parameter. For the first table joined
  278. * on a query, this value is ignored as the first table is taken as the base
  279. * table. The token %alias can be used in this string to be replaced with
  280. * the actual alias. This is useful when $alias is modified by the database
  281. * system, for example, when joining the same table more than once.
  282. * @param $arguments
  283. * An array of arguments to replace into the $condition of this join.
  284. * @return
  285. * The unique alias that was assigned for this table.
  286. */
  287. public function leftJoin($table, $alias = NULL, $condition = NULL, $arguments = array());
  288. /**
  289. * Right Outer Join against another table in the database.
  290. *
  291. * @param $table
  292. * The table against which to join.
  293. * @param $alias
  294. * The alias for the table. In most cases this should be the first letter
  295. * of the table, or the first letter of each "word" in the table.
  296. * @param $condition
  297. * The condition on which to join this table. If the join requires values,
  298. * this clause should use a named placeholder and the value or values to
  299. * insert should be passed in the 4th parameter. For the first table joined
  300. * on a query, this value is ignored as the first table is taken as the base
  301. * table. The token %alias can be used in this string to be replaced with
  302. * the actual alias. This is useful when $alias is modified by the database
  303. * system, for example, when joining the same table more than once.
  304. * @param $arguments
  305. * An array of arguments to replace into the $condition of this join.
  306. * @return
  307. * The unique alias that was assigned for this table.
  308. */
  309. public function rightJoin($table, $alias = NULL, $condition = NULL, $arguments = array());
  310. /**
  311. * Join against another table in the database.
  312. *
  313. * This method does the "hard" work of queuing up a table to be joined against.
  314. * In some cases, that may include dipping into the Schema API to find the necessary
  315. * fields on which to join.
  316. *
  317. * @param $type
  318. * The type of join. Typically one one of INNER, LEFT OUTER, and RIGHT OUTER.
  319. * @param $table
  320. * The table against which to join. May be a string or another SelectQuery
  321. * object. If a query object is passed, it will be used as a subselect.
  322. * @param $alias
  323. * The alias for the table. In most cases this should be the first letter
  324. * of the table, or the first letter of each "word" in the table. If omitted,
  325. * one will be dynamically generated.
  326. * @param $condition
  327. * The condition on which to join this table. If the join requires values,
  328. * this clause should use a named placeholder and the value or values to
  329. * insert should be passed in the 4th parameter. For the first table joined
  330. * on a query, this value is ignored as the first table is taken as the base
  331. * table. The token %alias can be used in this string to be replaced with
  332. * the actual alias. This is useful when $alias is modified by the database
  333. * system, for example, when joining the same table more than once.
  334. * @param $arguments
  335. * An array of arguments to replace into the $condition of this join.
  336. * @return
  337. * The unique alias that was assigned for this table.
  338. */
  339. public function addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = array());
  340. /**
  341. * Orders the result set by a given field.
  342. *
  343. * If called multiple times, the query will order by each specified field in the
  344. * order this method is called.
  345. *
  346. * If the query uses DISTINCT or GROUP BY conditions, fields or expressions
  347. * that are used for the order must be selected to be compatible with some
  348. * databases like PostgreSQL. The PostgreSQL driver can handle simple cases
  349. * automatically but it is suggested to explicitly specify them. Additionally,
  350. * when ordering on an alias, the alias must be added before orderBy() is
  351. * called.
  352. *
  353. * @param $field
  354. * The field on which to order.
  355. * @param $direction
  356. * The direction to sort. Legal values are "ASC" and "DESC". Any other value
  357. * will be converted to "ASC".
  358. * @return SelectQueryInterface
  359. * The called object.
  360. */
  361. public function orderBy($field, $direction = 'ASC');
  362. /**
  363. * Orders the result set by a random value.
  364. *
  365. * This may be stacked with other orderBy() calls. If so, the query will order
  366. * by each specified field, including this one, in the order called. Although
  367. * this method may be called multiple times on the same query, doing so
  368. * is not particularly useful.
  369. *
  370. * Note: The method used by most drivers may not scale to very large result
  371. * sets. If you need to work with extremely large data sets, you may create
  372. * your own database driver by subclassing off of an existing driver and
  373. * implementing your own randomization mechanism. See
  374. *
  375. * http://jan.kneschke.de/projects/mysql/order-by-rand/
  376. *
  377. * for an example of such an alternate sorting mechanism.
  378. *
  379. * @return SelectQueryInterface
  380. * The called object
  381. */
  382. public function orderRandom();
  383. /**
  384. * Restricts a query to a given range in the result set.
  385. *
  386. * If this method is called with no parameters, will remove any range
  387. * directives that have been set.
  388. *
  389. * @param $start
  390. * The first record from the result set to return. If NULL, removes any
  391. * range directives that are set.
  392. * @param $length
  393. * The number of records to return from the result set.
  394. * @return SelectQueryInterface
  395. * The called object.
  396. */
  397. public function range($start = NULL, $length = NULL);
  398. /**
  399. * Add another Select query to UNION to this one.
  400. *
  401. * Union queries consist of two or more queries whose
  402. * results are effectively concatenated together. Queries
  403. * will be UNIONed in the order they are specified, with
  404. * this object's query coming first. Duplicate columns will
  405. * be discarded. All forms of UNION are supported, using
  406. * the second '$type' argument.
  407. *
  408. * Note: All queries UNIONed together must have the same
  409. * field structure, in the same order. It is up to the
  410. * caller to ensure that they match properly. If they do
  411. * not, an SQL syntax error will result.
  412. *
  413. * @param $query
  414. * The query to UNION to this query.
  415. * @param $type
  416. * The type of UNION to add to the query. Defaults to plain
  417. * UNION.
  418. * @return SelectQueryInterface
  419. * The called object.
  420. */
  421. public function union(SelectQueryInterface $query, $type = '');
  422. /**
  423. * Groups the result set by the specified field.
  424. *
  425. * @param $field
  426. * The field on which to group. This should be the field as aliased.
  427. * @return SelectQueryInterface
  428. * The called object.
  429. */
  430. public function groupBy($field);
  431. /**
  432. * Get the equivalent COUNT query of this query as a new query object.
  433. *
  434. * @return SelectQueryInterface
  435. * A new SelectQuery object with no fields or expressions besides COUNT(*).
  436. */
  437. public function countQuery();
  438. /**
  439. * Indicates if preExecute() has already been called on that object.
  440. *
  441. * @return
  442. * TRUE is this query has already been prepared, FALSE otherwise.
  443. */
  444. public function isPrepared();
  445. /**
  446. * Generic preparation and validation for a SELECT query.
  447. *
  448. * @return
  449. * TRUE if the validation was successful, FALSE if not.
  450. */
  451. public function preExecute(SelectQueryInterface $query = NULL);
  452. /**
  453. * Helper function to build most common HAVING conditional clauses.
  454. *
  455. * This method can take a variable number of parameters. If called with two
  456. * parameters, they are taken as $field and $value with $operator having a value
  457. * of IN if $value is an array and = otherwise.
  458. *
  459. * @param $field
  460. * The name of the field to check. If you would like to add a more complex
  461. * condition involving operators or functions, use having().
  462. * @param $value
  463. * The value to test the field against. In most cases, this is a scalar. For more
  464. * complex options, it is an array. The meaning of each element in the array is
  465. * dependent on the $operator.
  466. * @param $operator
  467. * The comparison operator, such as =, <, or >=. It also accepts more complex
  468. * options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is an array
  469. * = otherwise.
  470. * @return QueryConditionInterface
  471. * The called object.
  472. */
  473. public function havingCondition($field, $value = NULL, $operator = NULL);
  474. /**
  475. * Clone magic method.
  476. *
  477. * Select queries have dependent objects that must be deep-cloned. The
  478. * connection object itself, however, should not be cloned as that would
  479. * duplicate the connection itself.
  480. */
  481. public function __clone();
  482. /**
  483. * Add FOR UPDATE to the query.
  484. *
  485. * FOR UPDATE prevents the rows retrieved by the SELECT statement from being
  486. * modified or deleted by other transactions until the current transaction
  487. * ends. Other transactions that attempt UPDATE, DELETE, or SELECT FOR UPDATE
  488. * of these rows will be blocked until the current transaction ends.
  489. *
  490. * @param $set
  491. * IF TRUE, FOR UPDATE will be added to the query, if FALSE then it won't.
  492. *
  493. * @return QueryConditionInterface
  494. * The called object.
  495. */
  496. public function forUpdate($set = TRUE);
  497. }
  498. /**
  499. * The base extender class for Select queries.
  500. */
  501. class SelectQueryExtender implements SelectQueryInterface {
  502. /**
  503. * The SelectQuery object we are extending/decorating.
  504. *
  505. * @var SelectQueryInterface
  506. */
  507. protected $query;
  508. /**
  509. * The connection object on which to run this query.
  510. *
  511. * @var DatabaseConnection
  512. */
  513. protected $connection;
  514. /**
  515. * A unique identifier for this query object.
  516. */
  517. protected $uniqueIdentifier;
  518. /**
  519. * The placeholder counter.
  520. */
  521. protected $placeholder = 0;
  522. public function __construct(SelectQueryInterface $query, DatabaseConnection $connection) {
  523. $this->uniqueIdentifier = uniqid('', TRUE);
  524. $this->query = $query;
  525. $this->connection = $connection;
  526. }
  527. /**
  528. * Implements QueryPlaceholderInterface::uniqueIdentifier().
  529. */
  530. public function uniqueIdentifier() {
  531. return $this->uniqueIdentifier;
  532. }
  533. /**
  534. * Implements QueryPlaceholderInterface::nextPlaceholder().
  535. */
  536. public function nextPlaceholder() {
  537. return $this->placeholder++;
  538. }
  539. /* Implementations of QueryAlterableInterface. */
  540. public function addTag($tag) {
  541. $this->query->addTag($tag);
  542. return $this;
  543. }
  544. public function hasTag($tag) {
  545. return $this->query->hasTag($tag);
  546. }
  547. public function hasAllTags() {
  548. $args = func_get_args();
  549. return call_user_func_array(array($this->query, 'hasAllTags'), $args);
  550. }
  551. public function hasAnyTag() {
  552. $args = func_get_args();
  553. return call_user_func_array(array($this->query, 'hasAnyTag'), $args);
  554. }
  555. public function addMetaData($key, $object) {
  556. $this->query->addMetaData($key, $object);
  557. return $this;
  558. }
  559. public function getMetaData($key) {
  560. return $this->query->getMetaData($key);
  561. }
  562. /* Implementations of QueryConditionInterface for the WHERE clause. */
  563. public function condition($field, $value = NULL, $operator = NULL) {
  564. $this->query->condition($field, $value, $operator);
  565. return $this;
  566. }
  567. public function &conditions() {
  568. return $this->query->conditions();
  569. }
  570. public function arguments() {
  571. return $this->query->arguments();
  572. }
  573. public function where($snippet, $args = array()) {
  574. $this->query->where($snippet, $args);
  575. return $this;
  576. }
  577. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder) {
  578. return $this->query->compile($connection, $queryPlaceholder);
  579. }
  580. public function compiled() {
  581. return $this->query->compiled();
  582. }
  583. /* Implementations of QueryConditionInterface for the HAVING clause. */
  584. public function havingCondition($field, $value = NULL, $operator = '=') {
  585. $this->query->havingCondition($field, $value, $operator);
  586. return $this;
  587. }
  588. public function &havingConditions() {
  589. return $this->query->havingConditions();
  590. }
  591. public function havingArguments() {
  592. return $this->query->havingArguments();
  593. }
  594. public function having($snippet, $args = array()) {
  595. $this->query->having($snippet, $args);
  596. return $this;
  597. }
  598. public function havingCompile(DatabaseConnection $connection) {
  599. return $this->query->havingCompile($connection);
  600. }
  601. /* Implementations of QueryExtendableInterface. */
  602. public function extend($extender_name) {
  603. // The extender can be anywhere so this needs to go to the registry, which
  604. // is surely loaded by now.
  605. $class = $this->connection->getDriverClass($extender_name, array(), TRUE);
  606. return new $class($this, $this->connection);
  607. }
  608. /* Alter accessors to expose the query data to alter hooks. */
  609. public function &getFields() {
  610. return $this->query->getFields();
  611. }
  612. public function &getExpressions() {
  613. return $this->query->getExpressions();
  614. }
  615. public function &getOrderBy() {
  616. return $this->query->getOrderBy();
  617. }
  618. public function &getGroupBy() {
  619. return $this->query->getGroupBy();
  620. }
  621. public function &getTables() {
  622. return $this->query->getTables();
  623. }
  624. public function &getUnion() {
  625. return $this->query->getUnion();
  626. }
  627. public function getArguments(QueryPlaceholderInterface $queryPlaceholder = NULL) {
  628. return $this->query->getArguments($queryPlaceholder);
  629. }
  630. public function isPrepared() {
  631. return $this->query->isPrepared();
  632. }
  633. public function preExecute(SelectQueryInterface $query = NULL) {
  634. // If no query object is passed in, use $this.
  635. if (!isset($query)) {
  636. $query = $this;
  637. }
  638. return $this->query->preExecute($query);
  639. }
  640. public function execute() {
  641. // By calling preExecute() here, we force it to preprocess the extender
  642. // object rather than just the base query object. That means
  643. // hook_query_alter() gets access to the extended object.
  644. if (!$this->preExecute($this)) {
  645. return NULL;
  646. }
  647. return $this->query->execute();
  648. }
  649. public function distinct($distinct = TRUE) {
  650. $this->query->distinct($distinct);
  651. return $this;
  652. }
  653. public function addField($table_alias, $field, $alias = NULL) {
  654. return $this->query->addField($table_alias, $field, $alias);
  655. }
  656. public function fields($table_alias, array $fields = array()) {
  657. $this->query->fields($table_alias, $fields);
  658. return $this;
  659. }
  660. public function addExpression($expression, $alias = NULL, $arguments = array()) {
  661. return $this->query->addExpression($expression, $alias, $arguments);
  662. }
  663. public function join($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  664. return $this->query->join($table, $alias, $condition, $arguments);
  665. }
  666. public function innerJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  667. return $this->query->innerJoin($table, $alias, $condition, $arguments);
  668. }
  669. public function leftJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  670. return $this->query->leftJoin($table, $alias, $condition, $arguments);
  671. }
  672. public function rightJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  673. return $this->query->rightJoin($table, $alias, $condition, $arguments);
  674. }
  675. public function addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = array()) {
  676. return $this->query->addJoin($type, $table, $alias, $condition, $arguments);
  677. }
  678. public function orderBy($field, $direction = 'ASC') {
  679. $this->query->orderBy($field, $direction);
  680. return $this;
  681. }
  682. public function orderRandom() {
  683. $this->query->orderRandom();
  684. return $this;
  685. }
  686. public function range($start = NULL, $length = NULL) {
  687. $this->query->range($start, $length);
  688. return $this;
  689. }
  690. public function union(SelectQueryInterface $query, $type = '') {
  691. $this->query->union($query, $type);
  692. return $this;
  693. }
  694. public function groupBy($field) {
  695. $this->query->groupBy($field);
  696. return $this;
  697. }
  698. public function forUpdate($set = TRUE) {
  699. $this->query->forUpdate($set);
  700. return $this;
  701. }
  702. public function countQuery() {
  703. return $this->query->countQuery();
  704. }
  705. function isNull($field) {
  706. $this->query->isNull($field);
  707. return $this;
  708. }
  709. function isNotNull($field) {
  710. $this->query->isNotNull($field);
  711. return $this;
  712. }
  713. public function exists(SelectQueryInterface $select) {
  714. $this->query->exists($select);
  715. return $this;
  716. }
  717. public function notExists(SelectQueryInterface $select) {
  718. $this->query->notExists($select);
  719. return $this;
  720. }
  721. public function __toString() {
  722. return (string) $this->query;
  723. }
  724. public function __clone() {
  725. $this->uniqueIdentifier = uniqid('', TRUE);
  726. // We need to deep-clone the query we're wrapping, which in turn may
  727. // deep-clone other objects. Exciting!
  728. $this->query = clone($this->query);
  729. }
  730. /**
  731. * Magic override for undefined methods.
  732. *
  733. * If one extender extends another extender, then methods in the inner extender
  734. * will not be exposed on the outer extender. That's because we cannot know
  735. * in advance what those methods will be, so we cannot provide wrapping
  736. * implementations as we do above. Instead, we use this slower catch-all method
  737. * to handle any additional methods.
  738. */
  739. public function __call($method, $args) {
  740. $return = call_user_func_array(array($this->query, $method), $args);
  741. // Some methods will return the called object as part of a fluent interface.
  742. // Others will return some useful value. If it's a value, then the caller
  743. // probably wants that value. If it's the called object, then we instead
  744. // return this object. That way we don't "lose" an extender layer when
  745. // chaining methods together.
  746. if ($return instanceof SelectQueryInterface) {
  747. return $this;
  748. }
  749. else {
  750. return $return;
  751. }
  752. }
  753. }
  754. /**
  755. * Query builder for SELECT statements.
  756. */
  757. class SelectQuery extends Query implements SelectQueryInterface {
  758. /**
  759. * The fields to SELECT.
  760. *
  761. * @var array
  762. */
  763. protected $fields = array();
  764. /**
  765. * The expressions to SELECT as virtual fields.
  766. *
  767. * @var array
  768. */
  769. protected $expressions = array();
  770. /**
  771. * The tables against which to JOIN.
  772. *
  773. * This property is a nested array. Each entry is an array representing
  774. * a single table against which to join. The structure of each entry is:
  775. *
  776. * array(
  777. * 'type' => $join_type (one of INNER, LEFT OUTER, RIGHT OUTER),
  778. * 'table' => $table,
  779. * 'alias' => $alias_of_the_table,
  780. * 'condition' => $condition_clause_on_which_to_join,
  781. * 'arguments' => $array_of_arguments_for_placeholders_in_the condition.
  782. * 'all_fields' => TRUE to SELECT $alias.*, FALSE or NULL otherwise.
  783. * )
  784. *
  785. * If $table is a string, it is taken as the name of a table. If it is
  786. * a SelectQuery object, it is taken as a subquery.
  787. *
  788. * @var array
  789. */
  790. protected $tables = array();
  791. /**
  792. * The fields by which to order this query.
  793. *
  794. * This is an associative array. The keys are the fields to order, and the value
  795. * is the direction to order, either ASC or DESC.
  796. *
  797. * @var array
  798. */
  799. protected $order = array();
  800. /**
  801. * The fields by which to group.
  802. *
  803. * @var array
  804. */
  805. protected $group = array();
  806. /**
  807. * The conditional object for the WHERE clause.
  808. *
  809. * @var DatabaseCondition
  810. */
  811. protected $where;
  812. /**
  813. * The conditional object for the HAVING clause.
  814. *
  815. * @var DatabaseCondition
  816. */
  817. protected $having;
  818. /**
  819. * Whether or not this query should be DISTINCT
  820. *
  821. * @var boolean
  822. */
  823. protected $distinct = FALSE;
  824. /**
  825. * The range limiters for this query.
  826. *
  827. * @var array
  828. */
  829. protected $range;
  830. /**
  831. * An array whose elements specify a query to UNION, and the UNION type. The
  832. * 'type' key may be '', 'ALL', or 'DISTINCT' to represent a 'UNION',
  833. * 'UNION ALL', or 'UNION DISTINCT' statement, respectively.
  834. *
  835. * All entries in this array will be applied from front to back, with the
  836. * first query to union on the right of the original query, the second union
  837. * to the right of the first, etc.
  838. *
  839. * @var array
  840. */
  841. protected $union = array();
  842. /**
  843. * Indicates if preExecute() has already been called.
  844. * @var boolean
  845. */
  846. protected $prepared = FALSE;
  847. /**
  848. * The FOR UPDATE status
  849. */
  850. protected $forUpdate = FALSE;
  851. public function __construct($table, $alias = NULL, DatabaseConnection $connection, $options = array()) {
  852. $options['return'] = Database::RETURN_STATEMENT;
  853. parent::__construct($connection, $options);
  854. $this->where = new DatabaseCondition('AND');
  855. $this->having = new DatabaseCondition('AND');
  856. $this->addJoin(NULL, $table, $alias);
  857. }
  858. /* Implementations of QueryAlterableInterface. */
  859. public function addTag($tag) {
  860. $this->alterTags[$tag] = 1;
  861. return $this;
  862. }
  863. public function hasTag($tag) {
  864. return isset($this->alterTags[$tag]);
  865. }
  866. public function hasAllTags() {
  867. $args = func_get_args();
  868. return !(boolean)array_diff($args, array_keys($this->alterTags));
  869. }
  870. public function hasAnyTag() {
  871. $args = func_get_args();
  872. return (boolean)array_intersect($args, array_keys($this->alterTags));
  873. }
  874. public function addMetaData($key, $object) {
  875. $this->alterMetaData[$key] = $object;
  876. return $this;
  877. }
  878. public function getMetaData($key) {
  879. return isset($this->alterMetaData[$key]) ? $this->alterMetaData[$key] : NULL;
  880. }
  881. /* Implementations of QueryConditionInterface for the WHERE clause. */
  882. public function condition($field, $value = NULL, $operator = NULL) {
  883. $this->where->condition($field, $value, $operator);
  884. return $this;
  885. }
  886. public function &conditions() {
  887. return $this->where->conditions();
  888. }
  889. public function arguments() {
  890. if (!$this->compiled()) {
  891. return NULL;
  892. }
  893. $args = $this->where->arguments() + $this->having->arguments();
  894. foreach ($this->tables as $table) {
  895. if ($table['arguments']) {
  896. $args += $table['arguments'];
  897. }
  898. // If this table is a subquery, grab its arguments recursively.
  899. if ($table['table'] instanceof SelectQueryInterface) {
  900. $args += $table['table']->arguments();
  901. }
  902. }
  903. foreach ($this->expressions as $expression) {
  904. if ($expression['arguments']) {
  905. $args += $expression['arguments'];
  906. }
  907. }
  908. // If there are any dependent queries to UNION,
  909. // incorporate their arguments recursively.
  910. foreach ($this->union as $union) {
  911. $args += $union['query']->arguments();
  912. }
  913. return $args;
  914. }
  915. public function where($snippet, $args = array()) {
  916. $this->where->where($snippet, $args);
  917. return $this;
  918. }
  919. public function isNull($field) {
  920. $this->where->isNull($field);
  921. return $this;
  922. }
  923. public function isNotNull($field) {
  924. $this->where->isNotNull($field);
  925. return $this;
  926. }
  927. public function exists(SelectQueryInterface $select) {
  928. $this->where->exists($select);
  929. return $this;
  930. }
  931. public function notExists(SelectQueryInterface $select) {
  932. $this->where->notExists($select);
  933. return $this;
  934. }
  935. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder) {
  936. $this->where->compile($connection, $queryPlaceholder);
  937. $this->having->compile($connection, $queryPlaceholder);
  938. foreach ($this->tables as $table) {
  939. // If this table is a subquery, compile it recursively.
  940. if ($table['table'] instanceof SelectQueryInterface) {
  941. $table['table']->compile($connection, $queryPlaceholder);
  942. }
  943. }
  944. // If there are any dependent queries to UNION, compile it recursively.
  945. foreach ($this->union as $union) {
  946. $union['query']->compile($connection, $queryPlaceholder);
  947. }
  948. }
  949. public function compiled() {
  950. if (!$this->where->compiled() || !$this->having->compiled()) {
  951. return FALSE;
  952. }
  953. foreach ($this->tables as $table) {
  954. // If this table is a subquery, check its status recursively.
  955. if ($table['table'] instanceof SelectQueryInterface) {
  956. if (!$table['table']->compiled()) {
  957. return FALSE;
  958. }
  959. }
  960. }
  961. foreach ($this->union as $union) {
  962. if (!$union['query']->compiled()) {
  963. return FALSE;
  964. }
  965. }
  966. return TRUE;
  967. }
  968. /* Implementations of QueryConditionInterface for the HAVING clause. */
  969. public function havingCondition($field, $value = NULL, $operator = NULL) {
  970. $this->having->condition($field, $value, $operator);
  971. return $this;
  972. }
  973. public function &havingConditions() {
  974. return $this->having->conditions();
  975. }
  976. public function havingArguments() {
  977. return $this->having->arguments();
  978. }
  979. public function having($snippet, $args = array()) {
  980. $this->having->where($snippet, $args);
  981. return $this;
  982. }
  983. public function havingCompile(DatabaseConnection $connection) {
  984. return $this->having->compile($connection, $this);
  985. }
  986. /* Implementations of QueryExtendableInterface. */
  987. public function extend($extender_name) {
  988. $override_class = $extender_name . '_' . $this->connection->driver();
  989. if (class_exists($override_class)) {
  990. $extender_name = $override_class;
  991. }
  992. return new $extender_name($this, $this->connection);
  993. }
  994. public function havingIsNull($field) {
  995. $this->having->isNull($field);
  996. return $this;
  997. }
  998. public function havingIsNotNull($field) {
  999. $this->having->isNotNull($field);
  1000. return $this;
  1001. }
  1002. public function havingExists(SelectQueryInterface $select) {
  1003. $this->having->exists($select);
  1004. return $this;
  1005. }
  1006. public function havingNotExists(SelectQueryInterface $select) {
  1007. $this->having->notExists($select);
  1008. return $this;
  1009. }
  1010. public function forUpdate($set = TRUE) {
  1011. if (isset($set)) {
  1012. $this->forUpdate = $set;
  1013. }
  1014. return $this;
  1015. }
  1016. /* Alter accessors to expose the query data to alter hooks. */
  1017. public function &getFields() {
  1018. return $this->fields;
  1019. }
  1020. public function &getExpressions() {
  1021. return $this->expressions;
  1022. }
  1023. public function &getOrderBy() {
  1024. return $this->order;
  1025. }
  1026. public function &getGroupBy() {
  1027. return $this->group;
  1028. }
  1029. public function &getTables() {
  1030. return $this->tables;
  1031. }
  1032. public function &getUnion() {
  1033. return $this->union;
  1034. }
  1035. public function getArguments(QueryPlaceholderInterface $queryPlaceholder = NULL) {
  1036. if (!isset($queryPlaceholder)) {
  1037. $queryPlaceholder = $this;
  1038. }
  1039. $this->compile($this->connection, $queryPlaceholder);
  1040. return $this->arguments();
  1041. }
  1042. /**
  1043. * Indicates if preExecute() has already been called on that object.
  1044. */
  1045. public function isPrepared() {
  1046. return $this->prepared;
  1047. }
  1048. /**
  1049. * Generic preparation and validation for a SELECT query.
  1050. *
  1051. * @return
  1052. * TRUE if the validation was successful, FALSE if not.
  1053. */
  1054. public function preExecute(SelectQueryInterface $query = NULL) {
  1055. // If no query object is passed in, use $this.
  1056. if (!isset($query)) {
  1057. $query = $this;
  1058. }
  1059. // Only execute this once.
  1060. if ($query->isPrepared()) {
  1061. return TRUE;
  1062. }
  1063. // Modules may alter all queries or only those having a particular tag.
  1064. if (isset($this->alterTags)) {
  1065. $hooks = array('query');
  1066. foreach ($this->alterTags as $tag => $value) {
  1067. $hooks[] = 'query_' . $tag;
  1068. }
  1069. drupal_alter($hooks, $query);
  1070. }
  1071. $this->prepared = TRUE;
  1072. // Now also prepare any sub-queries.
  1073. foreach ($this->tables as $table) {
  1074. if ($table['table'] instanceof SelectQueryInterface) {
  1075. $table['table']->preExecute();
  1076. }
  1077. }
  1078. foreach ($this->union as $union) {
  1079. $union['query']->preExecute();
  1080. }
  1081. return $this->prepared;
  1082. }
  1083. public function execute() {
  1084. // If validation fails, simply return NULL.
  1085. // Note that validation routines in preExecute() may throw exceptions instead.
  1086. if (!$this->preExecute()) {
  1087. return NULL;
  1088. }
  1089. $args = $this->getArguments();
  1090. return $this->connection->query((string) $this, $args, $this->queryOptions);
  1091. }
  1092. public function distinct($distinct = TRUE) {
  1093. $this->distinct = $distinct;
  1094. return $this;
  1095. }
  1096. public function addField($table_alias, $field, $alias = NULL) {
  1097. // If no alias is specified, first try the field name itself.
  1098. if (empty($alias)) {
  1099. $alias = $field;
  1100. }
  1101. // If that's already in use, try the table name and field name.
  1102. if (!empty($this->fields[$alias])) {
  1103. $alias = $table_alias . '_' . $field;
  1104. }
  1105. // If that is already used, just add a counter until we find an unused alias.
  1106. $alias_candidate = $alias;
  1107. $count = 2;
  1108. while (!empty($this->fields[$alias_candidate])) {
  1109. $alias_candidate = $alias . '_' . $count++;
  1110. }
  1111. $alias = $alias_candidate;
  1112. $this->fields[$alias] = array(
  1113. 'field' => $field,
  1114. 'table' => $table_alias,
  1115. 'alias' => $alias,
  1116. );
  1117. return $alias;
  1118. }
  1119. public function fields($table_alias, array $fields = array()) {
  1120. if ($fields) {
  1121. foreach ($fields as $field) {
  1122. // We don't care what alias was assigned.
  1123. $this->addField($table_alias, $field);
  1124. }
  1125. }
  1126. else {
  1127. // We want all fields from this table.
  1128. $this->tables[$table_alias]['all_fields'] = TRUE;
  1129. }
  1130. return $this;
  1131. }
  1132. public function addExpression($expression, $alias = NULL, $arguments = array()) {
  1133. if (empty($alias)) {
  1134. $alias = 'expression';
  1135. }
  1136. $alias_candidate = $alias;
  1137. $count = 2;
  1138. while (!empty($this->expressions[$alias_candidate])) {
  1139. $alias_candidate = $alias . '_' . $count++;
  1140. }
  1141. $alias = $alias_candidate;
  1142. $this->expressions[$alias] = array(
  1143. 'expression' => $expression,
  1144. 'alias' => $alias,
  1145. 'arguments' => $arguments,
  1146. );
  1147. return $alias;
  1148. }
  1149. public function join($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  1150. return $this->addJoin('INNER', $table, $alias, $condition, $arguments);
  1151. }
  1152. public function innerJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  1153. return $this->addJoin('INNER', $table, $alias, $condition, $arguments);
  1154. }
  1155. public function leftJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  1156. return $this->addJoin('LEFT OUTER', $table, $alias, $condition, $arguments);
  1157. }
  1158. public function rightJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
  1159. return $this->addJoin('RIGHT OUTER', $table, $alias, $condition, $arguments);
  1160. }
  1161. public function addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = array()) {
  1162. if (empty($alias)) {
  1163. if ($table instanceof SelectQueryInterface) {
  1164. $alias = 'subquery';
  1165. }
  1166. else {
  1167. $alias = $table;
  1168. }
  1169. }
  1170. $alias_candidate = $alias;
  1171. $count = 2;
  1172. while (!empty($this->tables[$alias_candidate])) {
  1173. $alias_candidate = $alias . '_' . $count++;
  1174. }
  1175. $alias = $alias_candidate;
  1176. if (is_string($condition)) {
  1177. $condition = str_replace('%alias', $alias, $condition);
  1178. }
  1179. $this->tables[$alias] = array(
  1180. 'join type' => $type,
  1181. 'table' => $table,
  1182. 'alias' => $alias,
  1183. 'condition' => $condition,
  1184. 'arguments' => $arguments,
  1185. );
  1186. return $alias;
  1187. }
  1188. public function orderBy($field, $direction = 'ASC') {
  1189. // Only allow ASC and DESC, default to ASC.
  1190. $direction = strtoupper($direction) == 'DESC' ? 'DESC' : 'ASC';
  1191. $this->order[$field] = $direction;
  1192. return $this;
  1193. }
  1194. public function orderRandom() {
  1195. $alias = $this->addExpression('RAND()', 'random_field');
  1196. $this->orderBy($alias);
  1197. return $this;
  1198. }
  1199. public function range($start = NULL, $length = NULL) {
  1200. $this->range = func_num_args() ? array('start' => $start, 'length' => $length) : array();
  1201. return $this;
  1202. }
  1203. public function union(SelectQueryInterface $query, $type = '') {
  1204. // Handle UNION aliasing.
  1205. switch ($type) {
  1206. // Fold UNION DISTINCT to UNION for better cross database support.
  1207. case 'DISTINCT':
  1208. case '':
  1209. $type = 'UNION';
  1210. break;
  1211. case 'ALL':
  1212. $type = 'UNION ALL';
  1213. default:
  1214. }
  1215. $this->union[] = array(
  1216. 'type' => $type,
  1217. 'query' => $query,
  1218. );
  1219. return $this;
  1220. }
  1221. public function groupBy($field) {
  1222. $this->group[$field] = $field;
  1223. return $this;
  1224. }
  1225. public function countQuery() {
  1226. // Create our new query object that we will mutate into a count query.
  1227. $count = clone($this);
  1228. $group_by = $count->getGroupBy();
  1229. $having = $count->havingConditions();
  1230. if (!$count->distinct && !isset($having[0])) {
  1231. // When not executing a distinct query, we can zero-out existing fields
  1232. // and expressions that are not used by a GROUP BY or HAVING. Fields
  1233. // listed in a GROUP BY or HAVING clause need to be present in the
  1234. // query.
  1235. $fields =& $count->getFields();
  1236. foreach (array_keys($fields) as $field) {
  1237. if (empty($group_by[$field])) {
  1238. unset($fields[$field]);
  1239. }
  1240. }
  1241. $expressions =& $count->getExpressions();
  1242. foreach (array_keys($expressions) as $field) {
  1243. if (empty($group_by[$field])) {
  1244. unset($expressions[$field]);
  1245. }
  1246. }
  1247. // Also remove 'all_fields' statements, which are expanded into tablename.*
  1248. // when the query is executed.
  1249. foreach ($count->tables as $alias => &$table) {
  1250. unset($table['all_fields']);
  1251. }
  1252. }
  1253. // If we've just removed all fields from the query, make sure there is at
  1254. // least one so that the query still runs.
  1255. $count->addExpression('1');
  1256. // Ordering a count query is a waste of cycles, and breaks on some
  1257. // databases anyway.
  1258. $orders = &$count->getOrderBy();
  1259. $orders = array();
  1260. if ($count->distinct && !empty($group_by)) {
  1261. // If the query is distinct and contains a GROUP BY, we need to remove the
  1262. // distinct because SQL99 does not support counting on distinct multiple fields.
  1263. $count->distinct = FALSE;
  1264. }
  1265. $query = $this->connection->select($count);
  1266. $query->addExpression('COUNT(*)');
  1267. return $query;
  1268. }
  1269. public function __toString() {
  1270. // For convenience, we compile the query ourselves if the caller forgot
  1271. // to do it. This allows constructs like "(string) $query" to work. When
  1272. // the query will be executed, it will be recompiled using the proper
  1273. // placeholder generator anyway.
  1274. if (!$this->compiled()) {
  1275. $this->compile($this->connection, $this);
  1276. }
  1277. // Create a sanitized comment string to prepend to the query.
  1278. $comments = $this->connection->makeComment($this->comments);
  1279. // SELECT
  1280. $query = $comments . 'SELECT ';
  1281. if ($this->distinct) {
  1282. $query .= 'DISTINCT ';
  1283. }
  1284. // FIELDS and EXPRESSIONS
  1285. $fields = array();
  1286. foreach ($this->tables as $alias => $table) {
  1287. if (!empty($table['all_fields'])) {
  1288. $fields[] = $this->connection->escapeTable($alias) . '.*';
  1289. }
  1290. }
  1291. foreach ($this->fields as $alias => $field) {
  1292. // Always use the AS keyword for field aliases, as some
  1293. // databases require it (e.g., PostgreSQL).
  1294. $fields[] = (isset($field['table']) ? $this->connection->escapeTable($field['table']) . '.' : '') . $this->connection->escapeField($field['field']) . ' AS ' . $this->connection->escapeAlias($field['alias']);
  1295. }
  1296. foreach ($this->expressions as $alias => $expression) {
  1297. $fields[] = $expression['expression'] . ' AS ' . $this->connection->escapeAlias($expression['alias']);
  1298. }
  1299. $query .= implode(', ', $fields);
  1300. // FROM - We presume all queries have a FROM, as any query that doesn't won't need the query builder anyway.
  1301. $query .= "\nFROM ";
  1302. foreach ($this->tables as $alias => $table) {
  1303. $query .= "\n";
  1304. if (isset($table['join type'])) {
  1305. $query .= $table['join type'] . ' JOIN ';
  1306. }
  1307. // If the table is a subquery, compile it and integrate it into this query.
  1308. if ($table['table'] instanceof SelectQueryInterface) {
  1309. // Run preparation steps on this sub-query before converting to string.
  1310. $subquery = $table['table'];
  1311. $subquery->preExecute();
  1312. $table_string = '(' . (string) $subquery . ')';
  1313. }
  1314. else {
  1315. $table_string = '{' . $this->connection->escapeTable($table['table']) . '}';
  1316. }
  1317. // Don't use the AS keyword for table aliases, as some
  1318. // databases don't support it (e.g., Oracle).
  1319. $query .= $table_string . ' ' . $this->connection->escapeTable($table['alias']);
  1320. if (!empty($table['condition'])) {
  1321. $query .= ' ON ' . $table['condition'];
  1322. }
  1323. }
  1324. // WHERE
  1325. if (count($this->where)) {
  1326. // There is an implicit string cast on $this->condition.
  1327. $query .= "\nWHERE " . $this->where;
  1328. }
  1329. // GROUP BY
  1330. if ($this->group) {
  1331. $query .= "\nGROUP BY " . implode(', ', $this->group);
  1332. }
  1333. // HAVING
  1334. if (count($this->having)) {
  1335. // There is an implicit string cast on $this->having.
  1336. $query .= "\nHAVING " . $this->having;
  1337. }
  1338. // ORDER BY
  1339. if ($this->order) {
  1340. $query .= "\nORDER BY ";
  1341. $fields = array();
  1342. foreach ($this->order as $field => $direction) {
  1343. $fields[] = $field . ' ' . $direction;
  1344. }
  1345. $query .= implode(', ', $fields);
  1346. }
  1347. // RANGE
  1348. // There is no universal SQL standard for handling range or limit clauses.
  1349. // Fortunately, all core-supported databases use the same range syntax.
  1350. // Databases that need a different syntax can override this method and
  1351. // do whatever alternate logic they need to.
  1352. if (!empty($this->range)) {
  1353. $query .= "\nLIMIT " . (int) $this->range['length'] . " OFFSET " . (int) $this->range['start'];
  1354. }
  1355. // UNION is a little odd, as the select queries to combine are passed into
  1356. // this query, but syntactically they all end up on the same level.
  1357. if ($this->union) {
  1358. foreach ($this->union as $union) {
  1359. $query .= ' ' . $union['type'] . ' ' . (string) $union['query'];
  1360. }
  1361. }
  1362. if ($this->forUpdate) {
  1363. $query .= ' FOR UPDATE';
  1364. }
  1365. return $query;
  1366. }
  1367. public function __clone() {
  1368. // On cloning, also clone the dependent objects. However, we do not
  1369. // want to clone the database connection object as that would duplicate the
  1370. // connection itself.
  1371. $this->where = clone($this->where);
  1372. $this->having = clone($this->having);
  1373. foreach ($this->union as $key => $aggregate) {
  1374. $this->union[$key]['query'] = clone($aggregate['query']);
  1375. }
  1376. }
  1377. }
  1378. /**
  1379. * @} End of "addtogroup database".
  1380. */