class JoinPluginBase

Same name in other branches
  1. 9 core/modules/views/src/Plugin/views/join/JoinPluginBase.php \Drupal\views\Plugin\views\join\JoinPluginBase
  2. 8.9.x core/modules/views/src/Plugin/views/join/JoinPluginBase.php \Drupal\views\Plugin\views\join\JoinPluginBase
  3. 10 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

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.
     *
     * @var array
     *
     * @see SelectQueryInterface::addJoin()
     */
    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',
            'operator' => '=',
        ];
        $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} " . $this->configuration['operator'] . " {$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

Title Sort descending Modifiers Object type Summary Overriden Title Overrides
JoinPluginBase::$adjusted public property Defines whether a join has been adjusted.
JoinPluginBase::$configuration public property The configuration array passed by initJoin.
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 3
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. 1

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.