Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Upgrading to version 4

Last updated on
15 June 2025

Overview

Version 4 of the Menu Migration module introduces significant changes. Therefore, upgrading to this version requires caution and manual intervention.

You can directly upgrade to version 4 from any previous version (1, 2, or 3). However, carefully follow the instructions below to ensure a smooth transition.

What Changed in Version 4

This section highlights the major differences introduced in version 4. For comprehensive information about all features and changes in version 4, refer to the module's main guide.

Settings Form Changes

Version 3 or Lower

In version 3 and earlier, a global Settings Form was available at /admin/config/development/menu-migration. This form allowed users to configure the default export and import file path.

Version 4

The global Settings Form previously located at /admin/config/development/menu-migration has been removed in version 4. The underlying configuration (menu_migration.settings) is permanently deleted during the drush updb process.

This functionality has been replaced by Configuration Entities. However, a similar way to quickly configure direct importing and exporting of menus is available at /admin/config/development/menu-migration/quick-action-settings using the Quick Action Settings.

Previously, only the file path was configurable in the global settings. Now, the Quick Action Settings allow you to configure both the default file path and the default format for quick imports and exports.

Export Path Changes

More about Menu Exports and Quick Exports.

Version 3 or lower

In version 3 and earlier, the export process automatically created subdirectories based on the site during exports. Each menu's JSON file was placed within a folder named after the menu's machine name. This structure prevented having multiple menu exports in the same directory.

For example, if your global export path was set to ../config/menu_migration and you exported the "Main navigation" (main) menu on the default site, the resulting file structure would be:

../config/menu_migration/sites/default/main/main.json

Version 4

In version 4, the export path is no longer a global configuration (except when using the Quick Action Settings for quick exports). It no longer automatically creates extra subdirectories during the export process.

When using the Menu Export's Codebase Destination, the export path is now defined at the Configuration Entity level, and the specified path will be used directly for exports. This allows you to have multiple menu exports within the same folder.

For example, if you define a Menu Export using the Codebase Destination, select the JSON format, set the export path to ../config/menu_migration/my_menus, and choose to export both the "Main navigation" (main) and "Footer" (footer) menus, the resulting files will be:

../config/menu_migration/my_menus/main.json
../config/menu_migration/my_menus/footer.json

Import path Changes

More about Menu Imports and Quick Imports.

Version 3 or lower

In version 3 and earlier, there was no separate configuration for the import path. The module automatically used the globally configured Export path for imports as well, applying a similar directory structure logic.

For example, if the global Export path was set to ../config/menu_migration, and you were importing the "Main navigation" menu, the module would look for the import file at a path like:

../config/menu_migration/sites/SITENAME/main/main.json

where SITENAME would be the identifier of your site.

Version 4

In version 4, the import path is now configurable at the Menu Import entity level (or within the Quick Action Settings form for quick imports) when using the Codebase Source. The logic here mirrors the changes made to the export path.

For example, if you define a Menu Import using the Codebase Source, select the JSON format, set the import path to ../config/menu_migration/my_menus, and choose to import the "Main navigation" (main) and "Footer" (footer) menus, the module will expect to find the import files at:

../config/menu_migration/my_menus/main.json
../config/menu_migration/my_menus/footer.json

Drush command Changes

More about Drush Commands.

Version 3 or lower

Version 3 and earlier provided two Drush commands for menu migration:

  • drush menu_migration:export (alias drush mme): For exporting menus.
  • drush menu_migration:import (alias drush mmi): For importing menus.

These commands did not require confirmation before execution, and they accepted one or more menu IDs as arguments, separated by commas.

Version 4

Version 4 introduces a total of six Drush commands. You can find more detailed information about all available commands here.

The behavior of the drush menu_migration:export (alias drush mme) and drush menu_migration:import (alias drush mmi) commands has changed:

  • Confirmation: These commands now require confirmation before execution. If you are using them in Continuous Integration (CI) scripts, you will likely need to add the -y option to bypass the confirmation prompt. For example: 
    drush menu_migration:export my_export_id -y
