Backward-incompatible changes highlights

This page highlights backward-incompatible changes between Adobe Commerce and Magento Open Source releases that have a major impact and require detailed explanation and special instructions to ensure third-party modules continue working. High-level reference information for all backward-incompatible changes in each release is documented in the reference section.

2.4.8-beta

The following major backward-incompatible changes were introduced in the 2.4.8-beta Adobe Commerce and Magento Open Source releases:

• Upgraded monolog/monolog dependency
• Updated default value for 2FA OTP window
• New 2FA system parameter
• New unique EAV key

Upgraded monolog/monolog dependency

The monolog/monolog third-party dependency was updated to the latest stable version (3.x) to enhance platform stability and performance.

Action Required:

This change affects custom code and extensions that use or overwrite the protected function write(array $record): void method for exception logging. The argument type needs to be updated to LogRecord $record instead of array $record. For example:

Copy
protected function write(LogRecord $record): void
Copied to your clipboard
protected function write(LogRecord $record): void

Updated default value for 2FA OTP window

The spomky-labs/otphp library has changed the way that the one-time password (OTP) window is calculated for two factor authentication (2FA). Previously, it used a "window" multiplier, but now it uses a "leeway" value in seconds. This change ensures that the configuration is up to date with the latest library behavior.

Merchants and customers using the Google Authenticator 2FA provider must reset the configuration value for the OTP window. The command has changed from bin/magento config:set twofactorauth/google/otp_window VALUE to bin/magento config:set twofactorauth/google/leeway VALUE. This change aligns with the updated spomky-labs/otphp library, which uses a default expiration period of 30 seconds.

To set the new default value:

Copy
bin/magento config:set twofactorauth/google/leeway 29
Copied to your clipboard
bin/magento config:set twofactorauth/google/leeway 29

The following module is affected by this change:

• Magento_TwoFactorAuth

New 2FA system parameters

New system parameters have been added to enable rate limiting on two-factor authentication (2FA) one-time password (OTP) validation:

Copy
...    
    /**
     * Config path for the 2FA Attempts
     */
    private const XML_PATH_2FA_RETRY_ATTEMPTS = 'twofactorauth/general/twofactorauth_retry';

    /**
     * Config path for the 2FA Attempts
     */
    private const XML_PATH_2FA_LOCK_EXPIRE = 'twofactorauth/general/auth_lock_expire';
...
Copied to your clipboard
...    
    /**
     * Config path for the 2FA Attempts
     */
    private const XML_PATH_2FA_RETRY_ATTEMPTS = 'twofactorauth/general/twofactorauth_retry';

    /**
     * Config path for the 2FA Attempts
     */
    private const XML_PATH_2FA_LOCK_EXPIRE = 'twofactorauth/general/auth_lock_expire';
...

These paramters correspond to the following system configuration options in the Admin:

• Retry attempt limit for Two-Factor Authentication

• Two-Factor Authentication lockout time (seconds)

  Adobe advises setting a threshold for 2FA OTP validation to limit the number of retry attempts to mitigate brute-force attacks. See Security > 2FA in the Configuration Reference Guide for more information.

The following module is affected by this change:

• Magento_TwoFactorAuth

New unique EAV key

Added a unique key on the column pair (option_id, store_id) on the eav_attribute_option_value table.

The following module is affected by this change:

• Magento_EAV

2.4.7

The following major backward-incompatible changes were introduced in the 2.4.7 Adobe Commerce and Magento Open Source releases:

• API integration: FedEx SOAP
• API integration: UPS SOAP
• Default behavior for isEmailAvailable API
• Elasticsearch 7 deprecation
• Fixes to resolve compatibility issues with Symfony
• New block class for subresource integrity verification
• New interface and method for ApplicationServer module
• New method and an optional parameter for multicoupons
• New method in Config/Type/System
• New method for encryption key generation
• New SKU validation in inventory source items API
• New system configuration for full-page caching
• New system configuration for limiting coupon generation
• New system configuration for payment information rate limiting
• New system configuration validation for Two Factor Authentication otp_window value

API integration: FedEx SOAP

The Commerce FedEx SOAP API integration has been migrated to the new FedEx REST API. The FedEx Web Services for Tracking API was retired on May 15, 2024. All previous FedEx SOAP APIs have been removed from the Adobe Commerce and Magento Open Source 2.4.7 code base.

This change affects custom code and extensions that use the SOAP APIs. You must update your code to use the REST APIs.

You must generate REST credentials (Account Number, API Key, and Secret Key) from the FedEx developer portal and add those credentials to the Admin by going to Stores > Configuration > Sales > Shipping/Delivery Methods > FedEx.

The following module is affected by this change:

• Magento_Fedex

API integration: UPS SOAP

The Commerce UPS SOAP API integration has been migrated to the new UPS REST API to support updates that UPS is making to their API security model. UPS is implementing an OAuth 2.0 security model (bearer tokens) for all APIs. All previous Commerce UPS SOAP APIs have been removed from the Adobe Commerce and Magento Open Source 2.4.7 code base.

You must generate REST credentials (Account Number, API Key, and Secret Key) from the UPS developer portal and update those credentials to the Admin by going to Stores > Configuration > Sales > Shipping/Delivery Methods > UPS.

The following module is affected by this change:

• Magento_Ups

Default behavior for isEmailAvailable API

