Plugin vs Preference — When to Use Each

Preference Declaration

A preference replaces a class entirely via DI:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="Magento\Catalog\Model\Product"
                type="Vendor\Module\Model\Product"/>
</config>

How It Works

// Original class
namespace Magento\Catalog\Model\Product;
class Product {
    public function getName() { return $this->name; }
}

// Your replacement
namespace Vendor\Module\Model;
class Product extends \Magento\Catalog\Model\Product {
    public function getName() {
        return parent::getName() . ' (Modified)';
    }
}

When ObjectManager creates Product, it actually creates your Vendor\Module\Model\Product.

Interface Preferences

<preference for="Magento\Catalog\Api\ProductRepositoryInterface"
            type="Vendor\Module\Api\ProductRepository"/>

This replaces the default implementation of the interface.

Appropriate Use Cases

1. Replacing default implementations of interfaces

<preference for="Magento\Search\Model\SearchEngineInterface"
            type="Vendor\CustomSearch\Model\SearchEngine"/>

2. Adding behavior to classes without events/plugins

// Override save() to add custom validation
public function save() {
    $this->validateCustomFields();
    return parent::save();
}

3. Fixing bugs in core classes (temporary, then upgrade)

public function getData($key = null) {
    // Fix for known bug
    if ($key === 'special_field') {
        return $this->fixSpecialField();
    }
    return parent::getData($key);
}

4. Adding methods to existing classes

public class ExtendedProduct extends Product {
    public function getExtendedData() {
        // New method not in original class
    }
}

Not Appropriate For

• Modifying behavior that plugins can handle
• Adding side effects (use observers)
• Temporary overrides (use plugins or config)
• Replacing core classes without clear need

Only One Preference Per Class

Only one preference can exist for any class or interface. If two modules define preferences for the same class, one wins based on module load order.

<!-- Module A -->
<preference for="Magento\Catalog\Model\Product" type="Vendor\A\Product"/>

<!-- Module B -->
<preference for="Magento\Catalog\Model\Product" type="Vendor\B\Product"/>

<!-- Only one will be used — unpredictable which one wins -->

Upgrade Fragility

Preferences override the entire class. When Magento upgrades and changes the original class, your preference may break.

// Your preference from Magento 2.4.3
public function save() {
    // Override based on original implementation
    $this->validate();
    parent::save();
}

// Magento 2.4.4 changes save() internals
// Your preference breaks silently or throws errors

Cannot Compose

Preferences cannot be composed. You cannot stack multiple preferences on the same class.

Testing Difficulty

Preferences make testing harder because they replace the entire class. Unit tests may need to mock the full class instead of just the interface.

Performance Impact

Preferences affect all instances of a class across the entire application, not just specific method calls.

Composability

Multiple plugins can coexist on the same class:

<!-- Module A -->
<type name="Magento\Catalog\Model\Product">
    <plugin name="module_a" type="Vendor\A\Plugin" sortOrder="10"/>
</type>

<!-- Module B -->
<type name="Magento\Catalog\Model\Product">
    <plugin name="module_b" type="Vendor\B\Plugin" sortOrder="20"/>
</type>

Both plugins execute without conflict.

Granular Control

Plugins target specific methods:

<type name="Magento\Catalog\Model\Product">
    <plugin name="enhance_name" type="Vendor\Plugin\ProductNamePlugin"/>
</type>

Only getName() is affected; other methods remain untouched.

Easy Disabling

<type name="Magento\Catalog\Model\Product">
    <plugin name="third_party_plugin" disabled="true"/>
</type>

Disable without removing code.

Upgrade Safety

Plugins survive Magento upgrades because they wrap methods rather than replacing classes. If the original method changes, the plugin continues to work.

Comparison Table