abstract class QueryPluginBase extends PluginBase implements CacheableDependencyInterface (View source)

Base plugin class for Views queries.

Traits

Wrapper methods for \Drupal\Core\StringTranslation\TranslationInterface.

Provides dependency injection friendly methods for serialization.

Provides a trait for the messenger service.

Constants

DERIVATIVE_SEPARATOR

A string which is used to separate base plugin IDs from the derivative ID.

INCLUDE_NEGOTIATED

Include negotiated languages when listing languages.

INCLUDE_ENTITY

Include entity row languages when listing languages.

VIEWS_QUERY_LANGUAGE_SITE_DEFAULT

Query string to indicate the site default language.

Properties

protected string $pluginId

The plugin_id.

from  PluginBase
protected array $pluginDefinition

The plugin implementation definition.

from  PluginBase
protected array $configuration

Configuration information passed into the plugin.

from  PluginBase
protected TranslationInterface $stringTranslation

The string translation service.

from  StringTranslationTrait
protected array $_serviceIds

An array of service IDs keyed by property name used for serialization.

from  DependencySerializationTrait
protected array $_entityStorages

An array of entity type IDs keyed by the property name of their storages.

from  DependencySerializationTrait
protected MessengerInterface $messenger

The messenger.

from  MessengerTrait
array $options

Options for this plugin will be held here.

from  PluginBase
ViewExecutable $view

The top object of a view.

from  PluginBase
DisplayPluginBase $displayHandler

The display object this plugin is for.

from  PluginBase
array $definition

Plugins's definition.

from  PluginBase
protected bool $usesOptions

Denotes whether the plugin has an additional options form.

from  PluginBase
protected RendererInterface $renderer

Stores the render API renderer.

from  PluginBase
views_plugin_pager $pager

A pager plugin that should be provided by the display.

protected int $limit

Stores the limit of items that should be requested in the query.

Methods

__construct(array $configuration, string $plugin_id, mixed $plugin_definition)

Constructs a PluginBase object.

string
getPluginId()

Gets the plugin_id of the plugin instance.

string
getBaseId()

Gets the base_plugin_id of the plugin instance.

string|null
getDerivativeId()

Gets the derivative_id of the plugin instance.

array
getPluginDefinition()

Gets the definition of the plugin implementation.

bool
isConfigurable()

Determines if the plugin is configurable.

t(string $string, array $args = [], array $options = [])

Translates a string to the current language or to a given language.

formatPlural($count, $singular, $plural, array $args = [], array $options = [])

Formats a string containing a count of items.

getNumberOfPlurals($langcode = NULL)

Returns the number of plurals supported by a given language.

getStringTranslation()

Gets the string translation service.

$this
setStringTranslation(TranslationInterface $translation)

Sets the string translation service to use.

__sleep()

{@inheritdoc}

__wakeup()

{@inheritdoc}

setMessenger(MessengerInterface $messenger)

Sets the messenger.

messenger()

Gets the messenger.

create(ContainerInterface $container, array $configuration, string $plugin_id, mixed $plugin_definition)

Creates an instance of the plugin.

init(ViewExecutable $view, DisplayPluginBase $display, array $options = NULL)

Initialize the plugin.

array
defineOptions()

Information about options for all kinds of purposes will be held here.

setOptionDefaults(array $storage, array $options)

Fills up the options of the plugin with defaults.

filterByDefinedOptions(array $storage)

Filter out stored options depending on the defined options.

doFilterByDefinedOptions(array $storage, array $options)

Do the work to filter out stored options depending on the defined options.

unpackOptions($storage, $options, $definition = NULL, $all = TRUE, $check = TRUE)

Unpack options over our existing defaults, drilling down into arrays so that defaults don't get totally blown away.

destroy()

Clears a plugin.

buildOptionsForm($form, FormStateInterface $form_state)

Provide a form to edit options for this plugin.

static string[]
trustedCallbacks()

Lists the trusted callbacks provided by the implementing class.

validateOptionsForm($form, FormStateInterface $form_state)

Validate the options form.

submitOptionsForm($form, FormStateInterface $form_state)

Handle any special handling on the validate form.

query($get_count = FALSE)

Generate a query and a countquery from all of the information supplied to the object.

themeFunctions()

Provide a full list of possible theme templates used by this style.

An
validate()

Validate that the plugin is correct and can be saved.

summaryTitle()