The default behavior of the isEmailAvailable GraphQL query and (V1/customers/isEmailAvailable) REST endpoint has changed. By default, the API now always returns true. The new default behavior also affects the checkout workflow for guests that do not realize they already have an account. Previously, by default, when a guest supplied an email address that matched an existing customer account, they were prompted to sign in. Now, they are no longer prompted to sign in.

Merchants can restore the original default behavior of the isEmailAvailable API and checkout flow by setting the Stores > Configuration > Sales > Checkout > Enable Guest Checkout Login field to Yes. However, doing this can expose customer information to unauthenticated users.

Elasticsearch 7 deprecation

This change removes the Magento_Elasticsearch module (for Elasticsearch 5) and adds support for Elasticsearch 8. The Magento_Elasticsearch7 module is being deprecated because Elasticsearch 7 reached end-of-life in August 2023. However, it is still the default option for 2.4.7.

The Magento_Elasticsearch8 module is not currently supported because of backward-incompatible changes in ES7 and ES8. It is available as a Composer metapackage only in 2.4.7 until the Magento_Elasticsearch7 module is removed from the codebase.

You can use the Magento_Elasticsearch7 module or install the Magento_Elasticsearch8 module in 2.4.7.

The following modules are affected by this change:

• Magento_Elasticsearch
• Magento_ElasticsearchCatalogPermissions
• Magento_Elasticsearch7
• Magento_OpenSearch

Fixes to resolve compatibility issues with Symfony

The return type was changed for the Magento\Framework\Console\Cli::getDefaultCommands interface to provide compatibility with the latest Symfony 6.4 LTS version.

Extension developers must define strict typing for return values in classes that use the changed interface: Magento\Framework\Console\Cli::getDefaultCommands.

New block class for subresource integrity verification

A new block class was added (Magento\Csp\Block\Sri\Hashes) marked with the @api annotation to support subresource integrity verification. This ensures that all scripts executed on payment pages and the Admin have an integrity attribute so that no unauthorized scripts can run. You must add integrity attributes to all custom and remote JavaScript resources.

The following module is affected by this change:

• Magento_Csp

New interface and method for ApplicationServer module

State management has been enabled for all GraphQL APIs (excluding B2B and service-related processes). The 2.4.7 release introduces a new PHP application server that is implemented on a Swoole PHP extension. The ApplicationServer module enables Adobe Commerce to maintain state between Commerce GraphQL API requests and eliminates the need for request bootstrapping. By sharing application state among processes, API requests become significantly more efficient, and API response times potentially decrease by 50 to 60 milliseconds.

The ResetAfterRequestInterface interface and _resetState() method were added to enable the PHP application server. The __debugInfo() method was also added to fix issues with var_dump calls.

No action for merchants or extension developers is necessary.

The following modules are affected by this change:

• Magento_Authorization
• Magento_Config
• Magento_Customer
• Magento_ResourceConnections

New method and an optional parameter for multicoupons

The following changes were introduced to implement the multicoupon functionality in the SalesRule module:

• Optional parameter added to Magento\SalesRule\Model\ResourceModel\Rule\Collection::setValidationFilter
• New method introduced: Magento\SalesRule\Model\Validator::initFromQuote

All changes have been done in a way to minimize any impact to extensions and customizations. However, there are risks of conflict if an extension or customization extends the following:

• Magento\SalesRule\Model\ResourceModel\Rule\Collection::setValidationFilter and adds a parameter to this method.
• Magento\SalesRule\Model\Validator and introduces a method with the same name initFromQuote.

The following module is affected by this change:

• Magento_SalesRule

New method for encryption key generation

This change improves the security of encrypted user data. You must reset the encryption key and set the Auto-generate option to Yes. After resetting the encryption key, all credit card data and cache files are re-encrypted with the new key.

The following files are affected by this change:

• lib/internal/Magento/Framework/Config/ConfigOptionsListConstants.php—A new method was added to increase the entropy of encryption keys generated by the framework for stored credit card and cache data.
• lib/internal/Magento/Framework/Math/Random.php—A new constant was added to prefix base64-encoded encryption keys for use in env.php files.

New method in Config/Type/System

The bin/magento cache:clean config CLI command, and its Admin UI equivalent, now pre-warm the config cache (when config cache is enabled) in order to reduce the lock time after cleaning the config cache. This reduces the downtime for large configurations that take significant time to generate the config cache.

We've also changed the configuration save so that it no longer cleans the config_scopes cache (when config cache is enabled). Config saving also pre-warms the config cache now, which also reduces the lock time for large configurations. Cleaning the config cache after saving configuration changes is still recommended.

No action for merchants or extension developers is necessary because the general functionality is the same. Only the order of generating the config cache, serializing, and encrypting (before lock instead of after) was changed.

The following module is affected by this change:

• Magento_Config

New SKU validation in inventory source items API

Payload containing SKU will now be validated for leading and trailing spaces in the rest/V1/inventory/source-items API.

New system configuration full-page caching

This change improves the security and performance of how the framework resolves Varnish Edge Side Includes (ESI) for full-page caching.

The {BASE-URL}/page_cache/block/esi HTTP endpoint supports unrestricted, dynamically loaded content fragments from Commerce layout handles and block structures.

The new Handles params size system configuration setting limits the handles parameter for the endpoint to 100 by default. You can change the default in the Admin by going to Stores > Settings > Configuration > Advanced > System > Full Page Cache.

No action is necessary unless you need to modify the default value for the endpoint.

The following module is affected by this change:

• Magento_PageCache

New system configuration for limiting coupon generation

