Composer.json for an OXID eShop Module

OXID eShop modules with metadata version greater 2.0 are installed via Composer by using the OXID eShop Composer Plugin.

In order to install a module correctly, this plugin requires four fields to be described in module composer.json file:

• name

• type

• extra

• require

• autoload

PayPal module example:

{
    "name": "oxid-esales/paypal-module",
    "description": "This is the PayPal module for the OXID eShop.",
    "type": "oxideshop-module",
    "keywords": ["oxid", "modules", "eShop"],
    "homepage": "https://www.oxid-esales.com/en/home.html",
    "license": [
        "GPL-3.0-only",
        "proprietary"
    ],
    "extra": {
        "oxideshop": {
            "blacklist-filter": [
                "documentation/**/*.*"
            ],
            "target-directory": "oe/oepaypal"
        }
    },
    "require": {
        "php": ">=5.6",
        "lib-curl": ">=7.26.0",
        "lib-openssl": ">=1.0.1",
        "ext-curl": "*",
        "ext-openssl": "*"
    },
    "autoload": {
        "psr-4": {
            "OxidEsales\\PayPalModule\\": "../../../source/modules/oe/oepaypal"
        }
    }
}

name

This is the name the OXID eShop module will be publicly known and installable. E.g. in our example you could type

composer require oxid-esales/paypal-module

type

Module must have oxideshop-module value defined as a type. This defines how the repository should be treated by the installer.

extra: {oxideshop}

target-directory

target-directory value will be used to create a folder inside the Shop modules directory. This folder will be used to place all files of the module.

Important

It is strongly recommended to set the target directory value to <vendor of the module> + <module ID>, e.g. oe/oepaypal.

source-directory

If source-directory is given, the value defines which directory will be used to define where the files and directories will be picked from. When the parameter is not given, the root directory of the module is used instead.

Note

Usually this parameter should not be used if all files are placed in the module’s root directory.

blacklist-filter

If blacklist-filter is given, it will be used to filter out unwanted files and directories while the copy from source-directory to target-directory takes place. The value of blacklist-filter must be a list of strings where each item represents a glob filter entry and is described as a relative path (relative to source-directory).

Below is a list of valid entries:

• README.md - will filter one specific file README.md;

• *.pdf - will filter all PDF documents from the source root directory;

• **/*.pdf - will filter all PDF documents from the source root directory and all of it’s child directories;

• example/path/**/* - will filter all files and directories from the directory example/path, including the given directory itself.

Below is a list of non-valid entries:

• /an/absolute/path/to/file - absolute paths are not allowed, only relative paths are accepted;

• some/path/ - ambigious description of directory to filter, it’s not clear if only the files are needed to be filtered or directories have to be included as well.

• documentation/**/*.* - Using **/*.* at the end of the filter string, is not allowed.

For the most up-to-date definition of what can be accepted as an argument, please follow the blacklist-filter tests which covers the behaviour.

require

Here you must define all dependencies your module has. You must define:

• a minimum PHP version. In the example PHP >=5.6 is required

• the required system libraries and their versions, if applicable. In the example lib-curl >=7.26.0 and lib-openssl >=1.0.1 are required

• the required PHP extension and their versions, if applicable. In the example the PHP extensions curl and openssl must be activated

• the required composer components, if applicable. In the example the are no requirements defined

Autoload

Composer autoloader is used to load classes. In order to load module classes the module needs to register it’s namespace to the modules path:

"autoload": {
  "psr-4": {
    "<vendor>\\<module-name>\\": "../../../source/modules/<vendor>/<module-name>"
  }
},

Keep in mind, that the target-directory in the section extra: {oxideshop} has to fit the autoload path you define here. In our PayPal example the PSR-4 autoload path points to a path inside the OXID eShop source/modules directory. This path must match the path of the target-directory as defined in the extra: {oxideshop} section, as the files will be copied there.