Returns the summary of the settings in the display.

pluginTitle()

Return the human readable name of the display.

usesOptions()

Returns the usesOptions property.

string
globalTokenReplace(string $string = '', array $options = [])

Returns a string with any core tokens replaced.

string
viewsTokenReplace($text, $tokens)

Replaces Views' tokens in a given string. The resulting string will be sanitized with Xss::filterAdmin.

array
getAvailableGlobalTokens(bool $prepared = FALSE, array $types = [])

Returns an array of available token replacements.

globalTokenForm(array $form, FormStateInterface $form_state)

Adds elements for available core tokens to a form.

static array
preRenderAddFieldsetMarkup(array $form)

Moves form elements into fieldsets for presentation purposes.

static array
preRenderFlattenData(array $form)

Flattens the structure of form elements.

array
calculateDependencies()

Calculates dependencies for the configured plugin.

string
getProvider()

Returns the plugin provider.

array
listLanguages(int $flags = LanguageInterface::STATE_ALL, array $current_values = NULL)

Makes an array of languages, optionally including special languages.

static array
queryLanguageSubstitutions()

Returns substitutions for Views queries for languages.

getRenderer()

Returns the render API renderer.

alter(ViewExecutable $view)

Let modules modify the query just prior to finalizing it.

build(ViewExecutable $view)

Builds the necessary info to execute the query.

execute(ViewExecutable $view)

Executes the query and fills the associated view object with according values.

addSignature(ViewExecutable $view)

Add a signature to the query, if such a thing is feasible.

getAggregationInfo()

Get aggregation info for group by queries.

setLimit($limit)

Set a LIMIT on the query, specifying a maximum number of results.

setOffset($offset)

Set an OFFSET on the query, specifying a number of results to skip.

getLimit()

Returns the limit of the query.

The
setWhereGroup($type = 'AND', $group = NULL, $where = 'where')

Create a new grouping for the WHERE or HAVING clause.

setGroupOperator($type = 'AND')

Control how all WHERE and HAVING groups are put together.

loadEntities($results)

Loads all entities contained in the passed-in $results.

string
getDateField(string $field, bool $string_date = FALSE, bool $calculate_offset = TRUE)

Returns a Unix timestamp to database native timestamp expression.

string
setupTimezone()

Set the database to the current user timezone.

string
getDateFormat(string $field, string $format, bool $string_date = FALSE)

Creates cross-database date formatting.

array
getEntityTableInfo()

Returns an array of all tables from the query that map to an entity type.

int
getCacheMaxAge()

The maximum age for which this object may be cached.

string[]
getCacheContexts()

The cache contexts associated with this object.

string[]
getCacheTags()

The cache tags associated with this object.

setFieldTimezoneOffset(string $field, int $offset)

Applies a timezone offset to the given field.

int
getTimezoneOffset()

Get the timezone offset in seconds.

Details

__construct(array $configuration, string $plugin_id, mixed $plugin_definition)

Constructs a PluginBase object.

Parameters

array $configuration

A configuration array containing information about the plugin instance.

string $plugin_id

The plugin_id for the plugin instance.

mixed $plugin_definition

The plugin implementation definition.

string getPluginId()

Gets the plugin_id of the plugin instance.

Return Value

string

The plugin_id of the plugin instance.

string getBaseId()

Gets the base_plugin_id of the plugin instance.

Return Value

string

The base_plugin_id of the plugin instance.

string|null getDerivativeId()

Gets the derivative_id of the plugin instance.

Return Value

string|null

The derivative_id of the plugin instance NULL otherwise.

array getPluginDefinition()

Gets the definition of the plugin implementation.

Return Value

array

The plugin definition, as returned by the discovery object used by the plugin manager.

bool isConfigurable()

Determines if the plugin is configurable.

Return Value

bool

A boolean indicating whether the plugin is configurable.

protected TranslatableMarkup t(string $string, array $args = [], array $options = [])

Translates a string to the current language or to a given language.

See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for important security information and usage guidelines.

In order for strings to be localized, make them available in one of the ways supported by the

Parameters

string $string

A string containing the English text to translate.

array $args

(optional) An associative array of replacements to make after translation. Based on the first character of the key, the value is escaped and/or themed. See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for details.

array $options

(optional) An associative array of additional options, with the following elements:

  • 'langcode' (defaults to the current language): A language code, to translate to a language other than what is used to display the page.
  • 'context' (defaults to the empty context): The context the source string belongs to. See the @link i18n Internationalization topic @endlink for more information about string contexts.

