class JoinPluginBase in Drupal 8

Represents a join and creates the SQL necessary to implement the join.

Extensions of this class can be used to create more interesting joins.

Hierarchy

• class \Drupal\Component\Plugin\PluginBase implements DerivativeInspectionInterface, PluginInspectionInterface
  • class \Drupal\Core\Plugin\PluginBase uses DependencySerializationTrait, MessengerTrait, StringTranslationTrait
    • class \Drupal\views\Plugin\views\join\JoinPluginBase implements JoinPluginInterface

Related topics

Views join handler plugins

Handler plugins for Views table joins.

4 files declare their use of JoinPluginBase

JoinTest.php in core/modules/views/tests/src/Kernel/Plugin/JoinTest.php

JoinTest.php in core/modules/views/tests/modules/views_test_data/src/Plugin/views/join/JoinTest.php

QueryTest.php in core/modules/views/tests/modules/views_test_data/src/Plugin/views/query/QueryTest.php

Sql.php in core/modules/views/src/Plugin/views/query/Sql.php

File

core/modules/views/src/Plugin/views/join/JoinPluginBase.php, line 153

Namespace

Drupal\views\Plugin\views\join

class JoinPluginBase extends PluginBase implements JoinPluginInterface {

  /**
   * The table to join (right table).
   *
   * @var string
   */
  public $table;

  /**
   * The field to join on (right field).
   *
   * @var string
   */
  public $field;

  /**
   * The table we join to.
   *
   * @var string
   */
  public $leftTable;

  /**
   * The field we join to.
   *
   * @var string
   */
  public $leftField;

  /**
   * A formula to be used instead of the left field.
   *
   * @var string
   */
  public $leftFormula;

  /**
   * An array of extra conditions on the join.
   *
   * Each condition is either a string that's directly added, or an array of
   * items:
   *   - table(optional): If not set, current table; if NULL, no table. If you
   *     specify a table in cached configuration, Views will try to load from an
   *     existing alias. If you use realtime joins, it works better.
   *   - field(optional): Field or formula. In formulas we can reference the
   *     right table by using %alias.
   *   - left_field(optional): Field or formula. In formulas we can reference
   *     the left table by using %alias.
   *   - operator(optional): The operator used, Defaults to "=".
   *   - value: Must be set. If an array, operator will be defaulted to IN.
   *   - numeric: If true, the value will not be surrounded in quotes.
   *
   * @see SelectQueryInterface::addJoin()
   *
   * @var array
   */
  public $extra;

  /**
   * The join type, so for example LEFT (default) or INNER.
   *
   * @var string
   */
  public $type;

  /**
   * The configuration array passed by initJoin.
   *
   * @var array
   *
   * @see \Drupal\views\Plugin\views\join\JoinPluginBase::initJoin()
   */
  public $configuration = [];

  /**
   * How all the extras will be combined. Either AND or OR.
   *
   * @var string
   */
  public $extraOperator;

  /**
   * Defines whether a join has been adjusted.
   *
   * Views updates the join object to set the table alias instead of the table
   * name. Once views has changed the alias it sets the adjusted value so it
   * does not have to be updated anymore. If you create your own join object
   * you should set the adjusted in the definition array to TRUE if you already
   * know the table alias.
   *
   * @var bool
   *
   * @see \Drupal\views\Plugin\HandlerBase::getTableJoin()
   * @see \Drupal\views\Plugin\views\query\Sql::adjustJoin()
   * @see \Drupal\views\Plugin\views\relationship\RelationshipPluginBase::query()
   */
  public $adjusted;

