3 namespace Drupal\views\Plugin\views\query;
5 use Drupal\Core\Cache\Cache;
6 use Drupal\Core\Cache\CacheableDependencyInterface;
7 use Drupal\Core\Form\FormStateInterface;
8 use Drupal\views\Plugin\views\PluginBase;
9 use Drupal\views\ViewExecutable;
10 use Drupal\views\Views;
13 * @defgroup views_query_plugins Views query plugins
15 * Plugins for views queries.
17 * Query plugins generate and execute a built query object against a
18 * particular storage backend, converting the Views query object into an
19 * actual query. Although query plugins need not necessarily use SQL, most
20 * other handler plugins that affect the query (fields, filters, etc.)
21 * implicitly assume that the query is using SQL.
23 * Query plugins extend \Drupal\views\Plugin\views\query\QueryPluginBase.
24 * They must be annotated with \Drupal\views\Annotation\ViewsQuery
25 * annotation, and they must be in namespace directory Plugin\views\query.
27 * @ingroup views_plugins
32 * Base plugin class for Views queries.
34 abstract class QueryPluginBase extends PluginBase implements CacheableDependencyInterface {
37 * A pager plugin that should be provided by the display.
39 * @var views_plugin_pager
44 * Stores the limit of items that should be requested in the query.
51 * Generate a query and a countquery from all of the information supplied
55 * Provide a countquery if this is true, otherwise provide a normal query.
57 public function query($get_count = FALSE) {}
60 * Let modules modify the query just prior to finalizing it.
63 * The view which is executed.
65 public function alter(ViewExecutable $view) {}
68 * Builds the necessary info to execute the query.
71 * The view which is executed.
73 public function build(ViewExecutable $view) {}
76 * Executes the query and fills the associated view object with according
79 * Values to set: $view->result, $view->total_rows, $view->execute_time,
80 * $view->pager['current_page'].
82 * $view->result should contain an array of objects. The array must use a
83 * numeric index starting at 0.
86 * The view which is executed.
88 public function execute(ViewExecutable $view) {}
91 * Add a signature to the query, if such a thing is feasible.
93 * This signature is something that can be used when perusing query logs to
94 * discern where particular queries might be coming from.
97 * The view which is executed.
99 public function addSignature(ViewExecutable $view) {}
102 * Get aggregation info for group by queries.
104 * If NULL, aggregation is not allowed.
106 public function getAggregationInfo() {}
108 public function validateOptionsForm(&$form, FormStateInterface $form_state) {}
110 public function submitOptionsForm(&$form, FormStateInterface $form_state) {}
112 public function summaryTitle() {
113 return $this->t('Settings');
119 public function calculateDependencies() {
122 foreach ($this->getEntityTableInfo() as $entity_type => $info) {
123 if (!empty($info['provider'])) {
124 $dependencies['module'][] = $info['provider'];
128 return $dependencies;
132 * Set a LIMIT on the query, specifying a maximum number of results.
134 public function setLimit($limit) {
135 $this->limit = $limit;
139 * Set an OFFSET on the query, specifying a number of results to skip
141 public function setOffset($offset) {
142 $this->offset = $offset;
146 * Returns the limit of the query.
148 public function getLimit() {
153 * Create a new grouping for the WHERE or HAVING clause.
156 * Either 'AND' or 'OR'. All items within this group will be added
157 * to the WHERE clause with this logical operator.
159 * An ID to use for this group. If unspecified, an ID will be generated.
161 * 'where' or 'having'.
164 * The group ID generated.
166 public function setWhereGroup($type = 'AND', $group = NULL, $where = 'where') {
168 $groups = &$this->$where;
170 if (!isset($group)) {
171 $group = empty($groups) ? 1 : max(array_keys($groups)) + 1;
174 // Create an empty group
175 if (empty($groups[$group])) {
176 $groups[$group] = ['conditions' => [], 'args' => []];
179 $groups[$group]['type'] = strtoupper($type);
184 * Control how all WHERE and HAVING groups are put together.
187 * Either 'AND' or 'OR'
189 public function setGroupOperator($type = 'AND') {
190 $this->groupOperator = strtoupper($type);
194 * Loads all entities contained in the passed-in $results.
196 * If the entity belongs to the base table, then it gets stored in
197 * $result->_entity. Otherwise, it gets stored in
198 * $result->_relationship_entities[$relationship_id];
200 * Query plugins that don't support entities can leave the method empty.
202 public function loadEntities(&$results) {}
205 * Returns a Unix timestamp to database native timestamp expression.
207 * @param string $field
208 * The query field that will be used in the expression.
209 * @param bool $string_date
210 * For certain databases, date format functions vary depending on string or
212 * @param bool $calculate_offset
213 * If set to TRUE, the timezone offset will be included in the returned
217 * An expression representing a timestamp with time zone.
219 public function getDateField($field, $string_date = FALSE, $calculate_offset = TRUE) {
224 * Set the database to the current user timezone,
227 * The current timezone as returned by drupal_get_user_timezone().
229 public function setupTimezone() {
230 return drupal_get_user_timezone();
234 * Creates cross-database date formatting.
236 * @param string $field
237 * An appropriate query expression pointing to the date field.
238 * @param string $format
239 * A format string for the result, like 'Y-m-d H:i:s'.
240 * @param bool $string_date
241 * For certain databases, date format functions vary depending on string or
245 * A string representing the field formatted as a date in the format
246 * specified by $format.
248 public function getDateFormat($field, $format, $string_date = FALSE) {
253 * Returns an array of all tables from the query that map to an entity type.
255 * Includes the base table and all relationships, if eligible.
257 * Available keys for each table:
258 * - base: The actual base table (i.e. "user" for an author relationship).
259 * - relationship_id: The id of the relationship, or "none".
260 * - alias: The alias used for the relationship.
261 * - entity_type: The entity type matching the base table.
262 * - revision: A boolean that specifies whether the table is a base table or
263 * a revision table of the entity type.
266 * An array of table information, keyed by table alias.
268 public function getEntityTableInfo() {
269 // Start with the base table.
271 $views_data = Views::viewsData();
272 $base_table = $this->view->storage->get('base_table');
273 $base_table_data = $views_data->get($base_table);
275 if (isset($base_table_data['table']['entity type'])) {
276 $entity_tables[$base_table_data['table']['entity type']] = [
277 'base' => $base_table,
278 'alias' => $base_table,
279 'relationship_id' => 'none',
280 'entity_type' => $base_table_data['table']['entity type'],
281 'revision' => $base_table_data['table']['entity revision'],
284 // Include the entity provider.
285 if (!empty($base_table_data['table']['provider'])) {
286 $entity_tables[$base_table_data['table']['entity type']]['provider'] = $base_table_data['table']['provider'];
290 // Include all relationships.
291 foreach ((array) $this->view->relationship as $relationship_id => $relationship) {
292 $table_data = $views_data->get($relationship->definition['base']);
293 if (isset($table_data['table']['entity type'])) {
295 // If this is not one of the entity base tables, skip it.
296 $entity_type = \Drupal::entityTypeManager()->getDefinition($table_data['table']['entity type']);
297 $entity_base_tables = [$entity_type->getBaseTable(), $entity_type->getDataTable(), $entity_type->getRevisionTable(), $entity_type->getRevisionDataTable()];
298 if (!in_array($relationship->definition['base'], $entity_base_tables)) {
302 $entity_tables[$relationship_id . '__' . $relationship->tableAlias] = [
303 'base' => $relationship->definition['base'],
304 'relationship_id' => $relationship_id,
305 'alias' => $relationship->alias,
306 'entity_type' => $table_data['table']['entity type'],
307 'revision' => $table_data['table']['entity revision'],
310 // Include the entity provider.
311 if (!empty($table_data['table']['provider'])) {
312 $entity_tables[$relationship_id . '__' . $relationship->tableAlias]['provider'] = $table_data['table']['provider'];
317 // Determine which of the tables are revision tables.
318 foreach ($entity_tables as $table_alias => $table) {
319 $entity_type = \Drupal::entityManager()->getDefinition($table['entity_type']);
320 if ($entity_type->getRevisionTable() == $table['base']) {
321 $entity_tables[$table_alias]['revision'] = TRUE;
325 return $entity_tables;
331 public function getCacheMaxAge() {
332 return Cache::PERMANENT;
338 public function getCacheContexts() {
340 if (($views_data = Views::viewsData()->get($this->view->storage->get('base_table'))) && !empty($views_data['table']['entity type'])) {
341 $entity_type_id = $views_data['table']['entity type'];
342 $entity_type = \Drupal::entityManager()->getDefinition($entity_type_id);
343 $contexts = $entity_type->getListCacheContexts();
351 public function getCacheTags() {
356 * Applies a timezone offset to the given field.
358 * @param string &$field
359 * The date field, in string format.
361 * The timezone offset to apply to the field.
363 public function setFieldTimezoneOffset(&$field, $offset) {
364 // No-op. Timezone offsets are implementation-specific and should implement
365 // this method as needed.
369 * Get the timezone offset in seconds.
372 * The offset, in seconds, for the timezone being used.
374 public function getTimezoneOffset() {
375 $timezone = $this->setupTimezone();
378 $dtz = new \DateTimeZone($timezone);
379 $dt = new \DateTime('now', $dtz);
380 $offset = $dtz->getOffset($dt);