You are here

Home » API reference » Drupal 9 » JoinPluginBase.php

class JoinPluginBase in Drupal 9

Same name and namespace in other branches
  1. 8 core/modules/views/src/Plugin/views/join/JoinPluginBase.php \Drupal\views\Plugin\views\join\JoinPluginBase

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

Expanded class hierarchy of JoinPluginBase

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
View source 
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'];
    if (!empty($configuration['left_field'])) {
      $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

Namesort descending Modifiers Type Description Overrides
DependencySerializationTrait::$_entityStorages protected property
DependencySerializationTrait::$_serviceIds protected property
DependencySerializationTrait::__sleep public function 2
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. 27
MessengerTrait::messenger public function Gets the messenger. 27
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 2
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. 4
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.