Form modification hooks

Choosing a hook

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:fill

This hook is triggered every time an array is used to fill a form.
This is also true when a parent (ancestor) field is populated with values for its child (relative) elements, causing this hook to trigger recursively.
Use this hook to change field values, whether it's a single field or for multiple fields of a form.

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

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

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	1. 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