Available Hooks and/or Events

Overview

The Menu Migration module provides a MenuImportEvent that fires for each menu item before it is imported. This event allows you to inspect and modify menu item data during the import process.

Event Definition: menu_migration/src/Event/MenuImportEvent.php

Example Implementation: menu_migration/src/EventSubscriber/ImportSubscriber.php

MenuImportEvent

The MenuImportEvent is dispatched before each menu item is imported, providing an opportunity to alter menu item properties such as links, titles, weights, and other attributes.

Event Constant

• MenuImportEvent::IMPORT_MENU_ITEM - The event name to subscribe to

Available Methods

The MenuImportEvent provides the following methods:

• getMenuItem() - Returns the complete menu item array being imported
• getMenuName() - Returns the machine name of the menu the item is being imported to (added in version 4.1.0)
• getNestedValue(array $parents) - Retrieves a nested value from the menu item using an array of parent keys
• setNestedValue(array $parents, mixed $value) - Sets a nested value in the menu item using an array of parent keys

Creating an Event Subscriber

To respond to menu import events, create an event subscriber in your custom module:

Step 1: Create the Event Subscriber Class

Create a file at MY_MODULE/src/EventSubscriber/MenuImportSubscriber.php:

<?php

namespace Drupal\MY_MODULE\EventSubscriber;

use Drupal\menu_migration\Event\MenuImportEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

/**
 * Alters menu items before they are imported.
 */
class MenuImportSubscriber implements EventSubscriberInterface {

  /**
   * {@inheritdoc}
   */
  public static function getSubscribedEvents(): array {
    $events[MenuImportEvent::IMPORT_MENU_ITEM][] = ['onMenuItemImport'];
    return $events;
  }

  /**
   * Acts on a menu item before it's imported.
   *
   * @param \Drupal\menu_migration\Event\MenuImportEvent $event
   *   The MenuImportEvent.
   */
  public function onMenuItemImport(MenuImportEvent $event): void {
    // Example: Get the current link URI
    $uri = $event->getNestedValue(['link', 'uri']);
    
    // Example: Modify the link URI
    $newUri = str_replace('old-domain.com', 'new-domain.com', $uri);
    $event->setNestedValue(['link', 'uri'], $newUri);
    
    // Example: Get the menu name (available in 4.1.0+)
    $menuName = $event->getMenuName();
    
    // Add your custom logic here
  }

}

Step 2: Register the Event Subscriber

Register your event subscriber in MY_MODULE.services.yml:

services:
  MY_MODULE.menu_import_subscriber:
    class: Drupal\MY_MODULE\EventSubscriber\MenuImportSubscriber
    tags:
      - { name: event_subscriber }

Step 3: Clear Cache

After creating the event subscriber, clear Drupal's cache to register the service:

drush cr

Settings-Based Replacements

For common use cases like replacing domain names or paths during import, the module supports a settings-based configuration approach that doesn't require writing custom code.

This is particularly useful when:

• Working with multisite installations where menu links need different domains per site
• Importing the same menu export into multiple environments (development, staging, production)
• You want to maintain a single source of truth for menu exports while adapting links per environment

Configuration

Add the following configuration to your site's settings.php or settings.local.php:

// Menu Migration replacements
$settings['menu_migration_replacements'] = [
  // Replace domain in menu link URIs
  [
    'parents' => ['link', 'uri'],
    'method' => 'str_replace',
    'arguments' => [
      'example.com',           // Search for this
      'local.example.com',     // Replace with this
      '[SUBJECT]',             // The current value (required token)
    ],
  ],
  // Replace paths in menu links
  [
    'parents' => ['link', 'uri'],
    'method' => 'str_replace',
    'arguments' => [
      '/old-path',
      '/new-path',
      '[SUBJECT]',
    ],
  ],
  // Add more replacement rules as needed
];

Configuration Parameters

• parents - An array of nested keys identifying which menu item property to modify (e.g., ['link', 'uri'] for the menu link URL)
• method - A PHP function to apply to the value (e.g., str_replace, preg_replace, strtolower)
• arguments - Arguments to pass to the specified function. Must include the [SUBJECT] token, which will be replaced with the actual value

Common Use Cases

Replace Domain Names

$settings['menu_migration_replacements'] = [
  [
    'parents' => ['link', 'uri'],
    'method' => 'str_replace',
    'arguments' => ['production.example.com', 'dev.example.com', '[SUBJECT]'],
  ],
];

Update Protocol (HTTP to HTTPS)

$settings['menu_migration_replacements'] = [
  [
    'parents' => ['link', 'uri'],
    'method' => 'str_replace',
    'arguments' => ['http://', 'https://', '[SUBJECT]'],
  ],
];

Modify Menu Item Titles

$settings['menu_migration_replacements'] = [
  [
    'parents' => ['title'],
    'method' => 'str_replace',
    'arguments' => ['Production', 'Development', '[SUBJECT]'],
  ],
];