Edit in GitHubLog an issue

Module version dependencies

Adobe Commerce and Magento Open Source platform clients need notifications about breaking changes for their installed extensions and customizations when they upgrade to a new version.

To achieve this, all third-party modules must obey the following rules:

  1. You must specify the dependency on all modules listed in the require section of your module's composer.json file.
  2. Do not specify a dependency on meta packages (e.g. product-community-edition).
  3. Specify a module's MAJOR and/or MINOR version number if you use any of that module's customization points.
  4. Specify a module's MAJOR, MINOR, and PATCH versions if you call or customize a module's private code.

Service provider interfaces#

A PHP Interface in Adobe Commerce and Magento Open Source can be used several ways by the core product and extension developers.

  • As an API. An interface is called by PHP code.
  • As a Service Provider Interface (SPI). An interface can be implemented, allowing code to provide functionality to the platform.
  • As both. For example, in a service contract, we expect all calls to a module to be done through the Interface (API), but we also have support for third parties to provide alternate implementations (SPI). APIs and SPIs are not mutually exclusive. Therefore, we do not distinguish them separately. SPIs are annotated the same as APIs.

However, the dependency rules are different:

  • If a module uses (calls) an API, it should be dependent on the MAJOR version and the system provides backward compatibility in scope of current major version.

    API dependency example

    Copied to your clipboard
    1{
    2 "require": {
    3 "magento/customer": "~2.0",
    4 },
    5}
  • If a module implements an API/SPI, it should be dependent on the MAJOR+MINOR version, and the system provides backward compatibility in scope of the current minor version.

    SPI dependency example

    Copied to your clipboard
    1{
    2 ...
    3 "require": {
    4 "magento/customer": "~2.0.0",
    5 },
    6 ...
    7}

Determine module dependency#

The following table lists common use cases for API/customization points and the version dependency for each use case. Use this table to set the appropriate version dependency on a module based on how you use its API/customization points.

API/Customization PointThird-party Use CaseVersion Dependency
PHP Interface (marked with @api)Inject in a constructor and/or call methodsMAJOR
Implement the interfaceMINOR
Re-define the interface preference in di.xmlMINOR
Add a plugin to the interfaceMAJOR
PHP Class (marked with @api)Inject in a constructorMAJOR
Extend from an abstract classMAJOR
Add a plugin to the classMAJOR
Configure class preference in di.xmlMAJOR
Configure constructor argument in di.xmlMAJOR
Use class constantMAJOR
PHP Class (NOT marked with @api)Inject in a constructorPATCH
Extend from an abstract classPATCH
Configure class preference in di.xmlPATCH
Configure constructor argument in di.xmlPATCH
Use class constantPATCH
JavaScript Interface (marked with @api)Inject in a constructor and/or call methodsMAJOR
Implement the interfaceMINOR
JavaScript class (marked with @api)Inject in a constructorMAJOR
Extend from a classMINOR
Override a methodMINOR
Subscribe to an eventMINOR
Virtual TypeConfigure a virtual type in the di.xml file as a class dependencyMAJOR
URL PathsLink to from custom pagesMAJOR
Console commands and their argumentsCalled in custom shell scriptsMAJOR
Less variables and mixinsUse in LESS declarationsMAJOR
Message queue topics and data typesConsume a topic/messageMINOR
Publish an existing topicMAJOR
Layout handles declared by modulesInstance blocks addedMAJOR
Blocks and containers moved/removedMAJOR
Static and dynamic events triggered by a componentSubscribing to eventMAJOR
XML configuration typeProvide another configuration to the configuration typeMAJOR
Extend existing XSDMINOR
Structure of System Configuration fields used by moduleConfigure module through System Configuration valuesMAJOR
Read system configuration using config pathMAJOR
Database structureRead/write to a tableMAJOR
Add a column to a tableMINOR
Declare a foreign key on a module tableMAJOR
Declare a trigger on a module tableMAJOR
Read from table or write to table from a temporary tablePATCH
Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.