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