How to fully port a module to OXID eShop 6

This post describes all changes necessary to port modules originally written for OXID eShop 5.3.x and 4.10.x, to OXID eShop 6.

As a basis, please first read the blog post “How to (quickly) port a module to OXID eShop 6” and go through all the steps mentioned there. Please make sure you have successfully re-factored your code, your module is working as expected and all the tests have been run successfully for OXID eShop 6. You may now continue, adapt and future proof the code of your module according to the standards used in OXID eShop v6.

Adapt your code style

Please note that from OXID eShop 6 on, we will use PSR-0 and PSR-4 standards in the core code. Our Codesniffer might be a helpful tool to achieve this goal.

Remove code using the backwards compatibility layer

In order to minimize the upgrade effort for module developers and shop operators, a so called backwards compatibility layer was introduced in OXID eShop 6.

The backwards compatibility layer assures two things:

  • You still can use the old class names (e.g. oxarticle) anywhere in the code
  • You can still use old controller names and pass them as a value for the GET or POST parameter cl in a HTTP request. E.g. in the URL like <your shop URL>/index.php?cl=yourcustomcontrollerclass

However, using the backwards compatibility layer will lead to a slight performance drop, and this is the reason why you only want to use it in your modules during a transition period. This means, that the backwards compatibility layer will be removed at some point in the future (which is not defined yet), hence you might want to prepare your modules to work without it.

1. Remove the usage of old class names and replace them by the new class names

The first thing to do is removing the usage of old OXID eShop class names and replace them with the new OXID eShop class names.
You will find a mapping from old to new class names in the BackwardsCompatibilityClassMap.

You might have used the old class names

  • when creating instances of classes with new or oxNew
  • when calling static class methods, properties or class constants
  • when defining inheritance
  • in type hints
  • in PHPDoc blocks
  • in comments
  • in metadata.php of your modules

Hint: use a clever script with some regex together with manual cleanup to fix the source code of modules in a huge shop installation without too much effort. Please keep in mind that the old class names were not really case sensitive, hence you may have to search for appearance of oxArticle, OxArticle or oxarticle, etc.

After this step, everything should work as usual. Metadata version 1.1 is compatible with the usage of namespaces. Now you can continue with the next steps.

2. Add your controller keys to metadata.php

The controller names in OXID eShop versions prior to v6 were identical to the class names, defined somewhere in metadata.php.

In OXID eShop 6 a new concept called controller keys was introduced. In this concept, a mapping from keys to classes is used.
For OXID eShop’s own controllers, the map is defined in a class called ShopControllerMapProvider. For your modules, this map has to be defined in a new section called controllers in metadata.php. Along with this change, a new major version of metadata was released. As it contains more changes I will explain all of them in the next section.

Switch to metadata version v2.0

For a fully compliant module with OXID eShop 6, it is mandatory to use metadata version 2.0.
There were several changes in metadata version 2.0, which directly or indirectly affect your code.

  • It permits only fully qualified class names, including its namespace
  • The section controllers was introduced
  • The section files was removed

Due to these changes, you have to perform the following tasks:

1. Introduce namespaces in your module

If not already done, you should re-factor your code to use PHP namespaces. To avoid naming clashes, please check out this page for already registered vendor namespaces. Please register your own namespace with a simple pull request on GitHub.

2. Add controllers to the metadata section controllers

This might not be applicable to your module, but if you are passing you own controllers in the GET or POST request parameter cl, you need to add them to a dedicated section in metadata.php, which was introduced with v2.0. In this controllers section you can define a controller key and map it to a controller class:

Of course, you can also use the old class name as controller key, so you don’t have to update your templates. Like before the controller class name, now the controller key has to be unique throughout the shop installation including all sub-shops (EE). Additionally, the controller classes have to be unique, hence you can’t let two controller keys pointing to the same class.

3. Remove the section files

Remove the entire metadata section files as it will not be evaluated anymore. This section took care for loading your custom classes, which were not extending any OXID eShop class. The autoloading of the module files isn’t done by OXID eShop any longer, it was delegated to the composer autoloader. From metadata version 2.0 on, you have to provide a valid composer.json file in which you have to define a PSR-4 compatible autoload entry.

Provide a valid composer.json for your module

Autoloading of the module files is now delegated to composer. This has some consequences: first of all, you have to register a valid PSR-4 compliant namespace in the composer.json file of the module. And as a second step, the users of your module have to install the module via composer in order to provide the local composer installation with the required information about namespaces and paths.

1. Take care of module class autoloading

2. Make your module installable via composer

In this article you will find detailed information about how to make module installable via composer. There are several ways to deliver the source code of your modules anyway:

  • submit the module to This will make your source code publicly available, a standard method used by many open source projects.
  • Besides, there are ways that will allow to keep your source code private, like or a private git repository.
  • You can even provide a zip file via OXID eXchange or any other download platform.

It is important to point out that – regardless the way you deliver the module source code – users will always have to install the module via composer as this is the only way to ensure that all module dependencies are met and that the proper autoloading entries are created. However, it is still possible to upload the module into the module folder but before it can be activated, composer has to be run.


There are several things to do to fully port your modules, and you will be gratified by an easier upgrade path, a slightly improved performance and a state-of-the-art codebase. We will keep publishing blog posts with in-depth information about module related topics, stay tuned.


1.80 avg. rating (42% score) - 5 votes

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *