Form Modification Hooks

Hyvä Checkout form modification hooks let you customize forms at specific points in the form lifecycle. Each hook fires at a different stage, from initial construction through to final rendering, and provides different callback arguments. Understanding which hook to use is essential for making clean, targeted form customizations.

The hook set differs between the release lines. Checkout 3.x adds a form:*:magewire hook for every Magewire lifecycle step and keeps the Checkout 1.x address form hooks as deprecated legacy hooks, so most existing modifiers keep working. See Hyvä Checkout Release Lines for the background.

Modification Guidelines

Form modifications are intended for minor adjustments such as changing labels, adding CSS classes, inserting an individual field, or modifying field properties. Modification hooks are not designed for major overhauls like adding many fields at once.

For extensive changes, consider creating separate custom forms and conditionally rendering them based on context. For example, you could use tabs to switch between different form layouts.

Registering a Hook Listener

You register a listener inside a form modifier's apply() method with registerModificationListener(). The first argument is a listener name that must be unique per form (registering the same name twice throws a FormException), the second is the hook name, and the third is the callback.

$form->registerModificationListener(string $name, string $event, callable $listener);

Hyvä Checkout dispatches hooks on two layers:

• Entity form hooks (form:*) are dispatched by Hyva\Checkout\Model\Form\AbstractEntityForm during the form's own build pipeline. They fire for every form, whatever drives it. The listener receives the form as its first argument.
• Magewire component hooks (form:*:magewire) are dispatched by the Magewire form component Hyva\Checkout\Magewire\Component\AbstractForm on its lifecycle steps. They fire only for Magewire-driven forms. The listener receives the form, then the component, then any hook-specific arguments.

The address form hooks (form:boot, form:updated, form:field:updated, form:action:edit, form:action:create and their address type variants) come from the address form component:

Hook Lifecycle Order

The hooks fire in this order during the form lifecycle:

Magewire Component Hooks

Every form driven by Hyva\Checkout\Magewire\Component\AbstractForm (the guest details form, the coupon code form, and your own Magewire-driven forms) dispatches form:*:magewire hooks on its lifecycle steps. The listener signature is ($form, $component, ...$args).

form:init Hook

The form:init hook fires whenever a form is constructed. Use form:init to add or remove form fields, or to adjust the form itself along with its fields and values.

form:populate Hook

The form:populate hook fires immediately after form:init, once all fields have been populated and all built-in modifiers have been applied. Use form:populate to make additional modifications to the form after the standard initialization is complete.

form:boot Hook

The form:boot hook fires after a form is fully constructed and all fields have been filled with their intended data. Use form:boot to alter field values right after initialization is complete.

form:build Hook

The form:build hook fires before the form is rendered. Use form:build to make visual-only changes such as adding extra CSS classes or styles to fields.

On both release lines, form:build fires once per render, from the entity form itself. The Checkout 3.x address forms don't re-emit it.

form:build:magewire Hook

The form:build:magewire hook is an additional build-phase hook for Magewire-specific adjustments. Use form:build:magewire to add or modify Magewire attributes like wire:model or wire:target.

Internally, Hyvä Checkout uses the form:build:magewire hook to add all necessary Magewire attributes. Use this hook when you need to modify or remove a Magewire attribute that was added by core.

form:updated Hook

The form:updated hook fires when form field values change during subsequent (non-initial) requests. In addition to the generic form:updated hook, address-specific hooks form:shipping:updated and form:billing:updated are available.

Use form:updated to alter the value of fields based on the values of other fields.

$form->registerModificationListener(
    'applyMyBillingModifications',
    'form:updated:data:postcode:magewire',
    function (AbstractEntityForm $form, ...$rest) use ($apiCall) {
        // Get the current postcode field value.
        $postcodeValue = $form->getField('postcode')->getValue();

        // Call an external API to look up the street by postcode.
        $streetValue = $apiCall->getStreetByZipcode($postcodeValue);

        if ($streetValue) {
            $form->getField('street')->setValue($streetValue);
        }
    }
);

$form->registerModificationListener(
    'applyMyBillingModifications',
    'form:billing:updated',
    // Leave $addressComponent untyped, so the listener also runs on Checkout 3.x.
    function (EntityFormInterface $form, $addressComponent) use ($apiCall) {
        // Get the current postcode field value.
        $postcodeValue = $form->getField('postcode')->getValue();

        // Call an external API to look up the street by postcode.
        $streetValue = $apiCall->getStreetByZipcode($postcodeValue);

        if ($streetValue) {
            $form->getField('street')->setValue($streetValue);
        }

        return $form;
    }
);

form:field:updated Hook

The form:field:updated hook fires when a specific field value is updated during subsequent requests. Use form:field:updated to transform or validate a single field's value at the moment it changes.

$form->registerModificationListener(
    'applyMyShippingPostcodeModifications',
    'form:updated:data:postcode:magewire',
    function (AbstractEntityForm $form, ...$rest) {
        $form->modifyField('postcode', function (EntityFieldInterface $field) {
            $field->setValue(ucfirst((string) $field->getValue()));
        });
    }
);

