Updating modules

To update existing modules from OXID eShop 6.5.x to OXID eShop 7, check the following sections.

Overview

Update steps

Adjust PHP version

As of version 7.0, we do not support PHP version lower 8.0.

Update your source code to work with the required PHP versions.

Adjust MySQL version

We have added MySQL 8 support and dropped MySQL 5.5 and 5.6 support.

Note also that we dropped encoding of database values as the functionality is no longer supported by MySQL v8.0.

Adjust Symfony components

We have updated Symfony components to v6.

Adjust your code to work with the required Symfony version.

Adjust module migrations

After doctrine update, you adjust your module migrations to a new configuration format.

For more information, see github.com/doctrine/migrations/blob/3.5.1/UPGRADE.md.

Adjust removed functionality

  • Make sure your module does not use any of the functionality that has been removed in OXID eShop 7.0.

    You can find a list of changes in the OXID eShop 7.0 Release Notes.

  • Besides removed functionality, we have also removed deprecated methods and classes.

  • Based on the PSR-12: Extended Coding Style, all method names MUST NOT be prefixed with a single underscore to indicate protected or private visibility.

    So, we renamed all the underscore method by removing their prefix underscore.

    Your module also has to be updated accordingly.

    We also recommend making your module compatible with PSR-12 by renaming the modules underscore methods too.
    You can do so either manually or via rector which helps us to do it faster.
    We already have provided a rector for this purpose available via OXID eShop update component. To run it, perform the following steps:

    1. Update composer with adding rector/rector and oxid-esales/oxideshop-update-component:

      composer require rector/rector --dev
composer require oxid-esales/oxideshop-update-component --dev

    2. Rename the underscore methods:

      cp vendor/oxid-esales/oxideshop-update-component/src/Rector/templates/oxid_V7_underscored_methods_renamer_rector.php.dist ./rector.php
sed -i 's/MODULE_VENDOR_PATH/<module-vendor>\/<module-ID>/g' rector.php
vendor/bin/rector process

# the same commands for the oxid-esales/paypal-module, for example
cp vendor/oxid-esales/oxideshop-update-component/src/Rector/templates/oxid_V7_underscored_methods_renamer_rector.php.dist ./rector.php
sed -i 's/MODULE_VENDOR_PATH/oxid-esales\/paypal-module/g' rector.php
vendor/bin/rector process

Move the module under a module namespace

We do not support not namespaced classes.

So as the next step, refactor the module to use only namespaced classes.

For more information, see Extending an OXID eShop class with a module.

Update composer file

As of OxXID eShop version 7.0, we do not copy modules files and folder from vendor folder to the source/modules directory anymore.

Therefore, to make your modules compatible with it, do the following:

  • To point to the module root directory in vendor, in the composer.json file, refactor Composer autoloader.

  • From the composer.json file, remove blacklist-filter, target-directory, and source-directory.

For more information, see Composer.json for an OXID eShop module.

Update metadata file

In version 7.0 we only support metadata version >= 2.0.

So, as the first step, change your metadata structure to use the proper version.

For more information, see Metadata 2.0.

Adjust entry points

If the module has entry points (direct calls to php files), refactor it to use controllers instead.

For more information, see Controllers

Adjust module templates path (only for smarty)

Change the paths for the module Smarty templates in the metadata.php file to be relative to the module root directory.

For more information, see Templates (Smarty only).

Locate module assets correctly

Copy assets to the <module-root-directory>/assets folder.

Copy module thumbnails also to the assets directory.

For more information, see File and folder structure.

Add Twig engine support

As of version 7.0, Twig is the default template engine.

Update your modules in order to work with it:

  1. Update to templating-engine agnostic names in all module controllers, e.g.:

    Controller::$_sThisTemplate = 'page/content'` instead of `'page/content.tpl'

  2. Add Twig templates for a twig specific theme.

For more information about converting existing templates from Smarty to Twig and how to use it, see Twig Template Engine.

Adjust module tests

The Testing Library is deprecated in version 7.0. We recommend updating your module tests to use the default PHPUnit or Codeception test framework functionality.

For more information about OXID best practices for testing, see Testing.

Check HTML-escaping

The class CoreField does not escape HTML special characters anymore, Twig template engine is automatically escaping these characters and printing them out safely.

But if your module renders some content that may have been filled in by the user, you need to escape it in order to prevent cross-site scripting attacks.

In some cases, you may need to actually print out some content unescaped. To do this, just use the handy raw filter:

{{ pageData.summary|raw }}

For backwards compatibility reasons, we have created the configuration parameter oxid_esales.templating.engine_autoescapes_html.

This parameter delegates HTML-escaping to the template engine.

As Smarty do not escape html special characters by default, we activate HTML-escaping in CoreField by deactivating this configuration parameter.

Check changes in the module handler

Notice also some changes in the module handler:

  • It does not store module controllers in the database anymore.

  • The information about active modules state is located in the module configuration (yml files), not in the database (activeModules config option is completely removed).

  • It reads the module class extensions chain directly from the shop configuration (yml files). It does not store the active module chain in the database (the aModules config option is completely removed).

  • It does not store module settings in the database anymore. So, you can’t receive a module setting from Config class or oxconfig table.

    To receive module setting, use the settings service ModuleSettingServiceInterface.

    For more information, see Module settings.