Same name and namespace in other branches

1. main core/lib/Drupal/Core/Database/Query/Upsert.php \Drupal\Core\Database\Query\Upsert::fields()

Adds a set of column->value pairs to be inserted.

This method may only be called once. Calling it a second time will be ignored. To queue up multiple sets of values to be inserted at once, use the values() method.

Parameters

array<string|int,string|\Drupal\Core\Database\Query\UpsertUpdateExpression>|array<string,string|int|float|bool|array> $fields: An array of columns on which to insert. This array may be indexed or associative. If indexed, the array is taken to be the list of columns. If associative, the keys of the array are taken to be the columns and the values are taken to be corresponding values to insert. If a $values argument is provided, $fields must be indexed. In the indexed form, an entry may map a column name to an UpsertUpdateExpression. When the row already exists, that expression is run for the column in place of overwriting it with the insert value.

list<string|int|float|bool|array> $values: (optional) An array of values to insert into the database. The values must be specified in the same order as the $fields array.

Return value

$this The called object.

Throws

\InvalidArgumentException If an update expression is not keyed by its column name, or if a column name maps to an insert value while the $fields array is not fully associative.

Overrides InsertTrait::fields

File

core/lib/Drupal/Core/Database/Query/Upsert.php, line 95

Class

Upsert

General class for an abstracted "Upsert" (UPDATE or INSERT) query operation.

Namespace

Drupal\Core\Database\Query

Code

public function fields(array $fields, array $values = []) : static {
  if (empty($this->insertFields)) {
    if (empty($values)) {
      $isFieldsAssociative = TRUE;
      array_walk($fields, function (mixed $value, int|string $key) use (&$isFieldsAssociative) : void {
        if (is_numeric($key) || is_string($key) && $value instanceof UpsertUpdateExpression) {
          $isFieldsAssociative = FALSE;
        }
      });
      if ($isFieldsAssociative) {
        $values = array_values($fields);
        $fields = array_keys($fields);
      }
    }
    foreach ($fields as $key => $def) {
      if ($def instanceof UpsertUpdateExpression) {
        if (!is_string($key)) {
          throw new \InvalidArgumentException('An update expression must be keyed by its column name.');
        }
        $this->insertFields[] = $key;
        $this->updateExpressions[$key] = $def;
      }
      elseif (is_string($key)) {
        throw new \InvalidArgumentException(sprintf('The entry for "%s" must be a column name or an update expression keyed by column name. Pass insert values via the $values argument or the values() method.', $key));
      }
      else {
        $this->insertFields[] = $def;
      }
    }
    if (!empty($values)) {
      $this->values($values);
    }
  }
  return $this;
}

---