Drupal Module Upgrader

The Drupal Module Upgrader is a Drush command that helps you update your modules from Drupal 7 to Drupal 8.

Indeed, Neo.

Command line use

Drupal Module Upgrader, or DMU from here on in, has two main modes of operation:

Analyze mode (drush dmu-analyze MODULE_NAME)

In this mode, DMU will scan your Drupal 7 module and look for things that need to be changed in order to port the module to Drupal 8, and generate a nice-looking report that outlines the required changes and links off to the relevant API change records in each case that tell you how to do the port yourself.

Upgrade mode (drush dmu-upgrade MODULE_NAME)

In upgrade mode, DMU will try to convert as much of your module to Drupal 8 as it can. The module code will be upgraded in place, so for example .info files converted to .info.yml, hook_menu() converted to controllers, etc. The goal is not to get the module 100% working, but rather to save you a ton of time on any D7 => D8 module port. However, in some cases it can get you far enough along that you can turn the module on and perhaps even see some basic things working (such as settings forms and blocks)!

NOTE: It is highly recommended that if you're brand new to Drupal 8 you run DMU in analyze mode only at first, and try and fix the things yourself manually. You'll be able to read the background behind many of the changes in D8, learn a lot about D8 in the process, and it will make future module porting much easier.

DMU supports converting Drupal 7 modules to Drupal 8 only. There are no plans to support Drupal 6 modules. To convert module code from Drupal 6 to Drupal 7, see the Coder Upgrade project.

Installation

DMU is a Drush command for Drupal 8, so you will need a modern version of Drush (see the install docs) and Composer. Download DMU and install it like any normal module, then run composer install from within the DMU directory to install dependencies. (If you're using Composer Manager, you'll want to run drush composer-manager install instead.)

Or, if you're that whole blurb reeks of effort and you just want to copy/paste some stuff:

cd /PATH_TO_DRUPAL_8_WEB_ROOT/modules/
drush dl drupalmoduleupgrader
cd drupalmoduleupgrader
composer install
drush en drupalmoduleupgrader -y

Analyzing a Drupal 7 module

Move the Drupal 7 module into your Drupal 8 root (in the modules directory). Then run drush dmu-analyze MODULE_NAME.

If all goes well, a report will be generated in the module's directory, called upgrade-info.html. Open that and peruse at your leisure :)

Upgrading a Drupal 7 module

Same deal, except run drush dmu-upgrade MODULE_NAME instead. Your module's code will be updated in-place: git add . ; git diff --cached to see what it changed.

If desired, you can also run drush dmu-clean MODULE_NAME and this will delete any old D7 code that was already ported (e.g. your old .info file), providing the DMU conversion plugin supports a cleanup operation.

Command-line options

dmu-upgrade and dmu-analyze have the same command line options. Note that "path" option may not work effectively - the most reliable location is in the root level of /modules. It may be helpful to skip or only run certain conversions, if all of them are not working.

drush help dmu-upgrade
Upgrades a Drupal 7 module to Drupal 8.

Examples:
 drush dmu-upgrade pants   Upgrade whatever can be automatically upgraded in the pants module.

Arguments:
 module    The machine name of a Drupal 7 module.

Options:
 --backup    If set, creates a backup copy of the module before conversion.
 --only=<HookMenu,VariableAPI,BlockInfo>    A comma-separated list of converters to run, excluding all others.
 --path=<drupal/modules/foobaz>    Optional path to the target module. Will be determined automatically if omitted.
 --skip=<HookInit,HookExit>    A comma-separated list of converters to skip.

Interpreting error messages when dmu-upgrade fails

When DMU runs into code it can't process correctly, it may leave some code converted successfully, and it may throw a stack trace indicating how it reached the point of the error. This can help narrow down the problem by showing which hook it couldn't convert. Searching for "Hook" can help you. In this instance the problem happened during HookPermission (thus you could try skipping that hook using the skip option above).

Error: Undefined class constant 'DUMP_EXCEPTION_ON_INVALID_TYPE' in Drupal\Component\Serialization\YamlSymfony::encode() (line 22 of                      [error]
/site/web/core/lib/Drupal/Component/Serialization/YamlSymfony.php) #0 /site/web/core/lib/Drupal/Component/Serialization/Yaml.php(27):
Drupal\Component\Serialization\YamlSymfony::encode(Array)
#1 /site/web/modules/custom/drupalmoduleupgrader/src/ConverterBase.php(167): Drupal\Component\Serialization\Yaml::encode(Array)
#2 /site/web/modules/custom/drupalmoduleupgrader/src/Plugin/DMU/Converter/HookPermission.php(23):
Drupal\drupalmoduleupgrader\ConverterBase->writeInfo(Object(Drupal\drupalmoduleupgrader\Target), 'permissions', Array)
#3 /site/web/modules/custom/drupalmoduleupgrader/drupalmoduleupgrader.drush.inc(313):
Drupal\drupalmoduleupgrader\Plugin\DMU\Converter\HookPermission->convert(Object(Drupal\drupalmoduleupgrader\Target))

Another example of an error during the dmu-upgrade process is

Error at line 3:1: unexpected < operator!

This can be caused by Twig debugging being enabled - disable Twig debugging.

You can also check the DMU issue queue for similar error messages. If filing a new issue please include enough information to reproduce the problem, and always be sure to clear caches with drush cr first!