Return Value

TranslatableMarkup

An object that, when cast to a string, returns the translated string.

See also

FormattableMarkup::placeholderFormat
TranslatableMarkup::__construct

protected formatPlural($count, $singular, $plural, array $args = [], array $options = [])

Formats a string containing a count of items.

Parameters

$count
$singular
$plural
array $args
array $options

See also

TranslationInterface::formatPlural

protected getNumberOfPlurals($langcode = NULL)

Returns the number of plurals supported by a given language.

Parameters

$langcode

See also

PluralFormulaInterface::getNumberOfPlurals

protected TranslationInterface getStringTranslation()

Gets the string translation service.

Return Value

TranslationInterface

The string translation service.

$this setStringTranslation(TranslationInterface $translation)

Sets the string translation service to use.

Parameters

TranslationInterface $translation

The string translation service.

Return Value

$this

__sleep()

{@inheritdoc}

__wakeup()

{@inheritdoc}

setMessenger(MessengerInterface $messenger)

Sets the messenger.

Parameters

MessengerInterface $messenger

The messenger.

MessengerInterface messenger()

Gets the messenger.

Return Value

MessengerInterface

The messenger.

static ContainerFactoryPluginInterface create(ContainerInterface $container, array $configuration, string $plugin_id, mixed $plugin_definition)

Creates an instance of the plugin.

Parameters

ContainerInterface $container

The container to pull out services used in the plugin.

array $configuration

A configuration array containing information about the plugin instance.

string $plugin_id

The plugin ID for the plugin instance.

mixed $plugin_definition

The plugin implementation definition.

Return Value

ContainerFactoryPluginInterface

Returns an instance of this plugin.

init(ViewExecutable $view, DisplayPluginBase $display, array $options = NULL)

Initialize the plugin.

Parameters

ViewExecutable $view

The view object.

DisplayPluginBase $display

The display handler.

array $options

The options configured for this plugin.

protected array defineOptions()

Information about options for all kinds of purposes will be held here.

Return Value

array

Returns the options of this handler/plugin.

protected setOptionDefaults(array $storage, array $options)

Fills up the options of the plugin with defaults.

Parameters

array $storage

An array which stores the actual option values of the plugin.

array $options

An array which describes the options of a plugin. Each element is an associative array containing:

  • default: The default value of one option. Should be translated to the interface text language selected for page if translatable.
  • (optional) contains: An array which describes the available options under the key. If contains is set, the default will be ignored and assumed to be an empty array.
  • (optional) 'bool': TRUE if the value is boolean, else FALSE.

filterByDefinedOptions(array $storage)

Filter out stored options depending on the defined options.

Parameters

array $storage

The stored options.

protected doFilterByDefinedOptions(array $storage, array $options)

Do the work to filter out stored options depending on the defined options.

Parameters

array $storage

The stored options.

array $options

The defined options.

unpackOptions($storage, $options, $definition = NULL, $all = TRUE, $check = TRUE)

Unpack options over our existing defaults, drilling down into arrays so that defaults don't get totally blown away.

Parameters

$storage
$options
$definition
$all
$check

destroy()

Clears a plugin.

buildOptionsForm($form, FormStateInterface $form_state)

Provide a form to edit options for this plugin.

Parameters

$form
FormStateInterface $form_state

static string[] trustedCallbacks()

Lists the trusted callbacks provided by the implementing class.

Trusted callbacks are public methods on the implementing class and can be invoked via \Drupal\Core\Security\DoTrustedCallbackTrait::doTrustedCallback().

Return Value

string[]

List of method names implemented by the class that can be used as trusted callbacks.

validateOptionsForm($form, FormStateInterface $form_state)

Validate the options form.

Parameters

$form
FormStateInterface $form_state

submitOptionsForm($form, FormStateInterface $form_state)

Handle any special handling on the validate form.

Parameters

$form
FormStateInterface $form_state

query($get_count = FALSE)

Generate a query and a countquery from all of the information supplied to the object.

Parameters

$get_count

Provide a countquery if this is true, otherwise provide a normal query.

themeFunctions()

Provide a full list of possible theme templates used by this style.

An validate()

Validate that the plugin is correct and can be saved.

Return Value

An

array of error strings to tell the user what is wrong with this plugin.

