Modifying Source Plugins

Most source plugins are configurable, and some can be changed using hooks.

When a migration declares its source, any keys other than plugin are passed to the source plugin as configuration. For example (d7_node_settings):

source:
  plugin: variable
  variables:
    - node_admin_theme
  source_module: node

The variables and source_module keys are configuration for the variable source plugin.

Most source plugins

Most source plugins extend \Drupal\migrate\Plugin\migrate\source\SourcePluginBase, so they support the following configuration (all optional):

• cache_counts
• cache_key
• skip_count
• track_changes
• high_water_property

See the API documentation for more information.

SQL source plugins

Most SQL source plugins extend \Drupal\migrate\Plugin\migrate\source\SqlBase, so they support the following configuration (all optional):

• database_state_key
• key
• target
• batch_size
• ignore_map

The first three determine which database provides the source data. Setting batch_size is important when there are many rows of data (for example, 100K in a user migration). Setting ignore_map to TRUE disables an optimization that can sometimes cause problems.

See the API documentation for more information.

Altering the query

The method SqlBase::prepareQuery() adds two tags to the query:

1. 'migration'
2. 'migration_' . $migration->id()

These tags can be used to target the query using hook_query_tag_alter(). For example, the hook can be implemented in mymigration.module:

<?php

use Drupal\Core\Database\Query\AlterableInterface;

/**
 * Implements hook_query_TAG_alter() for the migrate tag.
 */
function mymigration_query_migrate_alter(AlterableInterface $query): void {
  if ($query->hasTag('migrate_d7_node:article')) {
    $query->condition('n.nid', 17, '<');
  }
}

The newer method is to add a class in the Drupal\mymigration\Hook namespace and use the [#Hook()] attribute:

<?php

namespace Drupal\mymigration\Hook;

use Drupal\Core\Database\Query\AlterableInterface;
use Drupal\Core\Hook\Attribute\Hook;

class TagExample {

  /**
   * Implements hook_query_TAG_alter() for the migrate_d7_node:page tag.
   */
  #[Hook('query_migrate_d7_node:page_alter')]
  public function alterPageQuery(AlterableInterface $query): void {
    $query->condition('n.nid', 17, '<');
  }

}

One advantage of the newer method is that you can directly target a query tag that includes a character (such as ':') that is not allowed in a PHP function name.