  /**
   * Constructs a Drupal\views\Plugin\views\join\JoinPluginBase object.
   */
  public function __construct(array $configuration, $plugin_id, $plugin_definition) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);

    // Merge in some default values.
    $configuration += [
      'type' => 'LEFT',
      'extra_operator' => 'AND',
    ];
    $this->configuration = $configuration;
    if (!empty($configuration['table'])) {
      $this->table = $configuration['table'];
    }
    $this->leftTable = $configuration['left_table'];
    $this->leftField = $configuration['left_field'];
    $this->field = $configuration['field'];
    if (!empty($configuration['left_formula'])) {
      $this->leftFormula = $configuration['left_formula'];
    }
    if (!empty($configuration['extra'])) {
      $this->extra = $configuration['extra'];
    }
    if (isset($configuration['adjusted'])) {
      $this->adjusted = $configuration['adjusted'];
    }
    $this->extraOperator = strtoupper($configuration['extra_operator']);
    $this->type = $configuration['type'];
  }

  /**
   * {@inheritdoc}
   */
  public function buildJoin($select_query, $table, $view_query) {
    if (empty($this->configuration['table formula'])) {
      $right_table = $this->table;
    }
    else {
      $right_table = $this->configuration['table formula'];
    }
    if ($this->leftTable) {
      $left_table = $view_query
        ->getTableInfo($this->leftTable);
      $left_field = $this->leftFormula ?: "{$left_table['alias']}.{$this->leftField}";
    }
    else {

      // This can be used if left_field is a formula or something. It should be used only *very* rarely.
      $left_field = $this->leftField;
      $left_table = NULL;
    }
    $condition = "{$left_field} = {$table['alias']}.{$this->field}";
    $arguments = [];

    // Tack on the extra.
    if (isset($this->extra)) {
      $this
        ->joinAddExtra($arguments, $condition, $table, $select_query, $left_table);
    }
    $select_query
      ->addJoin($this->type, $right_table, $table['alias'], $condition, $arguments);
  }

  /**
   * Adds the extras to the join condition.
   *
   * @param array $arguments
   *   Array of query arguments.
   * @param string $condition
   *   The condition to be built.
   * @param array $table
   *   The right table.
   * @param \Drupal\Core\Database\Query\SelectInterface $select_query
   *   The current select query being built.
   * @param array $left_table
   *   The left table.
   */
  protected function joinAddExtra(&$arguments, &$condition, $table, SelectInterface $select_query, $left_table = NULL) {
    if (is_array($this->extra)) {
      $extras = [];
      foreach ($this->extra as $info) {
        $extras[] = $this
          ->buildExtra($info, $arguments, $table, $select_query, $left_table);
      }
      if ($extras) {
        if (count($extras) == 1) {
          $condition .= ' AND ' . array_shift($extras);
        }
        else {
          $condition .= ' AND (' . implode(' ' . $this->extraOperator . ' ', $extras) . ')';
        }
      }
    }
    elseif ($this->extra && is_string($this->extra)) {
      $condition .= " AND ({$this->extra})";
    }
  }

  /**
   * Builds a single extra condition.
   *
   * @param array $info
   *   The extra information. See JoinPluginBase::$extra for details.
   * @param array $arguments
   *   Array of query arguments.
   * @param array $table
   *   The right table.
   * @param \Drupal\Core\Database\Query\SelectInterface $select_query
   *   The current select query being built.
   * @param array $left
   *   The left table.
   *
   * @return string
   *   The extra condition
   */
  protected function buildExtra($info, &$arguments, $table, SelectInterface $select_query, $left) {

    // Do not require 'value' to be set; allow for field syntax instead.
    $info += [
      'value' => NULL,
    ];

    // Figure out the table name. Remember, only use aliases provided
    // if at all possible.
    $join_table = '';
    if (!array_key_exists('table', $info)) {
      $join_table = $table['alias'] . '.';
    }
    elseif (isset($info['table'])) {

      // If we're aware of a table alias for this table, use the table
      // alias instead of the table name.
      if (isset($left) && $left['table'] == $info['table']) {
        $join_table = $left['alias'] . '.';
      }
      else {
        $join_table = $info['table'] . '.';
      }
    }

    // Convert a single-valued array of values to the single-value case,
    // and transform from IN() notation to = notation
    if (is_array($info['value']) && count($info['value']) == 1) {
      $info['value'] = array_shift($info['value']);
    }
    if (is_array($info['value'])) {

      // We use an SA-CORE-2014-005 conformant placeholder for our array
      // of values. Also, note that the 'IN' operator is implicit.
      // @see https://www.drupal.org/node/2401615.
      $operator = !empty($info['operator']) ? $info['operator'] : 'IN';
      $placeholder = ':views_join_condition_' . $select_query
        ->nextPlaceholder() . '[]';
      $placeholder_sql = "( {$placeholder} )";
    }
    else {

      // With a single value, the '=' operator is implicit.
      $operator = !empty($info['operator']) ? $info['operator'] : '=';
      $placeholder = $placeholder_sql = ':views_join_condition_' . $select_query
        ->nextPlaceholder();
    }

    // Set 'field' as join table field if available or set 'left field' as
    // join table field is not set.
    if (isset($info['field'])) {
      $join_table_field = "{$join_table}{$info['field']}";

      // Allow the value to be set either with the 'value' element or
      // with 'left_field'.
      if (isset($info['left_field'])) {
        $placeholder_sql = "{$left['alias']}.{$info['left_field']}";
      }
      else {
        $arguments[$placeholder] = $info['value'];
      }
    }
    else {
      $join_table_field = "{$left['alias']}.{$info['left_field']}";
      $arguments[$placeholder] = $info['value'];
    }

    // Render out the SQL fragment with parameters.
    return "{$join_table_field} {$operator} {$placeholder_sql}";
  }

}

