aleph1.co.uk Git - yaffs-website/blob - web/core/modules/views/src/Plugin/views/join/JoinPluginBase.php

   1 <?php
   2
   3 namespace Drupal\views\Plugin\views\join;
   4
   5 use Drupal\Core\Database\Query\SelectInterface;
   6 use Drupal\Core\Plugin\PluginBase;
   7
   8 /**
   9  * @defgroup views_join_handlers Views join handler plugins
  10  * @{
  11  * Handler plugins for Views table joins.
  12  *
  13  * Handler plugins help build the view query object. Join handler plugins
  14  * handle table joins.
  15  *
  16  * Views join handlers extend \Drupal\views\Plugin\views\join\JoinPluginBase.
  17  * They must be annotated with \Drupal\views\Annotation\ViewsJoin annotation,
  18  * and they must be in namespace directory Plugin\views\join.
  19  *
  20  * Here are some examples of configuration for the join plugins.
  21  *
  22  * For this SQL:
  23  * @code
  24  * LEFT JOIN {two} ON one.field_a = two.field_b
  25  * @endcode
  26  * Use this configuration:
  27  * @code
  28  * $configuration = array(
  29  *   'table' => 'two',
  30  *   'field' => 'field_b',
  31  *   'left_table' => 'one',
  32  *   'left_field' => 'field_a',
  33  *   'operator' => '=',
  34  * );
  35  * $join = Views::pluginManager('join')->createInstance('standard', $configuration);
  36  * @endcode
  37  * Note that the default join type is a LEFT join when 'type' is not supplied in
  38  * the join plugin configuration.
  39  *
  40  * For this SQL:
  41  * @code
  42  * INNER JOIN {two} ON one.field_a = two.field_b AND one.field_c = 'some_val'
  43  * @endcode
  44  * Use this configuration:
  45  * @code
  46  * $configuration = array(
  47  *   'type' => 'INNER',
  48  *   'table' => 'two',
  49  *   'field' => 'field_b',
  50  *   'left_table' => 'one',
  51  *   'left_field' => 'field_a',
  52  *   'operator' => '=',
  53  *   'extra' => array(
  54  *     0 => array(
  55  *       'left_field' => 'field_c',
  56  *       'value' => 'some_val',
  57  *     ),
  58  *   ),
  59  * );
  60  * $join = Views::pluginManager('join')->createInstance('standard', $configuration);
  61  * @endcode
  62  *
  63  * For this SQL:
  64  * @code
  65  * INNER JOIN {two} ON one.field_a = two.field_b AND two.field_d = 'other_val'
  66  * @endcode
  67  * Use this configuration:
  68  * @code
  69  * $configuration = array(
  70  *   'type' => 'INNER',
  71  *   'table' => 'two',
  72  *   'field' => 'field_b',
  73  *   'left_table' => 'one',
  74  *   'left_field' => 'field_a',
  75  *   'operator' => '=',
  76  *   'extra' => array(
  77  *     0 => array(
  78  *       'field' => 'field_d',
  79  *       'value' => 'other_val',
  80  *     ),
  81  *   ),
  82  * );
  83  * $join = Views::pluginManager('join')->createInstance('standard', $configuration);
  84  * @endcode
  85  *
  86  * For this SQL:
  87  * @code
  88  * INNER JOIN {two} ON one.field_a = two.field_b AND one.field_c = two.field_d
  89  * @endcode
  90  * Use this configuration:
  91  * @code
  92  * $configuration = array(
  93  *   'type' => 'INNER',
  94  *   'table' => 'two',
  95  *   'field' => 'field_b',
  96  *   'left_table' => 'one',
  97  *   'left_field' => 'field_a',
  98  *   'operator' => '=',
  99  *   'extra' => array(
 100  *     0 => array(
 101  *       'left_field' => 'field_c',
 102  *       'field' => 'field_d',
 103  *     ),
 104  *   ),
 105  * );
 106  * $join = Views::pluginManager('join')->createInstance('standard', $configuration);
 107  * @endcode
 108  *
 109  * Here is an example of a more complex join:
 110  * @code
 111  * class JoinComplex extends JoinPluginBase {
 112  *   public function buildJoin($select_query, $table, $view_query) {
 113  *     // Add an additional hardcoded condition to the query.
 114  *     $this->extra = 'foo.bar = baz.boing';
 115  *     parent::buildJoin($select_query, $table, $view_query);
 116  *   }
 117  * }
 118  * @endcode
 119  *
 120  * @ingroup views_plugins
 121  * @see plugin_api
 122  */
 123
 124 /**
 125  * Represents a join and creates the SQL necessary to implement the join.
 126  *
 127  * Extensions of this class can be used to create more interesting joins.
 128  */
 129 class JoinPluginBase extends PluginBase implements JoinPluginInterface {
 130
 131   /**
 132    * The table to join (right table).
 133    *
 134    * @var string
 135    */
 136   public $table;
 137
 138   /**
 139    * The field to join on (right field).
 140    *
 141    * @var string
 142    */
 143   public $field;
 144
 145   /**
 146    * The table we join to.
 147    *
 148    * @var string
 149    */
 150   public $leftTable;
 151
 152   /**
 153    * The field we join to.
 154    *
 155    * @var string
 156    */
 157   public $leftField;
 158
 159   /**
 160    * An array of extra conditions on the join.
 161    *
 162    * Each condition is either a string that's directly added, or an array of
 163    * items:
 164    *   - table(optional): If not set, current table; if NULL, no table. If you
 165    *     specify a table in cached configuration, Views will try to load from an
 166    *     existing alias. If you use realtime joins, it works better.
 167    *   - field(optional): Field or formula. In formulas we can reference the
 168    *     right table by using %alias.
 169    *   - left_field(optional): Field or formula. In formulas we can reference
 170    *     the left table by using %alias.
 171    *   - operator(optional): The operator used, Defaults to "=".
 172    *   - value: Must be set. If an array, operator will be defaulted to IN.
 173    *   - numeric: If true, the value will not be surrounded in quotes.
 174    *
 175    * @see SelectQueryInterface::addJoin()
 176    *
 177    * @var array
 178    */
 179   public $extra;
 180
 181   /**
 182    * The join type, so for example LEFT (default) or INNER.
 183    *
 184    * @var string
 185    */
 186   public $type;
 187
 188   /**
 189    * The configuration array passed by initJoin.
 190    *
 191    * @var array
 192    *
 193    * @see \Drupal\views\Plugin\views\join\JoinPluginBase::initJoin()
 194    */
 195   public $configuration = [];
 196
 197   /**
 198    * How all the extras will be combined. Either AND or OR.
 199    *
 200    * @var string
 201    */
 202   public $extraOperator;
 203
 204   /**
 205    * Defines whether a join has been adjusted.
 206    *
 207    * Views updates the join object to set the table alias instead of the table
 208    * name. Once views has changed the alias it sets the adjusted value so it
 209    * does not have to be updated anymore. If you create your own join object
 210    * you should set the adjusted in the definition array to TRUE if you already
 211    * know the table alias.
 212    *
 213    * @var bool
 214    *
 215    * @see \Drupal\views\Plugin\HandlerBase::getTableJoin()
 216    * @see \Drupal\views\Plugin\views\query\Sql::adjustJoin()
 217    * @see \Drupal\views\Plugin\views\relationship\RelationshipPluginBase::query()
 218    */
 219   public $adjusted;
 220
 221   /**
 222    * Constructs a Drupal\views\Plugin\views\join\JoinPluginBase object.
 223    */
 224   public function __construct(array $configuration, $plugin_id, $plugin_definition) {
 225     parent::__construct($configuration, $plugin_id, $plugin_definition);
 226     // Merge in some default values.
 227     $configuration += [
 228       'type' => 'LEFT',
 229       'extra_operator' => 'AND'
 230     ];
 231     $this->configuration = $configuration;
 232
 233     if (!empty($configuration['table'])) {
 234       $this->table = $configuration['table'];
 235     }
 236
 237     $this->leftTable = $configuration['left_table'];
 238     $this->leftField = $configuration['left_field'];
 239     $this->field = $configuration['field'];
 240
 241     if (!empty($configuration['extra'])) {
 242       $this->extra = $configuration['extra'];
 243     }
 244
 245     if (isset($configuration['adjusted'])) {
 246       $this->adjusted = $configuration['adjusted'];
 247     }
 248
 249     $this->extraOperator = strtoupper($configuration['extra_operator']);
 250     $this->type = $configuration['type'];
 251   }
 252
 253   /**
 254    * {@inheritdoc}
 255    */
 256   public function buildJoin($select_query, $table, $view_query) {
 257     if (empty($this->configuration['table formula'])) {
 258       $right_table = $this->table;
 259     }
 260     else {
 261       $right_table = $this->configuration['table formula'];
 262     }
 263
 264     if ($this->leftTable) {
 265       $left_table = $view_query->getTableInfo($this->leftTable);
 266       $left_field = "$left_table[alias].$this->leftField";
 267     }
 268     else {
 269       // This can be used if left_field is a formula or something. It should be used only *very* rarely.
 270       $left_field = $this->leftField;
 271       $left_table = NULL;
 272     }
 273
 274     $condition = "$left_field = $table[alias].$this->field";
 275     $arguments = [];
 276
 277     // Tack on the extra.
 278     if (isset($this->extra)) {
 279       $this->joinAddExtra($arguments, $condition, $table, $select_query, $left_table);
 280     }
 281
 282     $select_query->addJoin($this->type, $right_table, $table['alias'], $condition, $arguments);
 283   }
 284   /**
 285    * Adds the extras to the join condition.
 286    *
 287    * @param array $arguments
 288    *   Array of query arguments.
 289    * @param string $condition
 290    *   The condition to be built.
 291    * @param array $table
 292    *   The right table.
 293    * @param \Drupal\Core\Database\Query\SelectInterface $select_query
 294    *   The current select query being built.
 295    * @param array $left_table
 296    *   The left table.
 297    */
 298   protected function joinAddExtra(&$arguments, &$condition, $table, SelectInterface $select_query, $left_table = NULL) {
 299     if (is_array($this->extra)) {
 300       $extras = [];
 301       foreach ($this->extra as $info) {
 302         $extras[] = $this->buildExtra($info, $arguments, $table, $select_query, $left_table);
 303       }
 304
 305       if ($extras) {
 306         if (count($extras) == 1) {
 307           $condition .= ' AND ' . array_shift($extras);
 308         }
 309         else {
 310           $condition .= ' AND (' . implode(' ' . $this->extraOperator . ' ', $extras) . ')';
 311         }
 312       }
 313     }
 314     elseif ($this->extra && is_string($this->extra)) {
 315       $condition .= " AND ($this->extra)";
 316     }
 317   }
 318
 319   /**
 320    * Builds a single extra condition.
 321    *
 322    * @param array $info
 323    *   The extra information. See JoinPluginBase::$extra for details.
 324    * @param array $arguments
 325    *   Array of query arguments.
 326    * @param array $table
 327    *   The right table.
 328    * @param \Drupal\Core\Database\Query\SelectInterface $select_query
 329    *   The current select query being built.
 330    * @param array $left
 331    *   The left table.
 332    *
 333    * @return string
 334    *   The extra condition
 335    */
 336   protected function buildExtra($info, &$arguments, $table, SelectInterface $select_query, $left) {
 337     // Do not require 'value' to be set; allow for field syntax instead.
 338     $info += [
 339       'value' => NULL,
 340     ];
 341     // Figure out the table name. Remember, only use aliases provided
 342     // if at all possible.
 343     $join_table = '';
 344     if (!array_key_exists('table', $info)) {
 345       $join_table = $table['alias'] . '.';
 346     }
 347     elseif (isset($info['table'])) {
 348       // If we're aware of a table alias for this table, use the table
 349       // alias instead of the table name.
 350       if (isset($left) && $left['table'] == $info['table']) {
 351         $join_table = $left['alias'] . '.';
 352       }
 353       else {
 354         $join_table = $info['table'] . '.';
 355       }
 356     }
 357
 358     // Convert a single-valued array of values to the single-value case,
 359     // and transform from IN() notation to = notation
 360     if (is_array($info['value']) && count($info['value']) == 1) {
 361       $info['value'] = array_shift($info['value']);
 362     }
 363     if (is_array($info['value'])) {
 364       // We use an SA-CORE-2014-005 conformant placeholder for our array
 365       // of values. Also, note that the 'IN' operator is implicit.
 366       // @see https://www.drupal.org/node/2401615.
 367       $operator = !empty($info['operator']) ? $info['operator'] : 'IN';
 368       $placeholder = ':views_join_condition_' . $select_query->nextPlaceholder() . '[]';
 369       $placeholder_sql = "( $placeholder )";
 370     }
 371     else {
 372       // With a single value, the '=' operator is implicit.
 373       $operator = !empty($info['operator']) ? $info['operator'] : '=';
 374       $placeholder = $placeholder_sql = ':views_join_condition_' . $select_query->nextPlaceholder();
 375     }
 376     // Set 'field' as join table field if available or set 'left field' as
 377     // join table field is not set.
 378     if (isset($info['field'])) {
 379       $join_table_field = "$join_table$info[field]";
 380       // Allow the value to be set either with the 'value' element or
 381       // with 'left_field'.
 382       if (isset($info['left_field'])) {
 383         $placeholder_sql = "$left[alias].$info[left_field]";
 384       }
 385       else {
 386         $arguments[$placeholder] = $info['value'];
 387       }
 388     }
 389     // Set 'left field' as join table field is not set.
 390     else {
 391       $join_table_field = "$left[alias].$info[left_field]";
 392       $arguments[$placeholder] = $info['value'];
 393     }
 394     // Render out the SQL fragment with parameters.
 395     return "$join_table_field $operator $placeholder_sql";
 396   }
 397
 398 }