Skip to content

Hyvä Checkout Backwards Compatibility

Hyvä Checkout V1 was built on Magewire V1, which tracked Livewire V2. The magewirephp/magewire-hyva-checkout package contains integration intended to enable Magewire's BC layer for components in the hyva-checkout-main layout container.

Use explicit attributes with Magewire 3.5

The current core layout resolver writes an explicit disabled BC flag before the companion package's container fallback checks for an unset value. As a result, automatic container opt-in is not a reliable migration guarantee in the current source. Add the attribute explicitly to legacy checkout components and verify their snapshots until the integration is corrected upstream.

The automatic rule

Any component rendered inside (or nested under) the hyva-checkout-main container has its memo.bc.enabled flag set to true unless explicitly overridden.

hyva-checkout-main
├── CheckoutShipping           → BC enabled
├── CheckoutPayment            → BC enabled
│   └── PaymentMethodSelector  → BC enabled (parent is BC)
└── CheckoutSummary            → BC enabled

This covers the V1 checkout's entire component tree without touching a single PHP class.

Opting out per component

Once you rewrite a checkout component to be V3-native end-to-end, opt it out so it stops paying the shim cost:

use Magewirephp\Magewire\Features\SupportMagewireBackwardsCompatibility\HandleBackwardsCompatibility;

#[HandleBackwardsCompatibility(enabled: false)]
class CheckoutShipping extends \Magewirephp\Magewire\Component { /* … */ }

The explicit attribute beats the container rule.

Opting in outside the container

For a legacy component rendered outside hyva-checkout-main (a mini-cart, a CMS widget):

#[HandleBackwardsCompatibility]
class MiniCart extends \Magewirephp\Magewire\Component { /* … */ }

Dynamic components

The companion integration also attempts to inherit BC status from a parent through its hydration registry. Treat that as a convenience, not a substitute for explicit component attributes during a migration.

What the Hyvä BC layer does (under the hood)

The compat module ships four phtml scripts that together implement the shim:

File Role
magewire-attributes.phtml Rewrites wire:model / .defer / .lazy / .delay.Xms on element.init and morph.updating.
magewire-hooks.phtml Promise-based runner for deprecated hook names. Warns once per hook in debug mode.
magewire-events.phtml Re-triggers deprecated events (component.initialized etc.) from their V3 replacements. Aliases component.data, component.deferredActions.
magewire-components.phtml Proxies Magewire.find(id).__instance so $wire.entangle() is live-by-default inside BC components.

All four are registered into the magewire.internal.backwards-compatibility container. They only run when memo.bc.enabled is truthy on the component.

Removing the BC layer

When every Hyvä Checkout component on your install is V3-native:

  1. Remove #[HandleBackwardsCompatibility] attributes where present.
  2. Remove the Hyvä Checkout BC Feature from your theme compat module's etc/frontend/di.xml.
  3. Flush cache and run the checkout end-to-end.

If any checkout component was relying on the automatic rule without the attribute, it will now break; adding the attribute explicitly is a safe intermediate step.