summaryTitle()

Returns the summary of the settings in the display.

pluginTitle()

Return the human readable name of the display.

This appears on the ui beside each plugin and beside the settings link.

usesOptions()

Returns the usesOptions property.

string globalTokenReplace(string $string = '', array $options = [])

Returns a string with any core tokens replaced.

Parameters

string $string

The string to preform the token replacement on.

array $options

An array of options, as passed to \Drupal\Core\Utility\Token::replace().

Return Value

string

The tokenized string.

protected string viewsTokenReplace($text, $tokens)

Replaces Views' tokens in a given string. The resulting string will be sanitized with Xss::filterAdmin.

Parameters

$text

Unsanitized string with possible tokens.

$tokens

Array of token => replacement_value items.

Return Value

string

array getAvailableGlobalTokens(bool $prepared = FALSE, array $types = [])

Returns an array of available token replacements.

Parameters

bool $prepared

Whether to return the raw token info for each token or an array of prepared tokens for each type. E.g. "[view:name]".

array $types

An array of additional token types to return, defaults to 'site' and 'view'.

Return Value

array

An array of available token replacement info or tokens, grouped by type.

globalTokenForm(array $form, FormStateInterface $form_state)

Adds elements for available core tokens to a form.

Parameters

array $form

The form array to alter, passed by reference.

FormStateInterface $form_state

The current state of the form.

static array preRenderAddFieldsetMarkup(array $form)

Moves form elements into fieldsets for presentation purposes.

Many views forms use #tree = TRUE to keep their values in a hierarchy for easier storage. Moving the form elements into fieldsets during form building would break up that hierarchy. Therefore, we wait until the pre_render stage, where any changes we make affect presentation only and aren't reflected in $form_state->getValues().

Parameters

array $form

The form build array to alter.

Return Value

array

The form build array.

static array preRenderFlattenData(array $form)

Flattens the structure of form elements.

If a form element has #flatten = TRUE, then all of its children get moved to the same level as the element itself. So $form['to_be_flattened'][$key] becomes $form[$key], and $form['to_be_flattened'] gets unset.

Parameters

array $form

The form build array to alter.

Return Value

array

The form build array.

array calculateDependencies()

Calculates dependencies for the configured plugin.

Dependencies are saved in the plugin's configuration entity and are used to determine configuration synchronization order. For example, if the plugin integrates with specific user roles, this method should return an array of dependencies listing the specified roles.

Return Value

array

An array of dependencies grouped by type (config, content, module, theme). For example: @code array( 'config' => array('user.role.anonymous', 'user.role.authenticated'), 'content' => array('node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'), 'module' => array('node', 'user'), 'theme' => array('seven'), ); @endcode

string getProvider()

Returns the plugin provider.

Return Value

string

protected array listLanguages(int $flags = LanguageInterface::STATE_ALL, array $current_values = NULL)

Makes an array of languages, optionally including special languages.

Parameters

int $flags

(optional) Flags for which languages to return (additive). Options:

  • \Drupal\Core\Language::STATE_ALL (default): All languages (configurable and default).
  • \Drupal\Core\Language::STATE_CONFIGURABLE: Configurable languages.
  • \Drupal\Core\Language::STATE_LOCKED: Locked languages.
  • \Drupal\Core\Language::STATE_SITE_DEFAULT: Add site default language; note that this is not included in STATE_ALL.
  • \Drupal\views\Plugin\views\PluginBase::INCLUDE_NEGOTIATED: Add negotiated language types.
  • \Drupal\views\Plugin\views\PluginBase::INCLUDE_ENTITY: Add entity row language types. Note that these are only supported for display options, not substituted in queries.
array $current_values

The currently-selected options in the list, if available.

Return Value

array

An array of language names, keyed by the language code. Negotiated and special languages have special codes that are substituted in queries by PluginBase::queryLanguageSubstitutions(). Only configurable languages and languages that are in $current_values are included in the list.

static array queryLanguageSubstitutions()

Returns substitutions for Views queries for languages.

This is needed so that the language options returned by PluginBase::listLanguages() are able to be used in queries. It is called by the Views module implementation of hook_views_query_substitutions() to get the language-related substitutions.

Return Value

array

An array in the format of hook_views_query_substitutions() that gives the query substitutions needed for the special language types.

protected RendererInterface getRenderer()

Returns the render API renderer.

Return Value

RendererInterface