$form->registerModificationListener(
    'applyMyShippingPostcodeModifications',
    'form:shipping:postcode:updated',
    // Leave $addressComponent untyped, so the listener also runs on Checkout 3.x.
    function (EntityFormInterface $form, EntityFieldInterface $field, $addressComponent) {
        $field->setValue(ucfirst($field->getValue()));

        return $form;
    }
);

form:action:edit Hook

The form:action:edit hook fires when a visitor clicks the shipping or billing "Edit Address" button. Use form:action:edit to customize form behavior when an existing address is loaded for editing.

form:action:create Hook

The form:action:create hook fires when a visitor clicks a shipping or billing "New Address" button. Use form:action:create to customize form behavior when a blank address form is opened.

Legacy Hooks on Checkout 3.x

AbstractAddressForm re-emits the Checkout 1.x address form hooks, without the :magewire suffix, so existing third-party modifiers keep working. Each legacy hook mirrors a modern one:

The bare form:build hook isn't in this list because the entity form already dispatches it natively on both release lines. It fires once per render, so don't expect a second call. The entity form hook form:fill is deprecated on Checkout 3.x: it fires from many places per request, so use form:loaded:magewire instead.

Listener Type Hints on Checkout 3.x

Type-hint the component argument of your listeners carefully. A listener that throws (for example with a TypeError) is caught and logged by dispatchModificationHook(), so it silently stops running.

Keep these points in mind when you port a Checkout 1.x listener:

• Methods of the deprecated component are gone. Listeners that call methods of AbstractMagewireAddressForm, such as store(), save(), autosave(), getSaveDateTime(), populateAddressProperty(), getDifferences() or emitByAddressType(), or read $component->modal['shown'], fail on Checkout 3.x. Use modification hooks instead.
• Accept extra arguments. Several :magewire hooks pass their extra arguments as PHP named arguments (for example property and value). On Checkout 3.x, a listener gets the arguments it declares by name and the others in parameter order, so its parameter names don't have to match the hook's. Code that also runs on Checkout 1.x keeps a trailing ...$rest.

The following listener works on both release lines because it leaves the component untyped and accepts any extra arguments:

$form->registerModificationListener(
    'myShippingBootListener',
    'form:shipping:boot',
    function (EntityFormInterface $form, $addressComponent = null, ...$rest) {
        // Your modification.
    }
);

Logging Deprecated Hook Usage

Checkout 3.x can log every listener that is still registered on a deprecated hook. Enable Stores > Configuration > Hyvä Checkout > General > Developer > Shipping- & Billing Forms > Log Deprecated Form Hook Usage (config path hyva_themes_checkout/developer/shipping_billing_form/log_deprecated_hooks).

When a deprecated hook with a registered listener fires, Hyvä Checkout writes a warning to var/log/system.log that names the listener and the hook to migrate to. The setting has no effect in production mode. The deprecated aliases of the AbstractForm hooks, such as form:mount:magewire and form:execute:submit:magewire, are logged in developer mode only.

Choosing a Hook on Checkout 3.x

Pick the hook by what your modifier does:

• Build options or derive a field value from the loaded data: form:loaded:magewire. It runs before the data property sync, so resolved values reach the frontend.
• React to one field changing: form:updated:data:<field>:magewire.
• Rebuild dependent fields when a controlling field changes (for example region options when the country changes): form:updated:data:country_id:magewire.
• Adjust data or cancel before saving: form:submitting:magewire.
• Run logic after a save attempt: form:trigger:submit:magewire. It also fires after a failed save, so check $exception to tell whether the save succeeded.
• Add fields or elements up front: form:construct:magewire.
• Avoid form:fill and form:execute:submit:magewire, which are deprecated.

The core region modifier (WithRegionModifier) combines these hooks. The following listeners build the region options on load, keep a form:build:magewire listener for the deprecated Checkout 1.x address form components, and rebuild the options when the country changes:

// Build region <select> options before the data property is synced, so the saved
// region resolves to its region_id and wire:model pre-selects it on load.
$form->registerModificationListener('applyRegionOptionsByCountryValueOnLoad', 'form:loaded:magewire',
    fn (AbstractEntityForm $form) => $this->applyRegionOptionsByCountryValue($form));

// Kept for the deprecated AbstractMagewireAddressForm components (no form:loaded:magewire). Idempotent.
$form->registerModificationListener('applyRegionOptionsByCountryValue', 'form:build:magewire',
    fn (AbstractEntityForm $form) => $this->applyRegionOptionsByCountryValue($form));

// Rebuild the options when the country changes during the request.
$form->registerModificationListener('applyRegionOptionsByCountryValueOnCountryUpdate',
    'form:updated:data:country_id:magewire',
    fn (AbstractEntityForm $form) => $this->applyRegionOptionsByCountryValue($form));

The complete hook reference ships with the module in vendor/hyva-themes/magento2-hyva-checkout/src/Model/Form/EntityFormModifier/form_hooks.md.