This post describes changes made to the Mail library in Magento 2.3.3 and explains the actions that merchants and extension developers need to take to ensure that extensions that use Mail library compatibility with these changes.
Backward-incompatible Changes
The Magento\Email\Model\Transport class has been changed as follows:
- The type of the $message constructor parameter has been changed from Magento\Framework\Mail\MessageInterface to Magento\Framework\Mail\EmailMessageInterface
- The return type of the getMessage method has been changed from Magento\Framework\Mail\MessageInterface to Magento\Framework\Mail\EmailMessageInterface
Recommendations for Merchants
Merchants should apply the Mail library patch (available from Magento Tech Resources) as soon as possible, especially if their deployments include extensions or customizations that use the Mail library.
This patch fixes the type of the constructor parameter, getMessage method return value and makes EmailMessageInterface extend MailMessageInterface. These changes will be included in Magento 2.3.4.
Recommendations for Extension Developers
Extension developers should both advise the merchants who use their extensions to apply the patch as well as update their extensions to be compatible with Magento 2.3.3 and 2.3.3 with the patch.
Extension developers should update their extensions to ensure compatibility with Magento 2.3.2, 2.3.3, and 2.3.4 (not yet released) by applying the following changes:
Usage scenario: A custom class inherits from
Magento\Framework\Mail\Template\TransportBuilder and relies on the protected $message property.
Solution: Use instanceof to determine which class is sending $message before using this property.
if ($message instanceof \Magento\Framework\Mail\MessageInterface) {
// Keep existing behavior here
} else {
// Introduce new behavior here
}
Usage scenario: The use of MessageInterface in a method signature.
Solution: Loosen typing by removing MessageInterface from the method signature and instead use instanceof check.
Usage scenario: Any plugin for Magento\Framework\Mail\TransportInterface that uses $subject->getMessage().
Solution: Use instanceof to determine which class is sending $message before using this property.
Usage scenario: Any client code that uses Magento\Framework\Mail\TransportInterface::getMessage() will now get an instance of EmailMessageInterface instead of MessageInterface.
Solution: Use instanceof to determine which class is sending $message before using this property.
Usage scenario: Instantiation of Magento\Email\Model\Transport using factory now requires a message argument to implement the new EmailMessageInterface.
Solution: Use Magento\Framework\Mail\Template\TransportBuilder instead.
Usage scenario: Calling getBody/getMessageBody on EmailMessageInterface.
Solution: Use instanceof MessageInterface on $message. If $message is an instance of MessageInterface, call getMessageBody. Otherwice call getBody.
Additional Notes
- MailMessageInterface and Magento\Framework\Mail\Message have been deprecated.
- EmailMessageInterface temporarily extends MailMessageInterface, but methods that belong to MailMessageInterface may be removed in Magento 2.4.
- We recommend not to use deprecated methods and use only methods of EmailMessageInterface itself (not inherited methods) to have extensions aligned with changes that may be done in Magento 2.4.
