Skip navigation
Help

query.inc

  1. drupal
    1. 7 drupal/includes/database/query.inc
    2. 7 drupal/includes/database/mysql/query.inc
    3. 7 drupal/includes/database/sqlite/query.inc
    4. 7 drupal/includes/database/pgsql/query.inc

Non-specific Database query code. Used by all engines.

Classes

NameDescription
DatabaseConditionGeneric class for a series of conditions in a query.
DeleteQueryGeneral class for an abstracted DELETE operation.
InsertQueryGeneral class for an abstracted INSERT query.
MergeQueryGeneral class for an abstracted MERGE query operation.
QueryBase class for query builders.
TruncateQueryGeneral class for an abstracted TRUNCATE operation.
UpdateQueryGeneral class for an abstracted UPDATE operation.

Interfaces

NameDescription
QueryAlterableInterfaceInterface for a query that can be manipulated via an alter hook.
QueryConditionInterfaceInterface for a conditional clause in a query.
QueryPlaceholderInterfaceInterface for a query that accepts placeholders.

File

drupal/includes/database/query.inc
View source
  1. <?php
  2. /**
  3. * @ingroup database
  4. * @{
  5. */
  6. /**
  7. * @file
  8. * Non-specific Database query code. Used by all engines.
  9. */
  10. /**
  11. * Interface for a conditional clause in a query.
  12. */
  13. interface QueryConditionInterface {
  14. /**
  15. * Helper function: builds the most common conditional clauses.
  16. *
  17. * This method can take a variable number of parameters. If called with two
  18. * parameters, they are taken as $field and $value with $operator having a
  19. * value of IN if $value is an array and = otherwise.
  20. *
  21. * @param $field
  22. * The name of the field to check. If you would like to add a more complex
  23. * condition involving operators or functions, use where().
  24. * @param $value
  25. * The value to test the field against. In most cases, this is a scalar.
  26. * For more complex options, it is an array. The meaning of each element in
  27. * the array is dependent on the $operator.
  28. * @param $operator
  29. * The comparison operator, such as =, <, or >=. It also accepts more
  30. * complex options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is
  31. * an array, and = otherwise.
  32. *
  33. * @return QueryConditionInterface
  34. * The called object.
  35. */
  36. public function condition($field, $value = NULL, $operator = NULL);
  37. /**
  38. * Adds an arbitrary WHERE clause to the query.
  39. *
  40. * @param $snippet
  41. * A portion of a WHERE clause as a prepared statement. It must use named
  42. * placeholders, not ? placeholders.
  43. * @param $args
  44. * An associative array of arguments.
  45. *
  46. * @return QueryConditionInterface
  47. * The called object.
  48. */
  49. public function where($snippet, $args = array());
  50. /**
  51. * Sets a condition that the specified field be NULL.
  52. *
  53. * @param $field
  54. * The name of the field to check.
  55. *
  56. * @return QueryConditionInterface
  57. * The called object.
  58. */
  59. public function isNull($field);
  60. /**
  61. * Sets a condition that the specified field be NOT NULL.
  62. *
  63. * @param $field
  64. * The name of the field to check.
  65. *
  66. * @return QueryConditionInterface
  67. * The called object.
  68. */
  69. public function isNotNull($field);
  70. /**
  71. * Sets a condition that the specified subquery returns values.
  72. *
  73. * @param SelectQueryInterface $select
  74. * The subquery that must contain results.
  75. *
  76. * @return QueryConditionInterface
  77. * The called object.
  78. */
  79. public function exists(SelectQueryInterface $select);
  80. /**
  81. * Sets a condition that the specified subquery returns no values.
  82. *
  83. * @param SelectQueryInterface $select
  84. * The subquery that must not contain results.
  85. *
  86. * @return QueryConditionInterface
  87. * The called object.
  88. */
  89. public function notExists(SelectQueryInterface $select);
  90. /**
  91. * Gets a complete list of all conditions in this conditional clause.
  92. *
  93. * This method returns by reference. That allows alter hooks to access the
  94. * data structure directly and manipulate it before it gets compiled.
  95. *
  96. * The data structure that is returned is an indexed array of entries, where
  97. * each entry looks like the following:
  98. * @code
  99. * array(
  100. * 'field' => $field,
  101. * 'value' => $value,
  102. * 'operator' => $operator,
  103. * );
  104. * @endcode
  105. *
  106. * In the special case that $operator is NULL, the $field is taken as a raw
  107. * SQL snippet (possibly containing a function) and $value is an associative
  108. * array of placeholders for the snippet.
  109. *
  110. * There will also be a single array entry of #conjunction, which is the
  111. * conjunction that will be applied to the array, such as AND.
  112. */
  113. public function &conditions();
  114. /**
  115. * Gets a complete list of all values to insert into the prepared statement.
  116. *
  117. * @return
  118. * An associative array of placeholders and values.
  119. */
  120. public function arguments();
  121. /**
  122. * Compiles the saved conditions for later retrieval.
  123. *
  124. * This method does not return anything, but simply prepares data to be
  125. * retrieved via __toString() and arguments().
  126. *
  127. * @param $connection
  128. * The database connection for which to compile the conditionals.
  129. * @param $queryPlaceholder
  130. * The query this condition belongs to. If not given, the current query is
  131. * used.
  132. */
  133. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL);
  134. }
  135. /**
  136. * Interface for a query that can be manipulated via an alter hook.
  137. */
  138. interface QueryAlterableInterface {
  139. /**
  140. * Adds a tag to a query.
  141. *
  142. * Tags are strings that identify a query. A query may have any number of
  143. * tags. Tags are used to mark a query so that alter hooks may decide if they
  144. * wish to take action. Tags should be all lower-case and contain only
  145. * letters, numbers, and underscore, and start with a letter. That is, they
  146. * should follow the same rules as PHP identifiers in general.
  147. *
  148. * @param $tag
  149. * The tag to add.
  150. *
  151. * @return QueryAlterableInterface
  152. * The called object.
  153. */
  154. public function addTag($tag);
  155. /**
  156. * Determines if a given query has a given tag.
  157. *
  158. * @param $tag
  159. * The tag to check.
  160. *
  161. * @return
  162. * TRUE if this query has been marked with this tag, FALSE otherwise.
  163. */
  164. public function hasTag($tag);
  165. /**
  166. * Determines if a given query has all specified tags.
  167. *
  168. * @param $tags
  169. * A variable number of arguments, one for each tag to check.
  170. *
  171. * @return
  172. * TRUE if this query has been marked with all specified tags, FALSE
  173. * otherwise.
  174. */
  175. public function hasAllTags();
  176. /**
  177. * Determines if a given query has any specified tag.
  178. *
  179. * @param $tags
  180. * A variable number of arguments, one for each tag to check.
  181. *
  182. * @return
  183. * TRUE if this query has been marked with at least one of the specified
  184. * tags, FALSE otherwise.
  185. */
  186. public function hasAnyTag();
  187. /**
  188. * Adds additional metadata to the query.
  189. *
  190. * Often, a query may need to provide additional contextual data to alter
  191. * hooks. Alter hooks may then use that information to decide if and how
  192. * to take action.
  193. *
  194. * @param $key
  195. * The unique identifier for this piece of metadata. Must be a string that
  196. * follows the same rules as any other PHP identifier.
  197. * @param $object
  198. * The additional data to add to the query. May be any valid PHP variable.
  199. *
  200. * @return QueryAlterableInterface
  201. * The called object.
  202. */
  203. public function addMetaData($key, $object);
  204. /**
  205. * Retrieves a given piece of metadata.
  206. *
  207. * @param $key
  208. * The unique identifier for the piece of metadata to retrieve.
  209. *
  210. * @return
  211. * The previously attached metadata object, or NULL if one doesn't exist.
  212. */
  213. public function getMetaData($key);
  214. }
  215. /**
  216. * Interface for a query that accepts placeholders.
  217. */
  218. interface QueryPlaceholderInterface {
  219. /**
  220. * Returns the next placeholder ID for the query.
  221. *
  222. * @return
  223. * The next available placeholder ID as an integer.
  224. */
  225. function nextPlaceholder();
  226. }
  227. /**
  228. * Base class for query builders.
  229. *
  230. * Note that query builders use PHP's magic __toString() method to compile the
  231. * query object into a prepared statement.
  232. */
  233. abstract class Query implements QueryPlaceholderInterface {
  234. /**
  235. * The connection object on which to run this query.
  236. *
  237. * @var DatabaseConnection
  238. */
  239. protected $connection;
  240. /**
  241. * The target of the connection object.
  242. *
  243. * @var string
  244. */
  245. protected $connectionTarget;
  246. /**
  247. * The key of the connection object.
  248. *
  249. * @var string
  250. */
  251. protected $connectionKey;
  252. /**
  253. * The query options to pass on to the connection object.
  254. *
  255. * @var array
  256. */
  257. protected $queryOptions;
  258. /**
  259. * The placeholder counter.
  260. */
  261. protected $nextPlaceholder = 0;
  262. /**
  263. * An array of comments that can be prepended to a query.
  264. *
  265. * @var array
  266. */
  267. protected $comments = array();
  268. /**
  269. * Constructs a Query object.
  270. *
  271. * @param DatabaseConnection $connection
  272. * Database connection object.
  273. * @param array $options
  274. * Array of query options.
  275. */
  276. public function __construct(DatabaseConnection $connection, $options) {
  277. $this->connection = $connection;
  278. $this->connectionKey = $this->connection->getKey();
  279. $this->connectionTarget = $this->connection->getTarget();
  280. $this->queryOptions = $options;
  281. }
  282. /**
  283. * Implements the magic __sleep function to disconnect from the database.
  284. */
  285. public function __sleep() {
  286. $keys = get_object_vars($this);
  287. unset($keys['connection']);
  288. return array_keys($keys);
  289. }
  290. /**
  291. * Implements the magic __wakeup function to reconnect to the database.
  292. */
  293. public function __wakeup() {
  294. $this->connection = Database::getConnection($this->connectionTarget, $this->connectionKey);
  295. }
  296. /**
  297. * Runs the query against the database.
  298. */
  299. abstract protected function execute();
  300. /**
  301. * Implements PHP magic __toString method to convert the query to a string.
  302. *
  303. * The toString operation is how we compile a query object to a prepared
  304. * statement.
  305. *
  306. * @return
  307. * A prepared statement query string for this object.
  308. */
  309. abstract public function __toString();
  310. /**
  311. * Gets the next placeholder value for this query object.
  312. *
  313. * @return int
  314. * Next placeholder value.
  315. */
  316. public function nextPlaceholder() {
  317. return $this->nextPlaceholder++;
  318. }
  319. /**
  320. * Adds a comment to the query.
  321. *
  322. * By adding a comment to a query, you can more easily find it in your
  323. * query log or the list of active queries on an SQL server. This allows
  324. * for easier debugging and allows you to more easily find where a query
  325. * with a performance problem is being generated.
  326. *
  327. * The comment string will be sanitized to remove * / and other characters
  328. * that may terminate the string early so as to avoid SQL injection attacks.
  329. *
  330. * @param $comment
  331. * The comment string to be inserted into the query.
  332. *
  333. * @return Query
  334. * The called object.
  335. */
  336. public function comment($comment) {
  337. $this->comments[] = $comment;
  338. return $this;
  339. }
  340. /**
  341. * Returns a reference to the comments array for the query.
  342. *
  343. * Because this method returns by reference, alter hooks may edit the comments
  344. * array directly to make their changes. If just adding comments, however, the
  345. * use of comment() is preferred.
  346. *
  347. * Note that this method must be called by reference as well:
  348. * @code
  349. * $comments =& $query->getComments();
  350. * @endcode
  351. *
  352. * @return
  353. * A reference to the comments array structure.
  354. */
  355. public function &getComments() {
  356. return $this->comments;
  357. }
  358. }
  359. /**
  360. * General class for an abstracted INSERT query.
  361. */
  362. class InsertQuery extends Query {
  363. /**
  364. * The table on which to insert.
  365. *
  366. * @var string
  367. */
  368. protected $table;
  369. /**
  370. * An array of fields on which to insert.
  371. *
  372. * @var array
  373. */
  374. protected $insertFields = array();
  375. /**
  376. * An array of fields that should be set to their database-defined defaults.
  377. *
  378. * @var array
  379. */
  380. protected $defaultFields = array();
  381. /**
  382. * A nested array of values to insert.
  383. *
  384. * $insertValues is an array of arrays. Each sub-array is either an
  385. * associative array whose keys are field names and whose values are field
  386. * values to insert, or a non-associative array of values in the same order
  387. * as $insertFields.
  388. *
  389. * Whether multiple insert sets will be run in a single query or multiple
  390. * queries is left to individual drivers to implement in whatever manner is
  391. * most appropriate. The order of values in each sub-array must match the
  392. * order of fields in $insertFields.
  393. *
  394. * @var array
  395. */
  396. protected $insertValues = array();
  397. /**
  398. * A SelectQuery object to fetch the rows that should be inserted.
  399. *
  400. * @var SelectQueryInterface
  401. */
  402. protected $fromQuery;
  403. /**
  404. * Constructs an InsertQuery object.
  405. *
  406. * @param DatabaseConnection $connection
  407. * A DatabaseConnection object.
  408. * @param string $table
  409. * Name of the table to associate with this query.
  410. * @param array $options
  411. * Array of database options.
  412. */
  413. public function __construct($connection, $table, array $options = array()) {
  414. if (!isset($options['return'])) {
  415. $options['return'] = Database::RETURN_INSERT_ID;
  416. }
  417. parent::__construct($connection, $options);
  418. $this->table = $table;
  419. }
  420. /**
  421. * Adds a set of field->value pairs to be inserted.
  422. *
  423. * This method may only be called once. Calling it a second time will be
  424. * ignored. To queue up multiple sets of values to be inserted at once,
  425. * use the values() method.
  426. *
  427. * @param $fields
  428. * An array of fields on which to insert. This array may be indexed or
  429. * associative. If indexed, the array is taken to be the list of fields.
  430. * If associative, the keys of the array are taken to be the fields and
  431. * the values are taken to be corresponding values to insert. If a
  432. * $values argument is provided, $fields must be indexed.
  433. * @param $values
  434. * An array of fields to insert into the database. The values must be
  435. * specified in the same order as the $fields array.
  436. *
  437. * @return InsertQuery
  438. * The called object.
  439. */
  440. public function fields(array $fields, array $values = array()) {
  441. if (empty($this->insertFields)) {
  442. if (empty($values)) {
  443. if (!is_numeric(key($fields))) {
  444. $values = array_values($fields);
  445. $fields = array_keys($fields);
  446. }
  447. }
  448. $this->insertFields = $fields;
  449. if (!empty($values)) {
  450. $this->insertValues[] = $values;
  451. }
  452. }
  453. return $this;
  454. }
  455. /**
  456. * Adds another set of values to the query to be inserted.
  457. *
  458. * If $values is a numeric-keyed array, it will be assumed to be in the same
  459. * order as the original fields() call. If it is associative, it may be
  460. * in any order as long as the keys of the array match the names of the
  461. * fields.
  462. *
  463. * @param $values
  464. * An array of values to add to the query.
  465. *
  466. * @return InsertQuery
  467. * The called object.
  468. */
  469. public function values(array $values) {
  470. if (is_numeric(key($values))) {
  471. $this->insertValues[] = $values;
  472. }
  473. else {
  474. // Reorder the submitted values to match the fields array.
  475. foreach ($this->insertFields as $key) {
  476. $insert_values[$key] = $values[$key];
  477. }
  478. // For consistency, the values array is always numerically indexed.
  479. $this->insertValues[] = array_values($insert_values);
  480. }
  481. return $this;
  482. }
  483. /**
  484. * Specifies fields for which the database defaults should be used.
  485. *
  486. * If you want to force a given field to use the database-defined default,
  487. * not NULL or undefined, use this method to instruct the database to use
  488. * default values explicitly. In most cases this will not be necessary
  489. * unless you are inserting a row that is all default values, as you cannot
  490. * specify no values in an INSERT query.
  491. *
  492. * Specifying a field both in fields() and in useDefaults() is an error
  493. * and will not execute.
  494. *
  495. * @param $fields
  496. * An array of values for which to use the default values
  497. * specified in the table definition.
  498. *
  499. * @return InsertQuery
  500. * The called object.
  501. */
  502. public function useDefaults(array $fields) {
  503. $this->defaultFields = $fields;
  504. return $this;
  505. }
  506. /**
  507. * Sets the fromQuery on this InsertQuery object.
  508. *
  509. * @param SelectQueryInterface $query
  510. * The query to fetch the rows that should be inserted.
  511. *
  512. * @return InsertQuery
  513. * The called object.
  514. */
  515. public function from(SelectQueryInterface $query) {
  516. $this->fromQuery = $query;
  517. return $this;
  518. }
  519. /**
  520. * Executes the insert query.
  521. *
  522. * @return
  523. * The last insert ID of the query, if one exists. If the query
  524. * was given multiple sets of values to insert, the return value is
  525. * undefined. If no fields are specified, this method will do nothing and
  526. * return NULL. That makes it safe to use in multi-insert loops.
  527. */
  528. public function execute() {
  529. // If validation fails, simply return NULL. Note that validation routines
  530. // in preExecute() may throw exceptions instead.
  531. if (!$this->preExecute()) {
  532. return NULL;
  533. }
  534. // If we're selecting from a SelectQuery, finish building the query and
  535. // pass it back, as any remaining options are irrelevant.
  536. if (!empty($this->fromQuery)) {
  537. $sql = (string) $this;
  538. // The SelectQuery may contain arguments, load and pass them through.
  539. return $this->connection->query($sql, $this->fromQuery->getArguments(), $this->queryOptions);
  540. }
  541. $last_insert_id = 0;
  542. // Each insert happens in its own query in the degenerate case. However,
  543. // we wrap it in a transaction so that it is atomic where possible. On many
  544. // databases, such as SQLite, this is also a notable performance boost.
  545. $transaction = $this->connection->startTransaction();
  546. try {
  547. $sql = (string) $this;
  548. foreach ($this->insertValues as $insert_values) {
  549. $last_insert_id = $this->connection->query($sql, $insert_values, $this->queryOptions);
  550. }
  551. }
  552. catch (Exception $e) {
  553. // One of the INSERTs failed, rollback the whole batch.
  554. $transaction->rollback();
  555. // Rethrow the exception for the calling code.
  556. throw $e;
  557. }
  558. // Re-initialize the values array so that we can re-use this query.
  559. $this->insertValues = array();
  560. // Transaction commits here where $transaction looses scope.
  561. return $last_insert_id;
  562. }
  563. /**
  564. * Implements PHP magic __toString method to convert the query to a string.
  565. *
  566. * @return string
  567. * The prepared statement.
  568. */
  569. public function __toString() {
  570. // Create a sanitized comment string to prepend to the query.
  571. $comments = $this->connection->makeComment($this->comments);
  572. // Default fields are always placed first for consistency.
  573. $insert_fields = array_merge($this->defaultFields, $this->insertFields);
  574. if (!empty($this->fromQuery)) {
  575. return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery;
  576. }
  577. // For simplicity, we will use the $placeholders array to inject
  578. // default keywords even though they are not, strictly speaking,
  579. // placeholders for prepared statements.
  580. $placeholders = array();
  581. $placeholders = array_pad($placeholders, count($this->defaultFields), 'default');
  582. $placeholders = array_pad($placeholders, count($this->insertFields), '?');
  583. return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES (' . implode(', ', $placeholders) . ')';
  584. }
  585. /**
  586. * Preprocesses and validates the query.
  587. *
  588. * @return
  589. * TRUE if the validation was successful, FALSE if not.
  590. *
  591. * @throws FieldsOverlapException
  592. * @throws NoFieldsException
  593. */
  594. public function preExecute() {
  595. // Confirm that the user did not try to specify an identical
  596. // field and default field.
  597. if (array_intersect($this->insertFields, $this->defaultFields)) {
  598. throw new FieldsOverlapException('You may not specify the same field to have a value and a schema-default value.');
  599. }
  600. if (!empty($this->fromQuery)) {
  601. // We have to assume that the used aliases match the insert fields.
  602. // Regular fields are added to the query before expressions, maintain the
  603. // same order for the insert fields.
  604. // This behavior can be overridden by calling fields() manually as only the
  605. // first call to fields() does have an effect.
  606. $this->fields(array_merge(array_keys($this->fromQuery->getFields()), array_keys($this->fromQuery->getExpressions())));
  607. }
  608. // Don't execute query without fields.
  609. if (count($this->insertFields) + count($this->defaultFields) == 0) {
  610. throw new NoFieldsException('There are no fields available to insert with.');
  611. }
  612. // If no values have been added, silently ignore this query. This can happen
  613. // if values are added conditionally, so we don't want to throw an
  614. // exception.
  615. if (!isset($this->insertValues[0]) && count($this->insertFields) > 0 && empty($this->fromQuery)) {
  616. return FALSE;
  617. }
  618. return TRUE;
  619. }
  620. }
  621. /**
  622. * General class for an abstracted DELETE operation.
  623. */
  624. class DeleteQuery extends Query implements QueryConditionInterface {
  625. /**
  626. * The table from which to delete.
  627. *
  628. * @var string
  629. */
  630. protected $table;
  631. /**
  632. * The condition object for this query.
  633. *
  634. * Condition handling is handled via composition.
  635. *
  636. * @var DatabaseCondition
  637. */
  638. protected $condition;
  639. /**
  640. * Constructs a DeleteQuery object.
  641. *
  642. * @param DatabaseConnection $connection
  643. * A DatabaseConnection object.
  644. * @param string $table
  645. * Name of the table to associate with this query.
  646. * @param array $options
  647. * Array of database options.
  648. */
  649. public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
  650. $options['return'] = Database::RETURN_AFFECTED;
  651. parent::__construct($connection, $options);
  652. $this->table = $table;
  653. $this->condition = new DatabaseCondition('AND');
  654. }
  655. /**
  656. * Implements QueryConditionInterface::condition().
  657. */
  658. public function condition($field, $value = NULL, $operator = NULL) {
  659. $this->condition->condition($field, $value, $operator);
  660. return $this;
  661. }
  662. /**
  663. * Implements QueryConditionInterface::isNull().
  664. */
  665. public function isNull($field) {
  666. $this->condition->isNull($field);
  667. return $this;
  668. }
  669. /**
  670. * Implements QueryConditionInterface::isNotNull().
  671. */
  672. public function isNotNull($field) {
  673. $this->condition->isNotNull($field);
  674. return $this;
  675. }
  676. /**
  677. * Implements QueryConditionInterface::exists().
  678. */
  679. public function exists(SelectQueryInterface $select) {
  680. $this->condition->exists($select);
  681. return $this;
  682. }
  683. /**
  684. * Implements QueryConditionInterface::notExists().
  685. */
  686. public function notExists(SelectQueryInterface $select) {
  687. $this->condition->notExists($select);
  688. return $this;
  689. }
  690. /**
  691. * Implements QueryConditionInterface::conditions().
  692. */
  693. public function &conditions() {
  694. return $this->condition->conditions();
  695. }
  696. /**
  697. * Implements QueryConditionInterface::arguments().
  698. */
  699. public function arguments() {
  700. return $this->condition->arguments();
  701. }
  702. /**
  703. * Implements QueryConditionInterface::where().
  704. */
  705. public function where($snippet, $args = array()) {
  706. $this->condition->where($snippet, $args);
  707. return $this;
  708. }
  709. /**
  710. * Implements QueryConditionInterface::compile().
  711. */
  712. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
  713. return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
  714. }
  715. /**
  716. * Executes the DELETE query.
  717. *
  718. * @return
  719. * The return value is dependant on the database connection.
  720. */
  721. public function execute() {
  722. $values = array();
  723. if (count($this->condition)) {
  724. $this->condition->compile($this->connection, $this);
  725. $values = $this->condition->arguments();
  726. }
  727. return $this->connection->query((string) $this, $values, $this->queryOptions);
  728. }
  729. /**
  730. * Implements PHP magic __toString method to convert the query to a string.
  731. *
  732. * @return string
  733. * The prepared statement.
  734. */
  735. public function __toString() {
  736. // Create a sanitized comment string to prepend to the query.
  737. $comments = $this->connection->makeComment($this->comments);
  738. $query = $comments . 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '} ';
  739. if (count($this->condition)) {
  740. $this->condition->compile($this->connection, $this);
  741. $query .= "\nWHERE " . $this->condition;
  742. }
  743. return $query;
  744. }
  745. }
  746. /**
  747. * General class for an abstracted TRUNCATE operation.
  748. */
  749. class TruncateQuery extends Query {
  750. /**
  751. * The table to truncate.
  752. *
  753. * @var string
  754. */
  755. protected $table;
  756. /**
  757. * Constructs a TruncateQuery object.
  758. *
  759. * @param DatabaseConnection $connection
  760. * A DatabaseConnection object.
  761. * @param string $table
  762. * Name of the table to associate with this query.
  763. * @param array $options
  764. * Array of database options.
  765. */
  766. public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
  767. $options['return'] = Database::RETURN_AFFECTED;
  768. parent::__construct($connection, $options);
  769. $this->table = $table;
  770. }
  771. /**
  772. * Implements QueryConditionInterface::compile().
  773. */
  774. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
  775. return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
  776. }
  777. /**
  778. * Executes the TRUNCATE query.
  779. *
  780. * @return
  781. * Return value is dependent on the database type.
  782. */
  783. public function execute() {
  784. return $this->connection->query((string) $this, array(), $this->queryOptions);
  785. }
  786. /**
  787. * Implements PHP magic __toString method to convert the query to a string.
  788. *
  789. * @return string
  790. * The prepared statement.
  791. */
  792. public function __toString() {
  793. // Create a sanitized comment string to prepend to the query.
  794. $comments = $this->connection->makeComment($this->comments);
  795. return $comments . 'TRUNCATE {' . $this->connection->escapeTable($this->table) . '} ';
  796. }
  797. }
  798. /**
  799. * General class for an abstracted UPDATE operation.
  800. */
  801. class UpdateQuery extends Query implements QueryConditionInterface {
  802. /**
  803. * The table to update.
  804. *
  805. * @var string
  806. */
  807. protected $table;
  808. /**
  809. * An array of fields that will be updated.
  810. *
  811. * @var array
  812. */
  813. protected $fields = array();
  814. /**
  815. * An array of values to update to.
  816. *
  817. * @var array
  818. */
  819. protected $arguments = array();
  820. /**
  821. * The condition object for this query.
  822. *
  823. * Condition handling is handled via composition.
  824. *
  825. * @var DatabaseCondition
  826. */
  827. protected $condition;
  828. /**
  829. * Array of fields to update to an expression in case of a duplicate record.
  830. *
  831. * This variable is a nested array in the following format:
  832. * @code
  833. * <some field> => array(
  834. * 'condition' => <condition to execute, as a string>,
  835. * 'arguments' => <array of arguments for condition, or NULL for none>,
  836. * );
  837. * @endcode
  838. *
  839. * @var array
  840. */
  841. protected $expressionFields = array();
  842. /**
  843. * Constructs an UpdateQuery object.
  844. *
  845. * @param DatabaseConnection $connection
  846. * A DatabaseConnection object.
  847. * @param string $table
  848. * Name of the table to associate with this query.
  849. * @param array $options
  850. * Array of database options.
  851. */
  852. public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
  853. $options['return'] = Database::RETURN_AFFECTED;
  854. parent::__construct($connection, $options);
  855. $this->table = $table;
  856. $this->condition = new DatabaseCondition('AND');
  857. }
  858. /**
  859. * Implements QueryConditionInterface::condition().
  860. */
  861. public function condition($field, $value = NULL, $operator = NULL) {
  862. $this->condition->condition($field, $value, $operator);
  863. return $this;
  864. }
  865. /**
  866. * Implements QueryConditionInterface::isNull().
  867. */
  868. public function isNull($field) {
  869. $this->condition->isNull($field);
  870. return $this;
  871. }
  872. /**
  873. * Implements QueryConditionInterface::isNotNull().
  874. */
  875. public function isNotNull($field) {
  876. $this->condition->isNotNull($field);
  877. return $this;
  878. }
  879. /**
  880. * Implements QueryConditionInterface::exists().
  881. */
  882. public function exists(SelectQueryInterface $select) {
  883. $this->condition->exists($select);
  884. return $this;
  885. }
  886. /**
  887. * Implements QueryConditionInterface::notExists().
  888. */
  889. public function notExists(SelectQueryInterface $select) {
  890. $this->condition->notExists($select);
  891. return $this;
  892. }
  893. /**
  894. * Implements QueryConditionInterface::conditions().
  895. */
  896. public function &conditions() {
  897. return $this->condition->conditions();
  898. }
  899. /**
  900. * Implements QueryConditionInterface::arguments().
  901. */
  902. public function arguments() {
  903. return $this->condition->arguments();
  904. }
  905. /**
  906. * Implements QueryConditionInterface::where().
  907. */
  908. public function where($snippet, $args = array()) {
  909. $this->condition->where($snippet, $args);
  910. return $this;
  911. }
  912. /**
  913. * Implements QueryConditionInterface::compile().
  914. */
  915. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
  916. return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
  917. }
  918. /**
  919. * Adds a set of field->value pairs to be updated.
  920. *
  921. * @param $fields
  922. * An associative array of fields to write into the database. The array keys
  923. * are the field names and the values are the values to which to set them.
  924. *
  925. * @return UpdateQuery
  926. * The called object.
  927. */
  928. public function fields(array $fields) {
  929. $this->fields = $fields;
  930. return $this;
  931. }
  932. /**
  933. * Specifies fields to be updated as an expression.
  934. *
  935. * Expression fields are cases such as counter=counter+1. This method takes
  936. * precedence over fields().
  937. *
  938. * @param $field
  939. * The field to set.
  940. * @param $expression
  941. * The field will be set to the value of this expression. This parameter
  942. * may include named placeholders.
  943. * @param $arguments
  944. * If specified, this is an array of key/value pairs for named placeholders
  945. * corresponding to the expression.
  946. *
  947. * @return UpdateQuery
  948. * The called object.
  949. */
  950. public function expression($field, $expression, array $arguments = NULL) {
  951. $this->expressionFields[$field] = array(
  952. 'expression' => $expression,
  953. 'arguments' => $arguments,
  954. );
  955. return $this;
  956. }
  957. /**
  958. * Executes the UPDATE query.
  959. *
  960. * @return
  961. * The number of rows affected by the update.
  962. */
  963. public function execute() {
  964. // Expressions take priority over literal fields, so we process those first
  965. // and remove any literal fields that conflict.
  966. $fields = $this->fields;
  967. $update_values = array();
  968. foreach ($this->expressionFields as $field => $data) {
  969. if (!empty($data['arguments'])) {
  970. $update_values += $data['arguments'];
  971. }
  972. unset($fields[$field]);
  973. }
  974. // Because we filter $fields the same way here and in __toString(), the
  975. // placeholders will all match up properly.
  976. $max_placeholder = 0;
  977. foreach ($fields as $field => $value) {
  978. $update_values[':db_update_placeholder_' . ($max_placeholder++)] = $value;
  979. }
  980. if (count($this->condition)) {
  981. $this->condition->compile($this->connection, $this);
  982. $update_values = array_merge($update_values, $this->condition->arguments());
  983. }
  984. return $this->connection->query((string) $this, $update_values, $this->queryOptions);
  985. }
  986. /**
  987. * Implements PHP magic __toString method to convert the query to a string.
  988. *
  989. * @return string
  990. * The prepared statement.
  991. */
  992. public function __toString() {
  993. // Create a sanitized comment string to prepend to the query.
  994. $comments = $this->connection->makeComment($this->comments);
  995. // Expressions take priority over literal fields, so we process those first
  996. // and remove any literal fields that conflict.
  997. $fields = $this->fields;
  998. $update_fields = array();
  999. foreach ($this->expressionFields as $field => $data) {
  1000. $update_fields[] = $field . '=' . $data['expression'];
  1001. unset($fields[$field]);
  1002. }
  1003. $max_placeholder = 0;
  1004. foreach ($fields as $field => $value) {
  1005. $update_fields[] = $field . '=:db_update_placeholder_' . ($max_placeholder++);
  1006. }
  1007. $query = $comments . 'UPDATE {' . $this->connection->escapeTable($this->table) . '} SET ' . implode(', ', $update_fields);
  1008. if (count($this->condition)) {
  1009. $this->condition->compile($this->connection, $this);
  1010. // There is an implicit string cast on $this->condition.
  1011. $query .= "\nWHERE " . $this->condition;
  1012. }
  1013. return $query;
  1014. }
  1015. }
  1016. /**
  1017. * General class for an abstracted MERGE query operation.
  1018. *
  1019. * An ANSI SQL:2003 compatible database would run the following query:
  1020. *
  1021. * @code
  1022. * MERGE INTO table_name_1 USING table_name_2 ON (condition)
  1023. * WHEN MATCHED THEN
  1024. * UPDATE SET column1 = value1 [, column2 = value2 ...]
  1025. * WHEN NOT MATCHED THEN
  1026. * INSERT (column1 [, column2 ...]) VALUES (value1 [, value2 ...
  1027. * @endcode
  1028. *
  1029. * Other databases (most notably MySQL, PostgreSQL and SQLite) will emulate
  1030. * this statement by running a SELECT and then INSERT or UPDATE.
  1031. *
  1032. * By default, the two table names are identical and they are passed into the
  1033. * the constructor. table_name_2 can be specified by the
  1034. * MergeQuery::conditionTable() method. It can be either a string or a
  1035. * subquery.
  1036. *
  1037. * The condition is built exactly like SelectQuery or UpdateQuery conditions,
  1038. * the UPDATE query part is built similarly like an UpdateQuery and finally the
  1039. * INSERT query part is built similarly like an InsertQuery. However, both
  1040. * UpdateQuery and InsertQuery has a fields method so
  1041. * MergeQuery::updateFields() and MergeQuery::insertFields() needs to be called
  1042. * instead. MergeQuery::fields() can also be called which calls both of these
  1043. * methods as the common case is to use the same column-value pairs for both
  1044. * INSERT and UPDATE. However, this is not mandatory. Another convinient
  1045. * wrapper is MergeQuery::key() which adds the same column-value pairs to the
  1046. * condition and the INSERT query part.
  1047. *
  1048. * Several methods (key(), fields(), insertFields()) can be called to set a
  1049. * key-value pair for the INSERT query part. Subsequent calls for the same
  1050. * fields override the earlier ones. The same is true for UPDATE and key(),
  1051. * fields() and updateFields().
  1052. */
  1053. class MergeQuery extends Query implements QueryConditionInterface {
  1054. /**
  1055. * Returned by execute() if an INSERT query has been executed.
  1056. */
  1057. const STATUS_INSERT = 1;
  1058. /**
  1059. * Returned by execute() if an UPDATE query has been executed.
  1060. */
  1061. const STATUS_UPDATE = 2;
  1062. /**
  1063. * The table to be used for INSERT and UPDATE.
  1064. *
  1065. * @var string
  1066. */
  1067. protected $table;
  1068. /**
  1069. * The table or subquery to be used for the condition.
  1070. */
  1071. protected $conditionTable;
  1072. /**
  1073. * An array of fields on which to insert.
  1074. *
  1075. * @var array
  1076. */
  1077. protected $insertFields = array();
  1078. /**
  1079. * An array of fields which should be set to their database-defined defaults.
  1080. *
  1081. * Used on INSERT.
  1082. *
  1083. * @var array
  1084. */
  1085. protected $defaultFields = array();
  1086. /**
  1087. * An array of values to be inserted.
  1088. *
  1089. * @var string
  1090. */
  1091. protected $insertValues = array();
  1092. /**
  1093. * An array of fields that will be updated.
  1094. *
  1095. * @var array
  1096. */
  1097. protected $updateFields = array();
  1098. /**
  1099. * Array of fields to update to an expression in case of a duplicate record.
  1100. *
  1101. * This variable is a nested array in the following format:
  1102. * @code
  1103. * <some field> => array(
  1104. * 'condition' => <condition to execute, as a string>,
  1105. * 'arguments' => <array of arguments for condition, or NULL for none>,
  1106. * );
  1107. * @endcode
  1108. *
  1109. * @var array
  1110. */
  1111. protected $expressionFields = array();
  1112. /**
  1113. * Flag indicating whether an UPDATE is necessary.
  1114. *
  1115. * @var boolean
  1116. */
  1117. protected $needsUpdate = FALSE;
  1118. /**
  1119. * Constructs a MergeQuery object.
  1120. *
  1121. * @param DatabaseConnection $connection
  1122. * A DatabaseConnection object.
  1123. * @param string $table
  1124. * Name of the table to associate with this query.
  1125. * @param array $options
  1126. * Array of database options.
  1127. */
  1128. public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
  1129. $options['return'] = Database::RETURN_AFFECTED;
  1130. parent::__construct($connection, $options);
  1131. $this->table = $table;
  1132. $this->conditionTable = $table;
  1133. $this->condition = new DatabaseCondition('AND');
  1134. }
  1135. /**
  1136. * Sets the table or subquery to be used for the condition.
  1137. *
  1138. * @param $table
  1139. * The table name or the subquery to be used. Use a SelectQuery object to
  1140. * pass in a subquery.
  1141. *
  1142. * @return MergeQuery
  1143. * The called object.
  1144. */
  1145. protected function conditionTable($table) {
  1146. $this->conditionTable = $table;
  1147. return $this;
  1148. }
  1149. /**
  1150. * Adds a set of field->value pairs to be updated.
  1151. *
  1152. * @param $fields
  1153. * An associative array of fields to write into the database. The array keys
  1154. * are the field names and the values are the values to which to set them.
  1155. *
  1156. * @return MergeQuery
  1157. * The called object.
  1158. */
  1159. public function updateFields(array $fields) {
  1160. $this->updateFields = $fields;
  1161. $this->needsUpdate = TRUE;
  1162. return $this;
  1163. }
  1164. /**
  1165. * Specifies fields to be updated as an expression.
  1166. *
  1167. * Expression fields are cases such as counter = counter + 1. This method
  1168. * takes precedence over MergeQuery::updateFields() and it's wrappers,
  1169. * MergeQuery::key() and MergeQuery::fields().
  1170. *
  1171. * @param $field
  1172. * The field to set.
  1173. * @param $expression
  1174. * The field will be set to the value of this expression. This parameter
  1175. * may include named placeholders.
  1176. * @param $arguments
  1177. * If specified, this is an array of key/value pairs for named placeholders
  1178. * corresponding to the expression.
  1179. *
  1180. * @return MergeQuery
  1181. * The called object.
  1182. */
  1183. public function expression($field, $expression, array $arguments = NULL) {
  1184. $this->expressionFields[$field] = array(
  1185. 'expression' => $expression,
  1186. 'arguments' => $arguments,
  1187. );
  1188. $this->needsUpdate = TRUE;
  1189. return $this;
  1190. }
  1191. /**
  1192. * Adds a set of field->value pairs to be inserted.
  1193. *
  1194. * @param $fields
  1195. * An array of fields on which to insert. This array may be indexed or
  1196. * associative. If indexed, the array is taken to be the list of fields.
  1197. * If associative, the keys of the array are taken to be the fields and
  1198. * the values are taken to be corresponding values to insert. If a
  1199. * $values argument is provided, $fields must be indexed.
  1200. * @param $values
  1201. * An array of fields to insert into the database. The values must be
  1202. * specified in the same order as the $fields array.
  1203. *
  1204. * @return MergeQuery
  1205. * The called object.
  1206. */
  1207. public function insertFields(array $fields, array $values = array()) {
  1208. if ($values) {
  1209. $fields = array_combine($fields, $values);
  1210. }
  1211. $this->insertFields = $fields;
  1212. return $this;
  1213. }
  1214. /**
  1215. * Specifies fields for which the database-defaults should be used.
  1216. *
  1217. * If you want to force a given field to use the database-defined default,
  1218. * not NULL or undefined, use this method to instruct the database to use
  1219. * default values explicitly. In most cases this will not be necessary
  1220. * unless you are inserting a row that is all default values, as you cannot
  1221. * specify no values in an INSERT query.
  1222. *
  1223. * Specifying a field both in fields() and in useDefaults() is an error
  1224. * and will not execute.
  1225. *
  1226. * @param $fields
  1227. * An array of values for which to use the default values
  1228. * specified in the table definition.
  1229. *
  1230. * @return MergeQuery
  1231. * The called object.
  1232. */
  1233. public function useDefaults(array $fields) {
  1234. $this->defaultFields = $fields;
  1235. return $this;
  1236. }
  1237. /**
  1238. * Sets common field-value pairs in the INSERT and UPDATE query parts.
  1239. *
  1240. * This method should only be called once. It may be called either
  1241. * with a single associative array or two indexed arrays. If called
  1242. * with an associative array, the keys are taken to be the fields
  1243. * and the values are taken to be the corresponding values to set.
  1244. * If called with two arrays, the first array is taken as the fields
  1245. * and the second array is taken as the corresponding values.
  1246. *
  1247. * @param $fields
  1248. * An array of fields to insert, or an associative array of fields and
  1249. * values. The keys of the array are taken to be the fields and the values
  1250. * are taken to be corresponding values to insert.
  1251. * @param $values
  1252. * An array of values to set into the database. The values must be
  1253. * specified in the same order as the $fields array.
  1254. *
  1255. * @return MergeQuery
  1256. * The called object.
  1257. */
  1258. public function fields(array $fields, array $values = array()) {
  1259. if ($values) {
  1260. $fields = array_combine($fields, $values);
  1261. }
  1262. foreach ($fields as $key => $value) {
  1263. $this->insertFields[$key] = $value;
  1264. $this->updateFields[$key] = $value;
  1265. }
  1266. $this->needsUpdate = TRUE;
  1267. return $this;
  1268. }
  1269. /**
  1270. * Sets the key field(s) to be used as conditions for this query.
  1271. *
  1272. * This method should only be called once. It may be called either
  1273. * with a single associative array or two indexed arrays. If called
  1274. * with an associative array, the keys are taken to be the fields
  1275. * and the values are taken to be the corresponding values to set.
  1276. * If called with two arrays, the first array is taken as the fields
  1277. * and the second array is taken as the corresponding values.
  1278. *
  1279. * The fields are copied to the condition of the query and the INSERT part.
  1280. * If no other method is called, the UPDATE will become a no-op.
  1281. *
  1282. * @param $fields
  1283. * An array of fields to set, or an associative array of fields and values.
  1284. * @param $values
  1285. * An array of values to set into the database. The values must be
  1286. * specified in the same order as the $fields array.
  1287. *
  1288. * @return MergeQuery
  1289. * The called object.
  1290. */
  1291. public function key(array $fields, array $values = array()) {
  1292. if ($values) {
  1293. $fields = array_combine($fields, $values);
  1294. }
  1295. foreach ($fields as $key => $value) {
  1296. $this->insertFields[$key] = $value;
  1297. $this->condition($key, $value);
  1298. }
  1299. return $this;
  1300. }
  1301. /**
  1302. * Implements QueryConditionInterface::condition().
  1303. */
  1304. public function condition($field, $value = NULL, $operator = NULL) {
  1305. $this->condition->condition($field, $value, $operator);
  1306. return $this;
  1307. }
  1308. /**
  1309. * Implements QueryConditionInterface::isNull().
  1310. */
  1311. public function isNull($field) {
  1312. $this->condition->isNull($field);
  1313. return $this;
  1314. }
  1315. /**
  1316. * Implements QueryConditionInterface::isNotNull().
  1317. */
  1318. public function isNotNull($field) {
  1319. $this->condition->isNotNull($field);
  1320. return $this;
  1321. }
  1322. /**
  1323. * Implements QueryConditionInterface::exists().
  1324. */
  1325. public function exists(SelectQueryInterface $select) {
  1326. $this->condition->exists($select);
  1327. return $this;
  1328. }
  1329. /**
  1330. * Implements QueryConditionInterface::notExists().
  1331. */
  1332. public function notExists(SelectQueryInterface $select) {
  1333. $this->condition->notExists($select);
  1334. return $this;
  1335. }
  1336. /**
  1337. * Implements QueryConditionInterface::conditions().
  1338. */
  1339. public function &conditions() {
  1340. return $this->condition->conditions();
  1341. }
  1342. /**
  1343. * Implements QueryConditionInterface::arguments().
  1344. */
  1345. public function arguments() {
  1346. return $this->condition->arguments();
  1347. }
  1348. /**
  1349. * Implements QueryConditionInterface::where().
  1350. */
  1351. public function where($snippet, $args = array()) {
  1352. $this->condition->where($snippet, $args);
  1353. return $this;
  1354. }
  1355. /**
  1356. * Implements QueryConditionInterface::compile().
  1357. */
  1358. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
  1359. return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
  1360. }
  1361. /**
  1362. * Implements PHP magic __toString method to convert the query to a string.
  1363. *
  1364. * In the degenerate case, there is no string-able query as this operation
  1365. * is potentially two queries.
  1366. *
  1367. * @return string
  1368. * The prepared query statement.
  1369. */
  1370. public function __toString() {
  1371. }
  1372. public function execute() {
  1373. // Wrap multiple queries in a transaction, if the database supports it.
  1374. $transaction = $this->connection->startTransaction();
  1375. try {
  1376. if (!count($this->condition)) {
  1377. throw new InvalidMergeQueryException(t('Invalid merge query: no conditions'));
  1378. }
  1379. $select = $this->connection->select($this->conditionTable)
  1380. ->condition($this->condition)
  1381. ->forUpdate();
  1382. $select->addExpression('1');
  1383. if (!$select->execute()->fetchField()) {
  1384. try {
  1385. $insert = $this->connection->insert($this->table)->fields($this->insertFields);
  1386. if ($this->defaultFields) {
  1387. $insert->useDefaults($this->defaultFields);
  1388. }
  1389. $insert->execute();
  1390. return MergeQuery::STATUS_INSERT;
  1391. }
  1392. catch (Exception $e) {
  1393. // The insert query failed, maybe it's because a racing insert query
  1394. // beat us in inserting the same row. Retry the select query, if it
  1395. // returns a row, ignore the error and continue with the update
  1396. // query below.
  1397. if (!$select->execute()->fetchField()) {
  1398. throw $e;
  1399. }
  1400. }
  1401. }
  1402. if ($this->needsUpdate) {
  1403. $update = $this->connection->update($this->table)
  1404. ->fields($this->updateFields)
  1405. ->condition($this->condition);
  1406. if ($this->expressionFields) {
  1407. foreach ($this->expressionFields as $field => $data) {
  1408. $update->expression($field, $data['expression'], $data['arguments']);
  1409. }
  1410. }
  1411. $update->execute();
  1412. return MergeQuery::STATUS_UPDATE;
  1413. }
  1414. }
  1415. catch (Exception $e) {
  1416. // Something really wrong happened here, bubble up the exception to the
  1417. // caller.
  1418. $transaction->rollback();
  1419. throw $e;
  1420. }
  1421. // Transaction commits here where $transaction looses scope.
  1422. }
  1423. }
  1424. /**
  1425. * Generic class for a series of conditions in a query.
  1426. */
  1427. class DatabaseCondition implements QueryConditionInterface, Countable {
  1428. /**
  1429. * Array of conditions.
  1430. *
  1431. * @var array
  1432. */
  1433. protected $conditions = array();
  1434. /**
  1435. * Array of arguments.
  1436. *
  1437. * @var array
  1438. */
  1439. protected $arguments = array();
  1440. /**
  1441. * Whether the conditions have been changed.
  1442. *
  1443. * TRUE if the condition has been changed since the last compile.
  1444. * FALSE if the condition has been compiled and not changed.
  1445. *
  1446. * @var bool
  1447. */
  1448. protected $changed = TRUE;
  1449. /**
  1450. * Constructs a DataBaseCondition object.
  1451. *
  1452. * @param string $conjunction
  1453. * The operator to use to combine conditions: 'AND' or 'OR'.
  1454. */
  1455. public function __construct($conjunction) {
  1456. $this->conditions['#conjunction'] = $conjunction;
  1457. }
  1458. /**
  1459. * Implements Countable::count().
  1460. *
  1461. * Returns the size of this conditional. The size of the conditional is the
  1462. * size of its conditional array minus one, because one element is the the
  1463. * conjunction.
  1464. */
  1465. public function count() {
  1466. return count($this->conditions) - 1;
  1467. }
  1468. /**
  1469. * Implements QueryConditionInterface::condition().
  1470. */
  1471. public function condition($field, $value = NULL, $operator = NULL) {
  1472. if (!isset($operator)) {
  1473. if (is_array($value)) {
  1474. $operator = 'IN';
  1475. }
  1476. elseif (!isset($value)) {
  1477. $operator = 'IS NULL';
  1478. }
  1479. else {
  1480. $operator = '=';
  1481. }
  1482. }
  1483. $this->conditions[] = array(
  1484. 'field' => $field,
  1485. 'value' => $value,
  1486. 'operator' => $operator,
  1487. );
  1488. $this->changed = TRUE;
  1489. return $this;
  1490. }
  1491. /**
  1492. * Implements QueryConditionInterface::where().
  1493. */
  1494. public function where($snippet, $args = array()) {
  1495. $this->conditions[] = array(
  1496. 'field' => $snippet,
  1497. 'value' => $args,
  1498. 'operator' => NULL,
  1499. );
  1500. $this->changed = TRUE;
  1501. return $this;
  1502. }
  1503. /**
  1504. * Implements QueryConditionInterface::isNull().
  1505. */
  1506. public function isNull($field) {
  1507. return $this->condition($field);
  1508. }
  1509. /**
  1510. * Implements QueryConditionInterface::isNotNull().
  1511. */
  1512. public function isNotNull($field) {
  1513. return $this->condition($field, NULL, 'IS NOT NULL');
  1514. }
  1515. /**
  1516. * Implements QueryConditionInterface::exists().
  1517. */
  1518. public function exists(SelectQueryInterface $select) {
  1519. return $this->condition('', $select, 'EXISTS');
  1520. }
  1521. /**
  1522. * Implements QueryConditionInterface::notExists().
  1523. */
  1524. public function notExists(SelectQueryInterface $select) {
  1525. return $this->condition('', $select, 'NOT EXISTS');
  1526. }
  1527. /**
  1528. * Implements QueryConditionInterface::conditions().
  1529. */
  1530. public function &conditions() {
  1531. return $this->conditions;
  1532. }
  1533. /**
  1534. * Implements QueryConditionInterface::arguments().
  1535. */
  1536. public function arguments() {
  1537. // If the caller forgot to call compile() first, refuse to run.
  1538. if ($this->changed) {
  1539. return NULL;
  1540. }
  1541. return $this->arguments;
  1542. }
  1543. /**
  1544. * Implements QueryConditionInterface::compile().
  1545. */
  1546. public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
  1547. if ($this->changed) {
  1548. $condition_fragments = array();
  1549. $arguments = array();
  1550. $conditions = $this->conditions;
  1551. $conjunction = $conditions['#conjunction'];
  1552. unset($conditions['#conjunction']);
  1553. foreach ($conditions as $condition) {
  1554. if (empty($condition['operator'])) {
  1555. // This condition is a literal string, so let it through as is.
  1556. $condition_fragments[] = ' (' . $condition['field'] . ') ';
  1557. $arguments += $condition['value'];
  1558. }
  1559. else {
  1560. // It's a structured condition, so parse it out accordingly.
  1561. // Note that $condition['field'] will only be an object for a dependent
  1562. // DatabaseCondition object, not for a dependent subquery.
  1563. if ($condition['field'] instanceof QueryConditionInterface) {
  1564. // Compile the sub-condition recursively and add it to the list.
  1565. $condition['field']->compile($connection, $queryPlaceholder);
  1566. $condition_fragments[] = '(' . (string) $condition['field'] . ')';
  1567. $arguments += $condition['field']->arguments();
  1568. }
  1569. else {
  1570. // For simplicity, we treat all operators as the same data structure.
  1571. // In the typical degenerate case, this won't get changed.
  1572. $operator_defaults = array(
  1573. 'prefix' => '',
  1574. 'postfix' => '',
  1575. 'delimiter' => '',
  1576. 'operator' => $condition['operator'],
  1577. 'use_value' => TRUE,
  1578. );
  1579. $operator = $connection->mapConditionOperator($condition['operator']);
  1580. if (!isset($operator)) {
  1581. $operator = $this->mapConditionOperator($condition['operator']);
  1582. }
  1583. $operator += $operator_defaults;
  1584. $placeholders = array();
  1585. if ($condition['value'] instanceof SelectQueryInterface) {
  1586. $condition['value']->compile($connection, $queryPlaceholder);
  1587. $placeholders[] = (string) $condition['value'];
  1588. $arguments += $condition['value']->arguments();
  1589. // Subqueries are the actual value of the operator, we don't
  1590. // need to add another below.
  1591. $operator['use_value'] = FALSE;
  1592. }
  1593. // We assume that if there is a delimiter, then the value is an
  1594. // array. If not, it is a scalar. For simplicity, we first convert
  1595. // up to an array so that we can build the placeholders in the same way.
  1596. elseif (!$operator['delimiter']) {
  1597. $condition['value'] = array($condition['value']);
  1598. }
  1599. if ($operator['use_value']) {
  1600. foreach ($condition['value'] as $value) {
  1601. $placeholder = ':db_condition_placeholder_' . $queryPlaceholder->nextPlaceholder();
  1602. $arguments[$placeholder] = $value;
  1603. $placeholders[] = $placeholder;
  1604. }
  1605. }
  1606. $condition_fragments[] = ' (' . $connection->escapeField($condition['field']) . ' ' . $operator['operator'] . ' ' . $operator['prefix'] . implode($operator['delimiter'], $placeholders) . $operator['postfix'] . ') ';
  1607. }
  1608. }
  1609. }
  1610. $this->changed = FALSE;
  1611. $this->stringVersion = implode($conjunction, $condition_fragments);
  1612. $this->arguments = $arguments;
  1613. }
  1614. }
  1615. /**
  1616. * Implements PHP magic __toString method to convert the conditions to string.
  1617. *
  1618. * @return string
  1619. * A string version of the conditions.
  1620. */
  1621. public function __toString() {
  1622. // If the caller forgot to call compile() first, refuse to run.
  1623. if ($this->changed) {
  1624. return NULL;
  1625. }
  1626. return $this->stringVersion;
  1627. }
  1628. /**
  1629. * PHP magic __clone() method.
  1630. *
  1631. * Only copies fields that implement QueryConditionInterface. Also sets
  1632. * $this->changed to TRUE.
  1633. */
  1634. function __clone() {
  1635. $this->changed = TRUE;
  1636. foreach ($this->conditions as $key => $condition) {
  1637. if ($condition['field'] instanceOf QueryConditionInterface) {
  1638. $this->conditions[$key]['field'] = clone($condition['field']);
  1639. }
  1640. }
  1641. }
  1642. /**
  1643. * Gets any special processing requirements for the condition operator.
  1644. *
  1645. * Some condition types require special processing, such as IN, because
  1646. * the value data they pass in is not a simple value. This is a simple
  1647. * overridable lookup function.
  1648. *
  1649. * @param $operator
  1650. * The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
  1651. *
  1652. * @return
  1653. * The extra handling directives for the specified operator, or NULL.
  1654. */
  1655. protected function mapConditionOperator($operator) {
  1656. // $specials does not use drupal_static as its value never changes.
  1657. static $specials = array(
  1658. 'BETWEEN' => array('delimiter' => ' AND '),
  1659. 'IN' => array('delimiter' => ', ', 'prefix' => ' (', 'postfix' => ')'),
  1660. 'NOT IN' => array('delimiter' => ', ', 'prefix' => ' (', 'postfix' => ')'),
  1661. 'EXISTS' => array('prefix' => ' (', 'postfix' => ')'),
  1662. 'NOT EXISTS' => array('prefix' => ' (', 'postfix' => ')'),
  1663. 'IS NULL' => array('use_value' => FALSE),
  1664. 'IS NOT NULL' => array('use_value' => FALSE),
  1665. // Use backslash for escaping wildcard characters.
  1666. 'LIKE' => array('postfix' => " ESCAPE '\\\\'"),
  1667. 'NOT LIKE' => array('postfix' => " ESCAPE '\\\\'"),
  1668. // These ones are here for performance reasons.
  1669. '=' => array(),
  1670. '<' => array(),
  1671. '>' => array(),
  1672. '>=' => array(),
  1673. '<=' => array(),
  1674. );
  1675. if (isset($specials[$operator])) {
  1676. $return = $specials[$operator];
  1677. }
  1678. else {
  1679. // We need to upper case because PHP index matches are case sensitive but
  1680. // do not need the more expensive drupal_strtoupper because SQL statements are ASCII.
  1681. $operator = strtoupper($operator);
  1682. $return = isset($specials[$operator]) ? $specials[$operator] : array();
  1683. }
  1684. $return += array('operator' => $operator);
  1685. return $return;
  1686. }
  1687. }
  1688. /**
  1689. * @} End of "ingroup database".
  1690. */