Add/Remove columns using the updater service

Modifying an existing field api field after the field tables contain data has historically been a challenging and unintuitive set of tasks. Fortunately, the Custom Field module provides a service that makes this incredibly easy!

In your custom module, create or edit an existing .install file and add an update hook. You will need to leverage the methods from the provided service providing arguments as documented. Before you proceed, backup your database and adequately test these updates in a development environment!

As of version 3.1.8, we recommend using the following Drush commands in your local environment which will interactively prompt you for all of the parameters needed, automatically perform the add/remove function and generate an example update hook for deployment to other environments.

Add a new column

1. Enter drush custom_field:add-column
2. Follow the prompts to select options for the new column
3. Copy the generated update hook to your module and deploy to your environment

The addColumn() method provided by the updater service:

/**
  * Adds a new column to the specified field storage.
  *
  * @param string $entity_type_id
  *   The entity type ID. For example: "node".
  * @param string $field_name
  *   The field name. For example: "field_my_field".
  * @param string $new_property
  *   The new property name (column name). For example: "foo".
  * @param string $data_type
  *   The data type to add. Allowed values such as: "integer", "boolean" etc.
  * @param array $options
  *   An array of options to set for new column.
  */
  public function addColumn(string $entity_type_id, string $field_name, string $new_property, string $data_type, array $options = []): void;

Parameters:

• $entity_type_id (string) – A valid content|config entity type machine name containing the custom field.
• $field_name (string) – The machine name of the existing custom field.
• $new_property (string) – The machine name of the subfield to add.
• $data_type (string) – The plugin id of the subfield to create. See plugin options.
• $options (array) – An array of options to set for the new column.
  • max_length (int)
    • Applicable plugins: string, telephone
  • unsigned (bool)
    • Applicable plugins: integer, float, decimal
  • size (string)
    • Applicable plugins: integer, float
    • Allowed values: tiny, small, medium, big, normal
  • precision (int)
    • Applicable plugins: decimal
  • scale (int)
    • Applicable plugins: decimal
  • target_type (string) – A valid content|config entity type machine name.
    • Applicable plugins: entity_reference,
  • datetime_type (string)
    • Applicable plugins: datetime, daterange
    • Allowed values: date, datetime

Remove an existing column

1. Enter drush custom_field:remove-column
2. Follow the prompts to select options for the column to remove
3. Copy the generated update hook to your module and deploy to your environment

The removeColumn() method provided by the updater service:

/**
  * Removes a column from the specified field storage.
  *
  * @param string $entity_type_id
  *   The entity type ID.
  * @param string $field_name
  *   The field name.
  * @param string $property
  *   The name of the column to remove.
  */
  public function removeColumn(string $entity_type_id, string $field_name, string $property): void;

Example Update Hooks

The following examples demonstrate how to use the updater service to add and remove columns from custom_field. These examples would be placed in a .install file in your module. These examples would normally be generated by running the applicable drush commands above.

Adding a new column

/**
 * Add a new column to custom_field.
 */
function my_module_update_9001(): void {
  /** @var \Drupal\custom_field\Service\UpdateManagerInterface $update_manager */
  $update_manager = \Drupal::service('custom_field.update_manager');
  $update_manager->addColumn('node', 'field_custom', 'test_decimal', 'decimal', ['scale' => 3, 'precision' => 6]);
}

Removing a column

/**
 * Remove a column from custom_field.
 */
function my_module_update_9002(): void {
  /** @var \Drupal\custom_field\Service\UpdateManagerInterface $update_manager */
  $update_manager = \Drupal::service('custom_field.update_manager');
  $update_manager->removeColumn('node', 'field_custom', 'test_string');
}