www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Database/Query/Query.php

   1 <?php
   2
   3 namespace Drupal\Core\Database\Query;
   4
   5 use Drupal\Core\Database\Database;
   6 use Drupal\Core\Database\Connection;
   7
   8 /**
   9  * Base class for query builders.
  10  *
  11  * Note that query builders use PHP's magic __toString() method to compile the
  12  * query object into a prepared statement.
  13  */
  14 abstract class Query implements PlaceholderInterface {
  15
  16   /**
  17    * The connection object on which to run this query.
  18    *
  19    * @var \Drupal\Core\Database\Connection
  20    */
  21   protected $connection;
  22
  23   /**
  24    * The target of the connection object.
  25    *
  26    * @var string
  27    */
  28   protected $connectionTarget;
  29
  30   /**
  31    * The key of the connection object.
  32    *
  33    * @var string
  34    */
  35   protected $connectionKey;
  36
  37   /**
  38    * The query options to pass on to the connection object.
  39    *
  40    * @var array
  41    */
  42   protected $queryOptions;
  43
  44   /**
  45    * A unique identifier for this query object.
  46    */
  47   protected $uniqueIdentifier;
  48
  49   /**
  50    * The placeholder counter.
  51    */
  52   protected $nextPlaceholder = 0;
  53
  54   /**
  55    * An array of comments that can be prepended to a query.
  56    *
  57    * @var array
  58    */
  59   protected $comments = [];
  60
  61   /**
  62    * Constructs a Query object.
  63    *
  64    * @param \Drupal\Core\Database\Connection $connection
  65    *   Database connection object.
  66    * @param array $options
  67    *   Array of query options.
  68    */
  69   public function __construct(Connection $connection, $options) {
  70     $this->uniqueIdentifier = uniqid('', TRUE);
  71
  72     $this->connection = $connection;
  73     $this->connectionKey = $this->connection->getKey();
  74     $this->connectionTarget = $this->connection->getTarget();
  75
  76     $this->queryOptions = $options;
  77   }
  78
  79   /**
  80    * Implements the magic __sleep function to disconnect from the database.
  81    */
  82   public function __sleep() {
  83     $keys = get_object_vars($this);
  84     unset($keys['connection']);
  85     return array_keys($keys);
  86   }
  87
  88   /**
  89    * Implements the magic __wakeup function to reconnect to the database.
  90    */
  91   public function __wakeup() {
  92     $this->connection = Database::getConnection($this->connectionTarget, $this->connectionKey);
  93   }
  94
  95   /**
  96    * Implements the magic __clone function.
  97    */
  98   public function __clone() {
  99     $this->uniqueIdentifier = uniqid('', TRUE);
 100   }
 101
 102   /**
 103    * Runs the query against the database.
 104    *
 105    * @return \Drupal\Core\Database\StatementInterface|null
 106    *   A prepared statement, or NULL if the query is not valid.
 107    */
 108   abstract protected function execute();
 109
 110   /**
 111    * Implements PHP magic __toString method to convert the query to a string.
 112    *
 113    * The toString operation is how we compile a query object to a prepared
 114    * statement.
 115    *
 116    * @return string
 117    *   A prepared statement query string for this object.
 118    */
 119   abstract public function __toString();
 120
 121   /**
 122    * Returns a unique identifier for this object.
 123    */
 124   public function uniqueIdentifier() {
 125     return $this->uniqueIdentifier;
 126   }
 127
 128   /**
 129    * Gets the next placeholder value for this query object.
 130    *
 131    * @return int
 132    *   The next placeholder value.
 133    */
 134   public function nextPlaceholder() {
 135     return $this->nextPlaceholder++;
 136   }
 137
 138   /**
 139    * Adds a comment to the query.
 140    *
 141    * By adding a comment to a query, you can more easily find it in your
 142    * query log or the list of active queries on an SQL server. This allows
 143    * for easier debugging and allows you to more easily find where a query
 144    * with a performance problem is being generated.
 145    *
 146    * The comment string will be sanitized to remove * / and other characters
 147    * that may terminate the string early so as to avoid SQL injection attacks.
 148    *
 149    * @param $comment
 150    *   The comment string to be inserted into the query.
 151    *
 152    * @return $this
 153    */
 154   public function comment($comment) {
 155     $this->comments[] = $comment;
 156     return $this;
 157   }
 158
 159   /**
 160    * Returns a reference to the comments array for the query.
 161    *
 162    * Because this method returns by reference, alter hooks may edit the comments
 163    * array directly to make their changes. If just adding comments, however, the
 164    * use of comment() is preferred.
 165    *
 166    * Note that this method must be called by reference as well:
 167    * @code
 168    * $comments =& $query->getComments();
 169    * @endcode
 170    *
 171    * @return array
 172    *   A reference to the comments array structure.
 173    */
 174   public function &getComments() {
 175     return $this->comments;
 176   }
 177
 178 }