Add process plugins for HTML processing using DOMDocument objects

New process plugins

There are several process plugins that can be used to process HTML fields:

• dom (since 8.x-4.2): Convert a string to a DOMDocument object and back.
• dom_str_replace (since 8.x-4.2): Similar to the str_replace plugin for attributes of HTML elements.
• dom_apply_styles (since 8.x-5.0): Replace specified elements with markup configured in the Editor module.
• dom_migration_lookup (since 8.x-5.0): Similar to the migration_lookup plugin for links in a text field.

Sample migration code

To use these new plugins,

• Apply the dom plugin with method: import to create a DOMDocument object.
• Apply one or more process plugins that expect a DOMDocument object as input and return the modified object.
• Apply the dom plugin with method: export to convert the DOMDocument object to a string.

For example,

process:
  'body/value':
    -
      plugin: dom
      method: import
      source: 'body/0/value'
    -
      plugin: dom_str_replace
      mode: attribute
      xpath: '//a'
      attribute_options:
        name: href
      search: 'oldsite.com'
      replace: 'newsite.com'
    -
      plugin: dom_apply_styles
      format: full_html
      rules:
        -
          xpath: '//b'
          style: Bold
    -
      plugin: dom
      method: export

This will search for all <a> elements (specified by the XPath expression //a) and replace "oldsite.com" with "newsite.com" in the href attribute. Then it will search for all <b> elements (specified by the XPath expression //b) and replace them with the "Bold" style as configured in the Editor module for the full_html text format.

Note about xpath expression

The original config key for the xpath expression was expression (with the addition of dom_str_replace in 8.x-4.2) -- BUT, it was later changed to xpath (with the addition of dom_migration_lookup in 8.x-5.0). See also: Use migration lookup on text fields, comment 12-on.

Adding another process plugin

To add a process plugin that can be used in this framework, extend the class DomProcessBase. Then start the transform() method as follows:

  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
    $this->init($value, $destination_property);

    // Your code goes here.

    return $this->document;
  }

The init() method will validate that $value is a DOMDocument object and then

    $this->document = $value;
    $this->xpath = new \DOMXPath($this->document);

Your code can use $this->xpath->query($xpath_expression) to create a DOMNodeList representing HTML elements matching the XPath expression.