Added a new setting for the number of coupons to generate. This property has a default value of 250,000, which is also the maximum value. Merchants can disable this feature by setting it to 0 in the Admin by going to Stores > Settings > Configuration > Customers > Promotions > Code Quantity Limit.

The following module is affected by this change:

• Magento_SalesRule

New system configuration for payment information rate limiting

New native application rate-limiting features have been added with initial out-of-the-box support for rate limiting of payment APIs. Disabled by default.

No action for merchants or extension developers is necessary.

The following module is affected by this change:

• Magento_Quote

New system configuration validation for Two Factor Authentication otp_window value

The updated spomky-labs/otphp library introduced a new validation requirement for supplying custom otp_window values. This configuration setting controls how long (in seconds) the system accepts an administrator's one-time-password (OTP) after it has expired. Previously, the library allowed any number of seconds to be specified. Now, the value cannot be higher than the lifetime of a single OTP (usually 30 seconds). You must update this value if it is currently set to 30 or higher.

If your Commerce application is affected by this change, admin users might see the following message when they log in: There was an internal error trying to verify your code. You can confirm the cause of the error by checking the system.log file in var/log for an entry main.ERROR: The leeway must be lower than the TOTP period.

To fix this issue, change the value of the configuration path twofactorauth/google/otp_window to be shorter than the TOTP period, which is usually 30 seconds. For example, you can reset it to 29 seconds using the bin/magento config:set twofactorauth/google/otp_window 29 command. You might need to flush the cache to apply the updated configuration.

2.4.6

The following major backward-incompatible changes were introduced in the 2.4.6 Adobe Commerce and Magento Open Source releases:

• New default value for automatic redirects
• New system configuration for customer segments
• New system configuration for limiting products in grid
• New system configuration for OpenSearch module
• Symfony dependencies upgraded to latest LTS version
• Zend_Filter replaced with laminas-filter
• Zend_HTTP replaced with laminas-http
• Zend_Json replaced with laminas-json
• Zend_Validate replaced with laminas-validator

New default value for automatic redirects

To improve performance, the default value for generate_category_product_rewrites in the app/code/Magento/CatalogURLRewrite/etc/config.xml file was changed from 1 to 0. This change disables automatic category/product URL rewrites, but only if you have not changed the previous default setting prior to upgrading to 2.4.6.

The new default does not change existing records in the catalog_url_rewrite_product_category and url_rewrite database tables when upgrading to 2.4.6, but no new rewrites are added. You can enable the Generate "category/product" URL Rewrites setting if you want to continue using it after upgrading.

New system configuration for limiting products in grid

To improve product grid performance for large catalogs, a new system configuration setting (disabled by default) was added to limit the number of products in the grid: Stores > Settings > Configuration > Advanced > Admin > Admin Grids > Limit Number of Products in Grid. See Limit number of products in grid.

The product grid limitation only affects product collections that are used by UI components. As a result, not all product grids are affected by this limitation. Only those that are using the Magento\Catalog\Ui\DataProvider\Product\ProductCollection class.

The following module is affected by this change:

• Magento_Backend

New system configuration for OpenSearch module

In Adobe Commerce and Magento Open Source 2.4.4 and 2.4.3-p2, all system configuration fields labeled Elasticsearch also apply to OpenSearch. When support for Elasticsearch 8.x was introduced in 2.4.6, new labels were created to distinguish between Elasticsearch and OpenSearch configurations. See Search engine configuration.

To simplify current and future support for Elasticsearch and OpenSearch, we refactored redundant virtual types for the Elasticsearch modules and renamed the functional test action group SearchEngineElasticsearch to SearchEngine.

These changes can be break tests or custom code if you:

• Use or extend the SearchEngineElasticsearch functional tests
• Use or extend the Magento\Elasticsearch\SearchAdapter\ConnectionManager virtual type, which was removed

If these changes impact you, you must update all tests and custom code that rely on the refactored action group and removed virtual type.

The following modules are affected by this change:

• Magento_VisualMerchandiser
• Magento_GiftCard
• Magento_Elasticsearch
• Magento_Elasticsearch7
• Magento_Search
• Magento_LayeredNavigation
• Magento_GroupedProduct
• Magento_Downloadable
• Magento_Customer
• Magento_ConfigurableProduct
• Magento_CatalogSearch
• Magento_Catalog
• Magento_Bundle
• Magento_Config
• Magento_FunctionalTestModuleInventoryAdminUi
• Magento_OpenSearch

New system configuration for customer segments

A new system configuration setting was added to avoid performance degradation when you have a large number of customer segments. See customer segments validation.

You can enable or disable this setting at any time. No additional actions are necessary, except cleaning the cache.

The following module is affected by this change:

• Magento_CustomerSegment

Symfony dependencies upgraded to latest LTS version

This change adds support for the latest version of Symfony, so that you can use the latest solutions to build more stable functionality and avoid hypothetical security issues.

For example, this change updates the return type for the Magento\Backend\Console\Command\AbstractCacheTypeManageCommand class from void to int, which extends Symfony\Component\Console\Command\Command and must return the int type.

If you override or extend the Magento\Backend\Console\Command\AbstractCacheTypeManageCommand class, you should check the return type for the execute method to avoid errors when executing command-line commands.

The following module is affected by this change:

• Magento_Backend

Zend_Filter replaced with laminas-filter

This change replaces the outdated Zend_Filter library with the actively supported laminas-filter library. The following modules are affected by this change:

