public function Schema::addField in Drupal 8

Same name in this branch

1. 8 core/lib/Drupal/Core/Database/Schema.php \Drupal\Core\Database\Schema::addField()
2. 8 core/lib/Drupal/Core/Database/Driver/sqlite/Schema.php \Drupal\Core\Database\Driver\sqlite\Schema::addField()
3. 8 core/lib/Drupal/Core/Database/Driver/pgsql/Schema.php \Drupal\Core\Database\Driver\pgsql\Schema::addField()
4. 8 core/lib/Drupal/Core/Database/Driver/mysql/Schema.php \Drupal\Core\Database\Driver\mysql\Schema::addField()

Same name and namespace in other branches

1. 9 core/lib/Drupal/Core/Database/Driver/sqlite/Schema.php \Drupal\Core\Database\Driver\sqlite\Schema::addField()

Add a new field to a table.

Parameters

$table: Name of the table to be altered.

$field: Name of the field to be added.

$spec: The field specification array, as taken from a schema definition. The specification may also contain the key 'initial', the newly created field will be set to the value of the key in all rows. This is most useful for creating NOT NULL columns with no default value in existing tables. Alternatively, the 'initial_form_field' key may be used, which will auto-populate the new field with values from the specified field.

$keys_new: (optional) Keys and indexes specification to be created on the table along with adding the field. The format is the same as a table specification but without the 'fields' element. If you are adding a type 'serial' field, you MUST specify at least one key or index including it in this array. See ::changeField() for more explanation why.

Throws

\Drupal\Core\Database\SchemaObjectDoesNotExistException If the specified table doesn't exist.

\Drupal\Core\Database\SchemaObjectExistsException If the specified table already has a field by that name.

Overrides Schema::addField

File

core/lib/Drupal/Core/Database/Driver/sqlite/Schema.php, line 316

Class

Schema

SQLite implementation of \Drupal\Core\Database\Schema.

Namespace

Drupal\Core\Database\Driver\sqlite

Code

public function addField($table, $field, $specification, $keys_new = []) {
  if (!$this
    ->tableExists($table)) {
    throw new SchemaObjectDoesNotExistException("Cannot add field '{$table}.{$field}': table doesn't exist.");
  }
  if ($this
    ->fieldExists($table, $field)) {
    throw new SchemaObjectExistsException("Cannot add field '{$table}.{$field}': field already exists.");
  }
  if (isset($keys_new['primary key']) && in_array($field, $keys_new['primary key'], TRUE)) {
    $this
      ->ensureNotNullPrimaryKey($keys_new['primary key'], [
      $field => $specification,
    ]);
  }

  // SQLite doesn't have a full-featured ALTER TABLE statement. It only
  // supports adding new fields to a table, in some simple cases. In most
  // cases, we have to create a new table and copy the data over.
  if (empty($keys_new) && (empty($specification['not null']) || isset($specification['default']))) {

    // When we don't have to create new keys and we are not creating a
    // NOT NULL column without a default value, we can use the quicker version.
    $query = 'ALTER TABLE {' . $table . '} ADD ' . $this
      ->createFieldSql($field, $this
      ->processField($specification));
    $this->connection
      ->query($query);

    // Apply the initial value if set.
    if (isset($specification['initial_from_field'])) {
      if (isset($specification['initial'])) {
        $expression = 'COALESCE(' . $specification['initial_from_field'] . ', :default_initial_value)';
        $arguments = [
          ':default_initial_value' => $specification['initial'],
        ];
      }
      else {
        $expression = $specification['initial_from_field'];
        $arguments = [];
      }
      $this->connection
        ->update($table)
        ->expression($field, $expression, $arguments)
        ->execute();
    }
    elseif (isset($specification['initial'])) {
      $this->connection
        ->update($table)
        ->fields([
        $field => $specification['initial'],
      ])
        ->execute();
    }
  }
  else {

    // We cannot add the field directly. Use the slower table alteration
    // method, starting from the old schema.
    $old_schema = $this
      ->introspectSchema($table);
    $new_schema = $old_schema;

    // Add the new field.
    $new_schema['fields'][$field] = $specification;

    // Build the mapping between the old fields and the new fields.
    $mapping = [];
    if (isset($specification['initial_from_field'])) {

      // If we have a initial value, copy it over.
      if (isset($specification['initial'])) {
        $expression = 'COALESCE(' . $specification['initial_from_field'] . ', :default_initial_value)';
        $arguments = [
          ':default_initial_value' => $specification['initial'],
        ];
      }
      else {
        $expression = $specification['initial_from_field'];
        $arguments = [];
      }
      $mapping[$field] = [
        'expression' => $expression,
        'arguments' => $arguments,
      ];
    }
    elseif (isset($specification['initial'])) {

      // If we have a initial value, copy it over.
      $mapping[$field] = [
        'expression' => ':newfieldinitial',
        'arguments' => [
          ':newfieldinitial' => $specification['initial'],
        ],
      ];
    }
    else {

      // Else use the default of the field.
      $mapping[$field] = NULL;
    }

    // Add the new indexes.
    $new_schema = array_merge($new_schema, $keys_new);
    $this
      ->alterTable($table, $old_schema, $new_schema, $mapping);
  }
}