Magento 2 - di.xml virtual type - overriding a class

Magento 2 - di.xml virtual type - overriding a class

July 22, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento 2 - di.xml virtual type - overriding a class

[Blog Post]

Overriding Classes in Magento 2: The di.xml Virtual Type Approach

Hello developers! Today we’re going to dive into an interesting aspect of Magento 2 development - overriding classes using the di.xml virtual type configuration. This powerful technique allows you to replace core Magento classes with your own implementations while ensuring compatibility and preventing type parsing errors.

Understanding the Challenge

Our reader is facing a common issue while trying to override the ShippingMethodConverter class in their module. They’ve set up the di.xml preferences correctly, but are encountering an exception during execution:

Exception #0 (Exception): Recoverable Error: Argument 2 passed to Magento\Quote\Model\ShippingMethodManagement::__construct() must be an instance of Magento\Quote\Model\Cart\ShippingMethodConverter, instance of MyNameSpace\MyModule\Quote\Model\Cart\ShippingMethodConverter given, called in /path_to_magento/vendor/magento/framework/ObjectManager/Factory/AbstractFactory.php on line 93 and defined in /path_to_magento/vendor/magento/module-quote/Model/ShippingMethodManagement.php on line 62

The error message suggests that the core Magento class is expecting an instance of Magento\Quote\Model\Cart\ShippingMethodConverter, but it’s receiving an instance of our custom class instead.

The Virtual Type Approach

To resolve this issue, we need to use a virtual type in the di.xml file. This technique allows us to create an alias for our custom class that matches the interface or parent class specified by Magento.

Here’s how you can set up the virtualType:

<virtualType name="mynamespace_mymodule_quote_mode_cart_shippingmethodconverter" type="\MyNameSpace\MyModule\Quote\Model\Cart\ShippingMethodConverter">
    <arguments>
        <argument name="shippingMethodConverter" xsi:type="object">Magento\Quote\Model\Cart\ShippingMethodConverter</argument>
    </arguments>
</virtualType>

In this configuration:

  1. name: Define a unique name for the virtual type, following the pattern <your_namespace>_<your_module>_<type_name>.
  2. type: Specify the fully qualified namespace of your custom class.
  3. arguments: Provide an argument named after the parent class or interface Magento expects.

Ensuring Compatibility

The key to making this approach work is ensuring that your custom class implements the same methods and properties as the core Magento class it’s replacing.

In our case, you should ensure that your ShippingMethodConverter class:

  • Has the same constructor signature as the core Magento\Quote\Model\Cart\ShippingMethodConverter.
  • Implements all public methods required by the Magento core.
  • Maintains the same property structure for compatibility.

Best Practices

While using virtual types is effective, remember to follow these best practices:

  1. Keep your custom class name and namespace consistent with the Magento naming conventions.
  2. Ensure your module’s di.xml file is located in the correct path (app/code/<Vendor>/<Module>/etc/di.xml).
  3. Test your implementation thoroughly to avoid breaking other features or modules.

Conclusion

Overriding classes in Magento 2 using virtual types in di.xml can be a powerful tool, but it requires careful configuration and compatibility checking.

By understanding the core Magento class’s expectations and implementing the appropriate methods in your custom class, you can successfully replace functionality without encountering type parsing errors or breaking other parts of the system.

Remember to always keep your code clean, well-documented, and consistent with Magento’s best practices for maintainability and upgrade compatibility. For more detailed guides on Magento 2 development techniques, check out Laravel Company’s comprehensive tutorials.

Happy coding! Let us know if you have any other questions or need further clarification.

Magento 2 Checkout API Extensions

Our network