• Magento_GoogleAdwords (backend)
• Magento_Framework (translation and validation functionality)

Interface changes

The following interface changes are a result of replacing interfaces from the Zend-Filter library with the corresponding interfaces from the laminas-filter library.

Class changes

Zend_HTTP replaced with laminas-http

This change replaces the outdated Zend_HTTP library with the actively supported laminas-http library. The following modules are affected by this change:

• Magento_Payment
• Magento_Framework

Zend_Validate replaced with laminas-validator

This change replaces the outdated Zend_Validate library with the actively supported laminas-validator library. The following modules are affected by this change:

• Magento_Store (validations during the creation of a new store)
• Magento_User
• Magento_GoogleAdwords (backend)
• Magento_Framework (translation and validation functionality)

Interface changes

The following interface changes are a result of replacing interfaces from the Zend-Validate library with the corresponding interfaces from the laminas-validate library.

Class changes

2.4.5

The grunt-contrib-jasmine.js library has been updated. The toBeFalsy() function does not work correctly with undefined values. Use the toBeUndefined() function instead to check results.

Static content deployment

A new backend theme (magento/spectrum) was added to support integration with Adobe Experience Platform. As a result, static file generation does not work correctly after upgrading to Adobe Commerce 2.4.5 on cloud infrastructure if you use the SCD_MATRIX deployment strategy.

If you use the SCD_MATRIX configuration, you must add the new magento/spectrum theme to your .magento.env.yaml file or your custom static content deploy command.

Copy
stage:
  deploy:
    SCD_MATRIX:
      "magento/backend":
        language:
          - en_US
          
+     "magento/spectrum":
+       language:
+         - en_US    
Copied to your clipboard
stage:
  deploy:
    SCD_MATRIX:
      "magento/backend":
        language:
          - en_US
          
+     "magento/spectrum":
+       language:
+         - en_US    

2.4.4

Removal of deprecated email variable usage

Email variable usage was deprecated back in 2.3.4 as part of a security risk mitigation in favor of a more strict variable syntax. This legacy behavior has been fully removed in this release as a continuation of that security risk mitigation.

As a result, email or newsletter templates that worked in previous versions may not work correctly after upgrading to Adobe Commerce 2.4.4 or Magento Open Source 2.4.4. Affected templates include admin overrides, themes, child themes, and templates from custom modules or third-party extensions. Your deployment may still be affected even after using the Upgrade compatibility tool to fix deprecated usages. See Migrating custom email templates for information about potential effects and guidelines for migrating affected templates.

Changes to naming conventions for language package filenames

2.4.4 and its support for PHP 8.1 requires changes in how translation packages are named. Language package filenames must now follow the naming conventions enforced by PHP 8.1. Consequently, lowercase letters are no longer permitted in the second part of the locale name.

The nl_di translation package has been renamed to nl_DI. Merchants using this translation pack must update their configuration (path: general/locale/code) from nl_di to nl_DI to use Adobe Commerce 2.4.4.

Inventory check on cart load

A new "Enable Inventory Check On Cart Load" system configuration option has been added to Admin > Stores > Configuration > General > Catalog > Inventory > Stock Options. The new option determines if an inventory check is performed when loading a product in the cart. It is enabled by default.

Disabling the inventory check can improve performance for checkout steps, especially when there are many items in the cart. But if this inventory check is skipped, some out-of-stock scenarios could throw other types of errors, including:

• The requested qty is not available
• Unable to place order: Enter a valid payment method and try again.
• Unable to place order: There are no source items with the in stock status.
• The shipping method is missing. Select the shipping method and try again.

The following table contains metrics of checkout with a large amount of products (750) and additional product by guest:

TinyMCE

There are three major BICs related to TinyMCE in 2.4.4, including:

• Renamed TinyMCE4 to tinymce
• Refactored TinyMCE MFTF tests
• Refactored TinyMCE4 MFTF tests

Renamed tinymce4 to tinymce

Renaming tinymce4 to tinymce removes the strict dependency on a version of TinyMCE from the code. The following changes could cause the WYSIWYG interface to break and not display on pages that use it in the Admin and break the Page Builder extension:

• Renamed the array key in the TinyMCE configuration provider
• Renamed the alias in the requirejs-config.js file
• Renamed a Page Builder JavaScript file that was marked as API from tinymce4.ts to tinymce.ts

You are impacted by these changes if:

• You use a custom configuration for TinyMCE that uses the tinymce4 alias in requirejs
• If you use the Page Builder JavaScript file that was renamed in any other place than the app/code/Magento/PageBuilder/etc/adminhtml/di.xml file

If these changes impact you, take the following action:

• Change the name of the array key in the TinyMCE configuration provider from tinymce4 to tinymce
• Change any requirejs file that uses the tinymce4 alias to tinymce
• Update anywhere that references the Page Builder JavaScript file that was renamed

Refactored TinyMCE MFTF tests

To simplifiy current and future upgrades to the next version of TinyMCE and decrease maintenance efforts, we refactored WYSIWYG (TinyMCE) MFTF tests to use the same sections\selectors. We also removed duplicated entities. These changes might break some MFTF tests.

You are impacted by these changes if:

• You have tests that use elements (selectors) from duplicated sections
• You have tests that extend core tests with TinyMCE

If these changes impact you, update all tests that use duplicated elements.

Refactored TinyMCE4 MFTF tests

