Modules

For updating existing modules from OXID eShop 6.5.x to OXID eShop 7, please have a look at the following sections.

Overview

Update steps

Adjust PHP version

Since version 7.0 we do not support PHP version lower 8.0. Please update your source code to work with required PHP versions.

Adjust MySQL version

We added MySQL 8 support and dropped MySQL 5.5 and 5.6 support. Please also note that we dropped encoding of database values as functionality is no longer supported by MySQL v8.0

Adjust Symfony components

We updated Symfony components to v6. Please adjust your code to work with required Symfony version

Adjust module migrations

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

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 here.

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

  • Based on the psr-12 (more info), 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 to make your module compatible with psr-12 by renaming the modules underscore methods too. It can be done either manually or via rector which helps us to do it faster. We already have provided a rector for this purpose and it can be run with the following steps:

    • Update composer with adding rector/rector package:

    "require-dev": {
    "rector/rector": "dev-master"
},
"repositories": {
    "rector/rector": {
        "type": "vcs",
        "url": "https://github.com/OXID-eSales/rector"
    }
}

    • Renaming underscore methods:

    # e.g. for oxid-esales/paypal-module
cp vendor/rector/rector/templates/oxidEsales/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

Move the module under a module namespace

We do not support not namespaced classes. So as the next step, the module should be refactored to use only namespaced classes.

Update composer file

In 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:

  • Composer autoloader in composer.json should be refactored to point to the module root directory in vendor

  • blacklist-filter, target-directory, and source-directory should be removed from composer.json

More information

Update metadata file

In version 7.0 we only support metadata version >= 2.0. So as the first step you should change your metadata structure to use the proper version.

Adjust entry point

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

Adjust module templates path (only for smarty)

Paths for module smarty templates in the metadata.php should be changed to be relative to the module root directory.

Locate module assets correctly

Assets should be copied to <module-root-directory>/assets folder. Module thumbnails also should be copied to the assets directory.

Add twig engine support

Since version 7.0 Twig is a default template engine. Please update your modules in order to work with it:

  • Please update to templating-engine agnostic names in all module controllers, e.g.:

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

  • Add Twig templates for twig specific theme.

Information about converting existing templates from Smarty to Twig and how to use it can be found in

Adjust module tests

We deprecated Testing Library in version 7.0 and recommend to update your module tests to use default PHPUnit or Codeception test framework functionality. You can read OXID best practice for testing here.

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 created the configuration parameter oxid_esales.templating.engine_autoescapes_html that delegates HTML-escaping to 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

Please also notice some changes in the module handler:

  • 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)

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

  • Does not store module settings in the database anymore. You can’t receive a module setting from Config class or oxconfig table. To receive module setting please use settings service ModuleSettingServiceInterface. More information