Form modification hooks

Modifications hooks are called at several points within the form lifecycle, starting at the construction and firing throughout the process until the final rendering. These hooks provide different callback arguments depending on the hook itself. Here you can read all about the available hooks, when to be used and when they are being triggered.

How do I choose the right hook for the job?

Finding the right modification hook (and modifier sort order) may not be straightforward.

Not every type of form and field manipulation is possible in every hook, so the desired effect also determines the hook that should be used.

If more than one modifier alter the same field, both the modifier sortOrder and the hook execution order influence the order in which the callbacks are executed. For example, a form:build hook with a high sort order will still be executed before a form:build:magewire hook with a lower sort order.

form:init

Use this hook to add or remove form fields, or adjust the form itself, along with its fields and values.

This hook is triggered whenever a form is constructed.

Callback Parameters	Preceding	Subsequent	Since	Associated hooks
1. EntityFormInterface $form	Yes	Yes	1.1.0	form:populate

form:boot

Use this hook to alter field values right after a form was initialized and all fields were filled with their intended data. This hook is triggered when a form is completely constructed and filled out.

Callback Parameters	Preceding	Subsequent	Since	Associated hooks
1. EntityFormInterface $form 2. MagewireAddressFormInterface $addressComponent	Yes	Yes	1.1.2	form:[ADDRESS_NAMESPACE]:boot

form:build

Use this hook to make visual changes to a form before it is rendered.
For example, you can add extra styles to fields. It is NOT intended for functional changes.
Do not use this hook to add or remove fields.

Callback Parameters	Preceding	Subsequent	Since
1. EntityFormInterface $form	Yes	Yes	1.1.0

form:build:magewire

Magewire driven forms only

Not all forms are Magewire forms (even though the address forms are).
This additional 'build' hook is intended to be used for making Magewire-specific adjustments.
For instance, you could add a special Magewire fields like wire:model or wire:target.

Internally, this hook is used to add all the necessary Magewire attributes.
You should utilize this hook if you want to make changes like removing a previously added attribute from the core.

Callback Parameters	Preceding	Subsequent	Since
1. EntityFormInterface $form	Yes	Yes	1.1.0

form:updated

In addition to the generic form:updated hook, there also are form specific hooks form:shipping:updated the form:billing:updated.
Use this hooks to alter the value of fields based on the values others fields.
However, be aware that this hook is only triggered during subsequent requests.

Callback Parameters	Preceding	Subsequent	Since	Associated hooks
1. EntityFormInterface $form 2. MagewireAddressFormInterface $addressComponent	No	Yes	1.1.2	form:[ADDRESS_NAMESPACE]:updated

Example:

$form->registerModificationListener(
    'applyMyBillingModifications',
    'form:billing:updated',
    fn(EntityFormInterface $form, MagewireAddressFormInterface $addressComponent) => {
        // Get the postcode field value.
        $postcodeValue = $form->getField('postcode')->getValue();
        // Talk with the API to retrieve a street value.
        $streetValue = $apiCall->getStreetByZipcode($postcodeValue);

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

        return $form;
    }
);

form:field:updated

Use this hook to alter the value of a field when it is being updated.
However, be aware that this hook is only triggered during subsequent requests.

Callback Parameters	Preceding	Subsequent	Since	Associated hooks
1. EntityFormInterface $form 2. EntityFieldInterface $field 3. MagewireAddressFormInterface $addressComponent	No	Yes	1.1.0	1. form:[FIELD_ID]:updated 2. form:[ADDRESS_NAMESPACE][FIELD_ID]:updated

For example:

$form->registerModificationListener(
    'applyMyShippingPostcodeModifications',
    'form:shipping:postcode:updated',
    fn(EntityFormInterface $form, EntityFieldInterface $field, MagewireAddressFormInterface $addressComponent) => {
        $field->setValue( ucfirst($field->getValue()));

        return $form;
    }
);

form:action:edit

This hook is triggered when a visitor clicks the shipping or billing "Edit Address" button.

Callback Parameters	Preceding	Subsequent	Since	Associated hooks
1. EntityFormInterface $form 2. AddressInterface $address	No	Yes	1.1.0	form:[FORM_NAMESPACE]:action:edit

form:action:create

When a visitor clicks a shipping or billing "New Address" button.

Callback Parameters	Preceding	Subsequent	Since	Associated hooks
1. EntityFormInterface $form	No	Yes	1.1.0	form:[FORM_NAMESPACE]:action:create