How to Migrate your Extension to Magento 2?

In this blog post I will show you a sample how to port your existing Magento 1 extension to the brand-new Magento 2 based on our Recolize Recommendation Engine extension for Magento 2.

While Magento 2 was publically released in December 2015 more and more extension providers are migrating their extension to the new platform. As the whole architecture of Magento 2 is different than in the first version the steps required for making the extension compatible with the new Magento version differ a lot from extension to extension depending on the complexity and used parts of the Magento system.

Most of the steps described here are taken from these sources:

(Generally for sources on the web it is important to look at the creation date as a lot has changed since the first official Magento 2 beta version.)

0. General hints

Magento 2 now has a nice command line tool bin/magento (comparable to the well-known n98-magerun in Magento 1) which offers lots of cool commands.

Assure to set the Magento 2 Developer mode as described here with

bin/magento deploy:mode:set developer

as well as to disable the Full Page Cache (FPC). This assures that e.g. static files are not cached which makes developing extensions a lot easier.

Magento 2 now ships with XSD files to validate your XML files. This can be integrated directly into PHPStorm which is a very handy feature. Just execute the following command (see here):

bin/magento dev:urn-catalog:generate .idea/misc.xml

Please note that there are also automatic converting solutions like the Unirgy Magento 2 Converter but we will do that manually for sample reasons.


The required steps for migrating the extension are:

  1. Create a skeleton Magento 2 extension
  2. Migrate system settings, localizations
  3. Migrate extension template stuff
  4. Migrate extension product feed generation logic

1. Create the skeleton Magento 2 extension

As the whole architecture and therewith also the file structure is different from Magento 1 it is advisable to create a completely new extension package.
The basic file structure looks like as follows:

After creating the basic file structure you can execute

bin/magento module:enable && bin/magento setup:upgrade

and the extension is now installed which you can easily verify by visiting the Admin panel Stores > Configuration > Advanced > Advanced

2. Migrating system settings

This task means mainly converting the old system.xml file into the new Magento 2 XSD format. As you can see from the picture below that shows the comparison between old and new format the changes can easily be understood:

For localization files it’s even easier as you only have to move them to the i18n folder.

3. Migrating extension logic

Next step is to migrate the existing logic from our Magento 1 extension.
Basically our Recolize Recommendation Engine extension does the following to major things:

  1. Add the layout handles for integrating our JavaScript snippet and the Recolize JavaScript parameters on special pages like cart, product detail page, etc.
  2. Update the user information in the cookie on login/logout.
  3. Periodically generate the product feed (see chapter 4).

As these migration tasks are very specific to our Recolize Magento extension it’s up to the reader to check out the necessary steps and differences with Magento 1.

4. Migrate extension product feed generation

In Magento 1 we relied on the Magento default Dataflow extension to generate our product export feed because there many flaws have already been implemented and made some customizations (see my earlier post about Dataflow customizations).

As Magento 2 only ships with the ImportExport module and that functionality is very limited we decided to implement our own feed generation methods. But that’s part of another blog post..

And basically that’s it! As you can see for simple extensions like ours that do not go deep into the Magento internals it is mostly re-writing some XML stuff into the new format and adapting to the new dependency injection logic.

Now it’s time to try out yourself. See our Recolize Magento 2 extension for a sample.

How to Migrate your Extension to Magento 2?