drush mme my_export_id -y
drush menu_migration:import my_import_id -y
drush mmi my_import_id -y
  • Arguments: These commands now accept only one argument, which is the ID of the Menu Export entity (for drush menu_migration:export) or the ID of the Menu Import entity (for drush menu_migration:import). They no longer accept multiple menu IDs separated by commas.

For users who prefer the version 3 Drush command behavior (no Configuration Entities required, accepting menu IDs, and with confirmation), version 4 provides new "quick" export and import commands. To continue using a similar workflow, you should use these new commands, which have different names:

drush menu_migration:quick-export (alias drush mmqe)
drush menu_migration:quick-import (alias drush mmqi)

  1. Ensure Configuration Sync: If you use Drupal's configuration management, it's good practice to ensure your configuration is synchronized with your codebase before any major update.

  2. Note Existing Global Settings: In version 3 or earlier, take note of the Export Path configured at Configuration → Development → Menu Migration → Settings. You might want to reuse or adapt this path.

  3. Update Module via Composer: In your project root, run the following command to update the Menu Migration module to version 4:

    composer require drupal/menu_migration:^4 -W

    The -W flag is optional and will update dependencies if necessary. You can preview the changes by running composer require drupal/menu_migration:^4 -W --dry-run first.

  4. Run Database Updates: Execute the database updates using Drush:

    drush updb

    This process will remove the menu_migration.settings configuration.

  5. Important Note on Export Paths: Be aware that version 4 no longer automatically generates subdirectories per subsite, nor does it enforce that each menu file resides in its own subdirectory (named after the menu). Regardless of whether you choose to use the Quick Action Settings or the more flexible Menu Export entities, you will need to explicitly configure the exact directory where one or more menu export files will be saved.

  6. (Optional) Configure Quick Action Settings for Version 3-like Behavior: If you prefer to continue with a workflow similar to version 3 for quick exports and imports, navigate to Configuration → Development → Menu Migration → Quick Action Settings. Here, you can configure:

    • Default Export Directory Path: Set the default directory where quick exports will be saved, and where the module will look for files during quick imports.
    • Default Format: Choose the default format (e.g., JSON, YAML) for quick exports and imports.

    If you configure these settings, you can then use the new "quick" Drush commands (refer to the Drush command changes section) which operate similarly to the version 3 commands, accepting menu IDs.

    Steps 6 and 7 can be skipped if you prefer to use this feature.

  7. Create Menu Exports (Codebase Destination - Optional): If you need more granular control over your menu migrations or want to leverage the features of Configuration Entities (e.g., different export formats per export, including in configuration), navigate to Configuration → Development → Menu Migration → Menu Exports and create new Menu Export configurations. For each export:

    • Set the Destination plugin to Codebase.
    • Define the Export path to the desired directory for your exported menu files.

  8. Create Menu Imports (Codebase Source - Optional): Similarly, if you need more control over imports using Configuration Entities, navigate to Configuration → Development → Menu Migration → Menu Imports and create new Menu Import configurations. For each import:

    • Set the Source plugin to Codebase.
    • Define the Import path to the directory containing your menu files.

  9. Update Drush Usage: If you use Drush commands in scripts or your workflow, be aware of the following:

    • The drush menu_migration:export (alias drush mme) and drush menu_migration:import (alias drush mmi) commands now expect Menu Export and Menu Import entity IDs.
    • For a version 3-like experience, use the new "quick" Drush commands (if you configured the Quick Action Settings): drush menu_migration:quick-export (alias drush mmqe) and drush menu_migration:quick-import (alias drush mmqi).

  10. Export Configuration: Once you have configured your preferred migration methods (Quick Actions and/or Menu Exports/Imports), export your Drupal configuration:

    drush cex

    You are now ready to use version 4 of the Menu Migration module!

Help improve this page

Page status: No known problems

You can: