Namespaces in OXID eShop 6

As you might already know, starting from OXID eShop version 6 we completely stripped down the editions and run them in completely different GitHub repositories in a manner that OXID eShop Community Edition is the basis, additional code for Professional Edition as well as for Enterprise Edition resides in separate repositories on top of the other edition.

This step not only made it possible to actively participate in the development as well as making cross-upgrades between the editions easier. It also cleared the way to make use of modern, state-of-the-art technologies like composer and namespaces for PHP classes in OXID eShop for good reasons:

  • comply with PSR-1, PSR-2, PSR-4 coding standards
  • the usage of composer is possible, including many features like the composer autoloader. This results e.g. in performance improvements.
  • namespaces are a de facto standard in the PHP world

And of course, the introduction of namespaces also led to a number of questions and decisions I want to explain in the following section:

Editions and unified namespaces

Each OXID eShop edition is now located in its own namespace. For example, OXID eShop Community Edition is located in the namespace OxidEsales\EshopCommunity.

OXID eShop editions inherit from each other. Community Edition is a subset of Professional Edition where Professional Edition is a subset of OXID eShop Enterprise Edition. This means, for example, the namespace OxidEsales\EshopEnterprise\Application\Model\Article inherits from OxidEsales\EshopProfessional\Application\Model\Article as you can see in figure 1:

Example of inheritance in an OXID eShop Enterprise Edition for the class Article

Figure 1: Example of inheritance in an OXID eShop Enterprise Edition for the Article class

Introducing namespaces also leads to the deprecation of the former non-namespaced classes like oxarticle. The new namespaced class Article from now on replaces the deprecated (for backwards compatibility) class oxarticle.

Module developers usually extend OXID eShop classes in order to adapt them to their needs. This raised several questions:

  • Which namespaced class should a module developer extend now? If a module developer would extend OxidEsales\EshopEnterprise\Application\Model\Article, this module would not work in a shop based on OXID eShop Community Edition.
  • Also: should a developer re-write all source code with the new namespaced classes?

One of the benefits of OXID eShop is its backwards compatibility and the possibility easy updates. Even for the major update from OXID eShop 5.3 to OXID eShop 6, we wanted to keep the effort and costs for projects and modules as small as possible. For these reasons, we decided for a technical solution which minimizes the costs for updates and fulfills the requirements of a software that is entirely compatible with namespaces as well as with composer.

Here are the results of this decision:

  • The usage of non-namespaced classes like oxArticle is still possible in OXID eShop 6. They are deprecated but still usable for the period of transition.
  • The usage of composer and namespaces in a module is possible but not mandatory.
  • We needed a new namespace which wraps the edition namespaces. We called this namespace “unified namespace”. The unified namespace classes can be used to make a feature working in all editions.

How did we reach these goals?

We decided to implement the unified namespace classes as separate classes and the backwards compatible classes as class aliases (PHP method class_alias) because of reasons I will explain immediately.

We called the unified namespace \OxidEsales\Eshop. A class in the unified namespace extends all other existing OXID eShop edition classes. If your OXID eShop is, for example, based on a Professional Edition, the inheritance would look like in figure 2.

The unified namespace class OxidEsales\Eshop\Application\Model\Article extends a OXID eShop Professional Edition.

Figure 2: The unified namespace class OxidEsales\Eshop\Application\Model\Article extends an OXID eShop Professional Edition.

If your OXID eShop is based on an Enterprise Edition, the inheritance would look like figure 3.

The unified namespace class OxidEsales\Eshop\Application\Model\Article extends a OXID eShop Enterprise Edition.

Figure 3: The unified namespace class OxidEsales\Eshop\Application\Model\Article extends an OXID eShop Enterprise Edition.

This means, a module can extend the unified namespace class OxidEsales\Eshop\Application\Model\Article, and the module will work in all editions.

The deprecated class “oxarticle” is created – as mentioned before – via the PHP method class_alias and is not a real class. This constellation has several benefits:

  • You still can use the backwards compatible class “oxarticle” e.g. in type hints or when catching exceptions. But if you request the type of a class, either the unified namespace class name (OxidEsales\Eshop\Application\Model\Article in our case) or a module class which extends this unified namespace class (see figure 4) will be returned.
  • The backwards compatible classes can be removed at any point in the future without breaking the behaviour for module or project developers – once everybody of you guys use unified namespaces.
Inheritance Chain in a OXID eShop Enterprise Edition with 2 modules extending the unified namespace class OxidEsales\Eshop\Application\Model\Article

Figure 4: Inheritance chain in an OXID eShop Enterprise Edition with two modules extending the unified namespace class OxidEsales\Eshop\Application\Model\Article

Generating unified namespace classes

Every time, at the end of executing composer install, composer update and composer require, unified namespace classes will be generated. That’s why you’d have to follow certain steps on updating an OXID eShop like described here.

The generated unified namespace classes are located in the folder vendor/oxid-esales/unified-namespace-generator/generated. Browsing through these classes, you can, for example, find out which backwards compatible class was replaced by what namespaced new class:

Summary

OXID eShop 6 introduced several new concepts like namespaces in PHP classes and autoloading via PSR standards. The integration of proven solutions like composer helped us with this goal.

We did this a backwards compatible way which minimizes the costs for updating projects and modules. Module developers can use new features like PHP namespaces in their modules but it is not mandatory to fully update OXID eShop 5.3 compatible modules.

In case of any requests or comments please feel free to use the comment section below.

 

0.00 avg. rating (0% score) - 0 votes
2 replies
  1. AMartinNo1 says:

    Thanks for the article. Yet I am especially interested in how to work with unified namespaces in an IDE such as PHPStorm in terms of auto completion. I am working remotely and sync the source directory accordingly.

    Reply
  2. RBlank
    RBlank says:

    To answer the question about unified name spaces and IDE auto completion.
    The classes in the unified name space are real existing classes, which reside in vendor/oxid-esales/unified-namespace-generator/generated. As the are generated on the fly during ‘composer install’ and ‘composer update’, they always extent the proper classes, no matter which edition you are working on.
    PHPStorm will find these generated classes, know their parent classes and thus offer you the correct options for auto completion.
    Basically it is just plain PHP inheritance and as long as you stick to the new class names, there is no magic needed.

    A different case is, if you like to work on legacy code in OXID eShop v6.0. Imagine some module, which was written for OXID eShop 5.3 and you want to port to v6.0. This module would still use the old class names (like oxarticle), and in this case you would need the IDE helper. See https://github.com/OXID-eSales/oxid-eshop-ide-helper. Please, keep in mind, that you should get rid of usages of old class names, when you fully want to port a module to OXID eShop v6.0.

    In any case the oxid-plugin from Daniel Espendiller (https://github.com/Haehnchen/idea-php-oxid-plugin) is still interesting for users of PHPStorm. For OXID eShop v6.0 it is a bit outdated, but still adds some functionality to the IDE.

    Reply

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 *