alter(ViewExecutable $view)

Let modules modify the query just prior to finalizing it.

Parameters

ViewExecutable $view

The view which is executed.

build(ViewExecutable $view)

Builds the necessary info to execute the query.

Parameters

ViewExecutable $view

The view which is executed.

execute(ViewExecutable $view)

Executes the query and fills the associated view object with according values.

Values to set: $view->result, $view->total_rows, $view->execute_time, $view->pager['current_page'].

$view->result should contain an array of objects. The array must use a numeric index starting at 0.

Parameters

ViewExecutable $view

The view which is executed.

addSignature(ViewExecutable $view)

Add a signature to the query, if such a thing is feasible.

This signature is something that can be used when perusing query logs to discern where particular queries might be coming from.

Parameters

ViewExecutable $view

The view which is executed.

getAggregationInfo()

Get aggregation info for group by queries.

If NULL, aggregation is not allowed.

setLimit($limit)

Set a LIMIT on the query, specifying a maximum number of results.

Parameters

$limit

setOffset($offset)

Set an OFFSET on the query, specifying a number of results to skip.

Parameters

$offset

getLimit()

Returns the limit of the query.

The setWhereGroup($type = 'AND', $group = NULL, $where = 'where')

Create a new grouping for the WHERE or HAVING clause.

Parameters

$type

Either 'AND' or 'OR'. All items within this group will be added to the WHERE clause with this logical operator.

$group

An ID to use for this group. If unspecified, an ID will be generated.

$where

'where' or 'having'.

Return Value

The

group ID generated.

setGroupOperator($type = 'AND')

Control how all WHERE and HAVING groups are put together.

Parameters

$type

Either 'AND' or 'OR'

loadEntities($results)

Loads all entities contained in the passed-in $results.

If the entity belongs to the base table, then it gets stored in $result->_entity. Otherwise, it gets stored in $result->_relationship_entities[$relationship_id];

Query plugins that don't support entities can leave the method empty.

Parameters

$results

string getDateField(string $field, bool $string_date = FALSE, bool $calculate_offset = TRUE)

Returns a Unix timestamp to database native timestamp expression.

Parameters

string $field

The query field that will be used in the expression.

bool $string_date

For certain databases, date format functions vary depending on string or numeric storage.

bool $calculate_offset

If set to TRUE, the timezone offset will be included in the returned field.

Return Value

string

An expression representing a timestamp with time zone.

string setupTimezone()

Set the database to the current user timezone.

Return Value

string

The current timezone as returned by date_default_timezone_get().

string getDateFormat(string $field, string $format, bool $string_date = FALSE)

Creates cross-database date formatting.

Parameters

string $field

An appropriate query expression pointing to the date field.

string $format

A format string for the result, like 'Y-m-d H:i:s'.

bool $string_date

For certain databases, date format functions vary depending on string or numeric storage.

Return Value

string

A string representing the field formatted as a date in the format specified by $format.

array getEntityTableInfo()

Returns an array of all tables from the query that map to an entity type.

Includes the base table and all relationships, if eligible.

Available keys for each table:

  • base: The actual base table (i.e. "user" for an author relationship).
  • relationship_id: The id of the relationship, or "none".
  • alias: The alias used for the relationship.
  • entity_type: The entity type matching the base table.
  • revision: A boolean that specifies whether the table is a base table or a revision table of the entity type.

Return Value

array

An array of table information, keyed by table alias.

int getCacheMaxAge()

The maximum age for which this object may be cached.

Return Value

int

The maximum time in seconds that this object may be cached.

string[] getCacheContexts()

The cache contexts associated with this object.

These identify a specific variation/representation of the object.

Cache contexts are tokens: placeholders that are converted to cache keys by the @cache_contexts_manager service. The replacement value depends on the request context (the current URL, language, and so on). They're converted before storing an object in cache.

Return Value

string[]

An array of cache context tokens, used to generate a cache ID.

string[] getCacheTags()

The cache tags associated with this object.

When this object is modified, these cache tags will be invalidated.

Return Value

string[]

A set of cache tags.

setFieldTimezoneOffset(string $field, int $offset)

Applies a timezone offset to the given field.

Parameters

string $field

The date field, in string format.

int $offset

The timezone offset to apply to the field.

int getTimezoneOffset()

Get the timezone offset in seconds.

Return Value

int

The offset, in seconds, for the timezone being used.