To simplify current and future upgrades to the next version of TinyMCE, we refactored TinyMCE4 MFTF in the following ways:

• Renamed the action group CliEnableTinyMCE4ActionGroup to CliEnableTinyMCEActionGroup
• Replaced all references to "TinyMCE 4" in the test code base with tinymce
• Create variable for adapter version
• Change stepKey on each test

These changes can be break tests if you use or extend the TinyMCE4 MFTF tests, but they affect only functional tests (MFTF).

If these changes impact you, you must update all tests that rely on the refactored action group and reference "TinyMCE4".

2.4.3-p2

Removal of deprecated email variable usage

Email variable usage was deprecated back in 2.3.4 as part of a security risk mitigation in favor of a more strict variable syntax. This legacy behavior has been fully removed in this release as a continuation of that security risk mitigation.

As a result, email or newsletter templates that worked in previous versions may not work correctly after upgrading to Adobe Commerce 2.4.3-p2 or Magento Open Source 2.4.3-p2. Affected templates include admin overrides, themes, child themes, and templates from custom modules or third-party extensions. Your deployment may still be affected even after using the Upgrade compatibility tool to fix deprecated usages. See Migrating custom email templates for information about potential effects and guidelines for migrating affected templates.

2.4.3-p1

Media Gallery folders

Version 2.4.3-p1 introduced a configuration option for Media Gallery content that denotes which folders can contain Media gallery files.

The new configuration path system/media_storage_configuration/allowed_resources/media_gallery_image_folders is used to define the "Media Gallery Allowed" folders in 'config.xml'.

The initial values are the wysiwyg and catalog/category folders.

These can be extended by adding a new value in config.xml.

Issue

Any Media Gallery files within pub/media, or in a folder outside a "Media Gallery Allowed" folder will not be accessible to the Media Gallery after the patch is installed.

Workaround

Copy any Media Gallery files to pub/media/wysiwyg or one of the specified "Media Gallery Allowed" folders, or add a new entry under system/media_storage_configuration/media_storage/allowed_resource/media_gallery_image_folders.

2.4.2- 2.4.3

Cookie message is displayed when new page loads

Stores with a pre-existing custom theme and for which cookies are enabled now display this message: The store will not work correctly in the case when cookies are disabled. This issue is caused by a backward-incompatible change in how Commerce handles cookie status messages. GitHub-9095

Workaround: Add the cookie-status-message class to the custom_theme_path/Magento_Theme/web/css/source/_module.less file for custom themes.

Copy
& when (@media-common = true) {
    .cookie-status-message {
        display: none;
    }
}

Copied to your clipboard

& when (@media-common = true) {
    .cookie-status-message {
        display: none;
    }
}

pelago/emogrifier update

The dependency pelago/emogrifier has been updated from version 3.1.0 to 5.0.0. This update resulted in the introduction of backwards-incompatible changes to the Magento\Email\Model\Template\Filter class. The changed code is executed during email templates rendering. See reference.

TinyMCE

The TinyMCE v3 library, which was deprecated on May 14, 2018, has been removed because it is not compatible with the latest version of jQuery. You must use TinyMCE v4.

• The Magento_Tinymce3 module has been removed from Magento Open Source.

• The Magento_Tinymce3Banner module has been removed from Adobe Commerce.

• All MFTF tests related to TinyMCE v3 have been removed.

To switch to the TinyMCE v4 library, you must change the cms/wysiwyg/editor value in the core_config_data database table to mage/adminhtml/wysiwyg/tiny_mce/tinymce4Adapter.

This change only impacts extensions that depend on the TinyMCE v3 library for WYSIWYG functionality in the Admin.

2.4.1 - 2.4.2

Compare lists

Commerce uses session storage to work with compare lists. In version 2.4.2, Adobe added GraphQL support for compare lists. Instead of relying on session storage, GraphQL now saves compare list information into the database, with each list assigned an ID. These changes are additive and do not alter the behavior of compare lists on the storefront. However, there is a chance these changes could affect third-party extensions that manage compare lists.

The following methods and property have been added to the Magento\Catalog\Model\ResourceModel\Product\Compare\Item\Collection class. They are available to all developers, not just those working on GraphQL.

Copy
getListId()
getProductsByListId()
removeCompareList()
setListId()
setListIdToCustomerCompareItems()
$listId
Copied to your clipboard
getListId()
getProductsByListId()
removeCompareList()
setListId()
setListIdToCustomerCompareItems()
$listId

This feature introduces the following database changes:

• Added the foreign key catalog_compare_item/CATALOG_COMPARE_ITEM_LIST_ID_CATALOG_COMPARE_LIST_LIST_ID
• Added the catalog_compare_list table
• Added the catalog_compare_item/list_id column

2.3.0 - 2.4

Elasticsearch

MySQL is no longer used for search. You must use Elasticsearch.

You must install and configure Elasticsearch 7.6.x before upgrading to 2.4.0. New installations require a connection to Elasticsearch to complete.

Extension developers must update any module that depends on the unsupported search engines.

The changes with removing values from the system.xml file require eliminating ES2 support from the Admin UI. Other API classes were removed to clean up the code when we deprecated ES2 and ES5 in 2.3.5.

The following modules have been refactored to use the ElasticSearchResultApplier class and avoid usage of CatalogSearch and SearchResultApplier, which was based on MySQL:

• CatalogGraphQL
• QuickOrder (B2B)

In addition, the following constructors were modified to provide a mixed type. We have removed deprecated class private and protected components but have left their usages as arguments in the constructor for backward compatibility.