Members

Name	Modifiers	Type	Description	Overrides
DependencySerializationTrait::$_entityStorages	protected	property	An array of entity type IDs keyed by the property name of their storages.
DependencySerializationTrait::$_serviceIds	protected	property	An array of service IDs keyed by property name used for serialization.
DependencySerializationTrait::__sleep	public	function		1
DependencySerializationTrait::__wakeup	public	function		2
JoinPluginBase::$adjusted	public	property	Defines whether a join has been adjusted.
JoinPluginBase::$configuration	public	property	The configuration array passed by initJoin. Overrides PluginBase::$configuration
JoinPluginBase::$extra	public	property	An array of extra conditions on the join.
JoinPluginBase::$extraOperator	public	property	How all the extras will be combined. Either AND or OR.
JoinPluginBase::$field	public	property	The field to join on (right field).
JoinPluginBase::$leftField	public	property	The field we join to.
JoinPluginBase::$leftFormula	public	property	A formula to be used instead of the left field.
JoinPluginBase::$leftTable	public	property	The table we join to.
JoinPluginBase::$table	public	property	The table to join (right table).
JoinPluginBase::$type	public	property	The join type, so for example LEFT (default) or INNER.
JoinPluginBase::buildExtra	protected	function	Builds a single extra condition.
JoinPluginBase::buildJoin	public	function	Builds the SQL for the join this object represents. Overrides JoinPluginInterface::buildJoin	2
JoinPluginBase::joinAddExtra	protected	function	Adds the extras to the join condition.	1
JoinPluginBase::__construct	public	function	Constructs a Drupal\views\Plugin\views\join\JoinPluginBase object. Overrides PluginBase::__construct	1
MessengerTrait::$messenger	protected	property	The messenger.	29
MessengerTrait::messenger	public	function	Gets the messenger.	29
MessengerTrait::setMessenger	public	function	Sets the messenger.
PluginBase::$pluginDefinition	protected	property	The plugin implementation definition.	1
PluginBase::$pluginId	protected	property	The plugin_id.
PluginBase::DERIVATIVE_SEPARATOR		constant	A string which is used to separate base plugin IDs from the derivative ID.
PluginBase::getBaseId	public	function	Gets the base_plugin_id of the plugin instance. Overrides DerivativeInspectionInterface::getBaseId
PluginBase::getDerivativeId	public	function	Gets the derivative_id of the plugin instance. Overrides DerivativeInspectionInterface::getDerivativeId
PluginBase::getPluginDefinition	public	function	Gets the definition of the plugin implementation. Overrides PluginInspectionInterface::getPluginDefinition	3
PluginBase::getPluginId	public	function	Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
PluginBase::isConfigurable	public	function	Determines if the plugin is configurable.
StringTranslationTrait::$stringTranslation	protected	property	The string translation service.	1
StringTranslationTrait::formatPlural	protected	function	Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals	protected	function	Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation	protected	function	Gets the string translation service.
StringTranslationTrait::setStringTranslation	public	function	Sets the string translation service to use.	2
StringTranslationTrait::t	protected	function	Translates a string to the current language or to a given language.