Copy
Magento\CatalogSearch\Model\ResourceModel\Fulltext\Collection
Magento\CatalogSearch\Model\ResourceModel\Advanced\Collection
Magento\CatalogSearch\Model\Indexer\Fulltext\Action\Full
Copied to your clipboard
Magento\CatalogSearch\Model\ResourceModel\Fulltext\Collection
Magento\CatalogSearch\Model\ResourceModel\Advanced\Collection
Magento\CatalogSearch\Model\Indexer\Fulltext\Action\Full

The following deprecated interfaces were deleted. If your extension implements any of these interfaces, refactor your code to use the Elasticsearch module.

Copy
Magento\Framework\Search\Adapter\Mysql\Query\Builder\QueryInterface
Magento\CatalogSearch\Model\Search\FilterMapper\FilterStrategyInterface
Copied to your clipboard
Magento\Framework\Search\Adapter\Mysql\Query\Builder\QueryInterface
Magento\CatalogSearch\Model\Search\FilterMapper\FilterStrategyInterface

The following deprecated classes were deleted. If your extension uses any of the above classes, then you must do a major refactor to your code to use the Elasticsearch module and not rely on the MySQL Search class implementations.

Copy
Magento\Framework\Search\Adapter\Mysql\DocumentFactory
Magento\Framework\Search\Adapter\Mysql\Mapper
Magento\Framework\Search\Adapter\Mysql\ScoreBuilder
Magento\Framework\Search\Adapter\Mysql\Query\Builder\Match
Magento\Framework\Search\Adapter\Mysql\Field\FieldFactory
Magento\Framework\Search\Adapter\Mysql\Aggregation\Builder
Magento\Framework\Search\Adapter\Mysql\Aggregation\DataProviderContainer
Magento\CatalogSearch\Model\Search\TableMapper
Magento\CatalogSearch\Model\Indexer\IndexerHandler
Magento\CatalogSearch\Model\Indexer\ProductFieldset
Magento\CatalogSearch\Model\Indexer\Scope\IndexTableNotExistException
Magento\CatalogSearch\Model\Indexer\Fulltext\Action\IndexIterator
Magento\CatalogSearch\Model\Adapter\Mysql\Filter\AliasResolver
Copied to your clipboard
Magento\Framework\Search\Adapter\Mysql\DocumentFactory
Magento\Framework\Search\Adapter\Mysql\Mapper
Magento\Framework\Search\Adapter\Mysql\ScoreBuilder
Magento\Framework\Search\Adapter\Mysql\Query\Builder\Match
Magento\Framework\Search\Adapter\Mysql\Field\FieldFactory
Magento\Framework\Search\Adapter\Mysql\Aggregation\Builder
Magento\Framework\Search\Adapter\Mysql\Aggregation\DataProviderContainer
Magento\CatalogSearch\Model\Search\TableMapper
Magento\CatalogSearch\Model\Indexer\IndexerHandler
Magento\CatalogSearch\Model\Indexer\ProductFieldset
Magento\CatalogSearch\Model\Indexer\Scope\IndexTableNotExistException
Magento\CatalogSearch\Model\Indexer\Fulltext\Action\IndexIterator
Magento\CatalogSearch\Model\Adapter\Mysql\Filter\AliasResolver

Functional Testing Framework

MFTF now uses Google Authenticator to execute tests with 2FA enabled. The functional test framework will not work with 2.4.0 without additional configuration steps to enable Google Authenticator. See Configuring Two-Factor Authentication (2FA).

Inventory asynchronous reindex

A new Stock/Source reindex strategy configuration setting option was added to the Admin to prevent index table collisions. The setting has the following options:

• Synchronous
• Asynchronous

Previously, it was possible to have a "burst" of activity that triggered contention of the index process. Even batching and deferring individual updates that were triggering the indexer, it was still highly likely that an index table collision would occur based on "other" activity.

For example, if the indexer was running based on schedule, and replenishment happens manually through the Admin or interaction with an order, indexing would be triggered. Previously, that would result in two processes attempting to index; one of those will "lose", leading to a deadlocked/stale index.

Copy
changed.MAJOR: Magento\InventoryIndexer\Indexer\Stock\StockIndexer::__construct
/InventoryIndexer/Indexer/Stock/StockIndexer.php:28 M113 [public] Method parameter typing changed.
changed.MAJOR: Magento\InventoryIndexer\Indexer\SourceItem\SourceItemIndexer::__construct
/InventoryIndexer/Indexer/SourceItem/SourceItemIndexer.php:27 M113 [public] Method parameter typing changed.
Copied to your clipboard
changed.MAJOR: Magento\InventoryIndexer\Indexer\Stock\StockIndexer::__construct
/InventoryIndexer/Indexer/Stock/StockIndexer.php:28 M113 [public] Method parameter typing changed.
changed.MAJOR: Magento\InventoryIndexer\Indexer\SourceItem\SourceItemIndexer::__construct
/InventoryIndexer/Indexer/SourceItem/SourceItemIndexer.php:27 M113 [public] Method parameter typing changed.

JSON field support

MySQL 5.7 supports the native JSON data type: https://dev.mysql.com/doc/refman/5.7/en/json.html. Version 2.4.0 now supports using JSON fields with a declarative schema.

Laminas

Migrating ZF2 components to Laminas introduced BICs in the following files:

Copy
Magento\Backend\App\Area\FrontNameResolver::_construct - _constructor argument type was changed
Magento\Framework\App\Response\HttpInterface::getHeader - declared return type was changed
Copied to your clipboard
Magento\Backend\App\Area\FrontNameResolver::_construct - _constructor argument type was changed
Magento\Framework\App\Response\HttpInterface::getHeader - declared return type was changed

Both files are API class/interface. These changes will be solved dynamically during runtime if you follow the recommended guidelines.

MediaContent and MediaContentApi modules

The 'MediaContent' and 'MediaContentApi' modules were introduced to provide the ability to manage relationships between content and media assets used in that content.

Additionally, observers have been added to the CMS and Catalog modules to save the relationship of corresponding entities to 'MediaContent' storage.

Method parameter typing changed

Method parameter typing was changed to leverage PHP 7+ Throwables and enable catching ALL possible errors that might expose confidential information, such as passwords.

Level Target/Location Code/Reason

Copy
Magento\Framework\App\Bootstrap::terminate
/lib/internal/Magento/Framework/App/Bootstrap.php:426 M114 [protected] Method parameter typing changed.
Copied to your clipboard
Magento\Framework\App\Bootstrap::terminate
/lib/internal/Magento/Framework/App/Bootstrap.php:426 M114 [protected] Method parameter typing changed.

New bulk interfaces for inventory salability check

In order to support bulk check for products salability, we introduced two new interfaces:

Copy
Magento\InventorySalesApi\Api\AreProductsSalableInterface
Magento\InventorySalesApi\Api\AreProductsSalableForRequestedQtyInterface
Copied to your clipboard
Magento\InventorySalesApi\Api\AreProductsSalableInterface
Magento\InventorySalesApi\Api\AreProductsSalableForRequestedQtyInterface

These changes allow third-party developers to optimize performance by providing an implementation for bulk services.

• Introduced a Bulk version of IsProductSalableForRequestedQtyInterface API
• Introduced a Bulk version of IsProductSalableInterface when working with a list of items

PHP

PHP 7.4 support is added to 2.4.0, and the lowest compatible version is PHP 7.3. As the result, some of the Composer libraries have been updated.

This section lists the backward incompatible changes and deprecated features in PHP 7.4. During development, we also discovered changes in the behavior of the setcookie function:

Copy
setcookie("tst", "Test Message");
print_r(headers_list());
//PHP 7.3
Array
(
    [0] => X-Powered-By: PHP/7.3.14
    [1] => Set-Cookie: tst=Test+Message
)
//PHP 7.4
Array
(
    [0] => X-Powered-By: PHP/7.4.4
    [1] => Set-Cookie: tst=Test%20Message
)
Copied to your clipboard
setcookie("tst", "Test Message");
print_r(headers_list());
//PHP 7.3
Array
(
    [0] => X-Powered-By: PHP/7.3.14
    [1] => Set-Cookie: tst=Test+Message
)
//PHP 7.4
Array
(
    [0] => X-Powered-By: PHP/7.4.4
    [1] => Set-Cookie: tst=Test%20Message
)

PHPUnit

The current PHPUnit framework version used with version 2.4.0 is PHPUnit 9. This requires refactoring most PHPUnit-based tests.

The most critical changes include:

• The methods listed below now have a void return type declaration:

  Copy
  PHPUnit\Framework\TestCase::setUpBeforeClass()
  PHPUnit\Framework\TestCase::setUp()
  PHPUnit\Framework\TestCase::assertPreConditions()
  PHPUnit\Framework\TestCase::assertPostConditions()
  PHPUnit\Framework\TestCase::tearDown()
  PHPUnit\Framework\TestCase::tearDownAfterClass()
  PHPUnit\Framework\TestCase::onNotSuccessfulTest()
  Copied to your clipboard
  PHPUnit\Framework\TestCase::setUpBeforeClass()
  PHPUnit\Framework\TestCase::setUp()
  PHPUnit\Framework\TestCase::assertPreConditions()
  PHPUnit\Framework\TestCase::assertPostConditions()
  PHPUnit\Framework\TestCase::tearDown()
  PHPUnit\Framework\TestCase::tearDownAfterClass()
  PHPUnit\Framework\TestCase::onNotSuccessfulTest()

• The following methods have been removed, and you should change the implementation their tests:

  Copy
  assertAttributeContains()
  assertAttributeNotContains()
  assertAttributeContainsOnly()
  assertAttributeNotContainsOnly()
  assertAttributeCount()
  assertAttributeNotCount()
  assertAttributeEquals()
  assertAttributeNotEquals()
  assertAttributeEmpty()
  assertAttributeNotEmpty()
  assertAttributeGreaterThan()
  assertAttributeGreaterThanOrEqual()
  assertAttributeLessThan()
  assertAttributeLessThanOrEqual()
  assertAttributeSame()
  assertAttributeNotSame()
  assertAttributeInstanceOf()
  assertAttributeNotInstanceOf()
  assertAttributeInternalType()
  assertAttributeNotInternalType()
  attribute()
  attributeEqualTo()
  readAttribute()
  getStaticAttribute()
  getObjectAttribute()
  Copied to your clipboard
  assertAttributeContains()
  assertAttributeNotContains()
  assertAttributeContainsOnly()
  assertAttributeNotContainsOnly()
  assertAttributeCount()
  assertAttributeNotCount()
  assertAttributeEquals()
  assertAttributeNotEquals()
  assertAttributeEmpty()
  assertAttributeNotEmpty()
  assertAttributeGreaterThan()
  assertAttributeGreaterThanOrEqual()
  assertAttributeLessThan()
  assertAttributeLessThanOrEqual()
  assertAttributeSame()
  assertAttributeNotSame()
  assertAttributeInstanceOf()
  assertAttributeNotInstanceOf()
  assertAttributeInternalType()
  assertAttributeNotInternalType()
  attribute()
  attributeEqualTo()
  readAttribute()
  getStaticAttribute()
  getObjectAttribute()

• The signature of assertContains(), assertNotContains(), assertEquals(), and assertNotEquals() were changed. In most cases, more specific methods should be used instead, like assertStringContainsString()

Tips and Tricks

• Use \PHPUnit\Framework\Assert::assertEqualsCanonicalizing() if you need to compare two entities with a different order of elements. assertEquals() has been used before.
• Use \PHPUnit\Framework\Assert::assertEqualsWithDelta() if you need non-strict comparison. assertEquals() with additional parameters has been used before.

Size field added to media_gallery_asset table

This is a dependency for the Adobe Stock integration.

A size field was added to the media_gallery_asset table to enable storing and using the media asset size. The Media Gallery Asset entity model and interface were updated accordingly.

The Magento\MediaGalleryApi\Api\Data\AssetInterface that was updated with a new public method in the scope of the changes is not marked as @api so it is not currently part of the API.

The possible impact is minimal: the table was introduced in 2.3.4 (just several month ago) and it was not used by any Commerce functionality (only Adobe Stock Integration extension).

SVC failure due to adding strict types

This change fixes a bug where getDefaultLimitPerPageValue returns a value that is not available.

As a Store Administrator, you are able to provide the 'Products per Page on Grid Allowed' values and 'Products per Page on Grid Default' value. There is no verification, so you can accidentally set the default value to be one of the unavailable options.

The only stores that might be affected are the ones who changed the configuration value for 'Default items per page', without customizing possible options. Some system integrators customize either the default value or allowed values.

As a result, there is inconsistency between default and allowed values. So far this worked by coincidence, but after the change, that would be explicit.

Per technical guidelines, all new PHP files MUST have strict type mode enabled by starting with declare(strict_types=1);. All updated PHP files SHOULD have strict type mode enabled. PHP interfaces MAY have this declaration.

Strict typing was added to the app/code/Magento/Catalog/Helper/Product/ProductList.php file.

It caused SVC failures.

Return type now array (the same as before in DocBlock):

Copy
changed.MAJOR: Magento\Catalog\Helper\Product\ProductList::getAvailableLimit
/app/code/Magento/Catalog/Helper/Product/ProductList.php:122M120 [public] Method return typing
Copied to your clipboard
changed.MAJOR: Magento\Catalog\Helper\Product\ProductList::getAvailableLimit
/app/code/Magento/Catalog/Helper/Product/ProductList.php:122M120 [public] Method return typing

The input parameter is renamed to viewMode:

Copy
changed.MAJOR: Magento\Catalog\Helper\Product\ProductList::getAvailableLimit
/app/code/Magento/Catalog/Helper/Product/ProductList.php:122V060 [public] Method parameter name
Copied to your clipboard
changed.MAJOR: Magento\Catalog\Helper\Product\ProductList::getAvailableLimit
/app/code/Magento/Catalog/Helper/Product/ProductList.php:122V060 [public] Method parameter name

Now returns int for DefaultLimitPerPageValue:

Copy
changed.MAJOR: Magento\Catalog\Helper\Product\ProductList::getDefaultLimitPerPageValue
/app/code/Magento/Catalog/Helper/Product/ProductList.php:147M120 [public] Method return typing changed.
Copied to your clipboard
changed.MAJOR: Magento\Catalog\Helper\Product\ProductList::getDefaultLimitPerPageValue
/app/code/Magento/Catalog/Helper/Product/ProductList.php:147M120 [public] Method return typing changed.

UrlRewrite module

The Admin grid in the UrlRewrite module was moved to UI components and all unused blocks were removed. Added mass delete and inline edit actions.

Copy
adminhtml.block.url_rewrite.grid.container
adminhtml.block.url_rewrite.grid
adminhtml.url_rewrite.grid.columnSet
adminhtml.url_rewrite.grid.columnSet.url_rewrite_id
adminhtml.url_rewrite.grid.columnSet.store_id
adminhtml.url_rewrite.grid.columnSet.request_path
adminhtml.url_rewrite.grid.columnSet.target_path
adminhtml.url_rewrite.grid.columnSet.redirect_type
adminhtml.url_rewrite.grid.columnSet.actions
Copied to your clipboard
adminhtml.block.url_rewrite.grid.container
adminhtml.block.url_rewrite.grid
adminhtml.url_rewrite.grid.columnSet
adminhtml.url_rewrite.grid.columnSet.url_rewrite_id
adminhtml.url_rewrite.grid.columnSet.store_id
adminhtml.url_rewrite.grid.columnSet.request_path
adminhtml.url_rewrite.grid.columnSet.target_path
adminhtml.url_rewrite.grid.columnSet.redirect_type
adminhtml.url_rewrite.grid.columnSet.actions

UUID validator

This code adds the Ramsey library as a UUID validator and creates wrappers for it. This feature is needed for the async-import project. They pass UUID to get status of the async-import, for that they need to validate UUID.

Last updated 10/30/2024

Was this helpful?

Yes

No