EntityForm Interface Reference for Hyvä Checkout
The Hyvä Checkout form customization system provides a family of PHP interfaces for building and customizing address forms in the checkout process. This page describes the core interfaces that serve as building blocks for form customizations in Hyvä Checkout.
Understanding these interfaces helps you determine which components to use when customizing shipping and billing address forms. Most customizations interact with these interfaces rather than implementing them directly.
EntityFormInterface - The Form Container
Interface: \Hyva\Checkout\Model\Form\EntityFormInterface
The EntityFormInterface represents the complete form for collecting entity data. Hyvä Checkout provides two implementations of this interface:
EavAttributeShippingAddressForm- Handles shipping address collectionEavAttributeBillingAddressForm- Handles billing address collection
These implementations are provided by Hyvä Checkout core. Custom implementations are technically possible but not expected for typical customizations. Most developers interact with existing form instances through form modifiers rather than creating new form implementations.
EntityFormElementInterface - Generic Form Components
Interface: \Hyva\Checkout\Model\Form\EntityFormElementInterface
An EntityFormElementInterface represents any component that appears in a form. This includes input fields, informational text, graphics, separators, or any other visual or structural element.
Form elements support hierarchical organization, allowing related elements to be grouped together for rendering. This hierarchical structure helps maintain visual organization in the checkout address forms.
Elements are the most flexible building block - use this interface when you need to add non-input components like help text, images, or structural containers to the form.
EntityFieldInterface - Input Elements
Interface: \Hyva\Checkout\Model\Form\EntityFieldInterface
The EntityFieldInterface represents form input elements specifically - the fields where users enter data. EntityFieldInterface extends EntityFormElementInterface, inheriting all element capabilities while adding input-specific functionality.
Form fields handle user input, validation, and value persistence. Use fields when you need to collect data from users in the Hyvä Checkout address forms.
EntityFormModifierInterface - The Customization Entry Point
Interface: \Hyva\Checkout\Model\Form\EntityFormModifierInterface
EntityFormModifierInterface provides the primary entry point for customizing Hyvä Checkout forms. Form modifiers register callbacks for form lifecycle events, allowing you to add, remove, or manipulate form elements at appropriate times.
Most Hyvä Checkout form customizations begin by implementing this interface. The modifier pattern allows multiple customizations from different modules to coexist without conflicts.
See the Implementing EntityFormModifierInterface page for detailed implementation guidance.
RendererInterface - Display Customization
Interface: \Hyva\Checkout\Model\Form\EntityFormElement\RendererInterface
The RendererInterface controls how form elements are rendered as HTML. Hyvä Checkout provides default implementations that handle standard rendering scenarios.
You rarely need to implement this interface directly. The default renderer implementation accepts customizations through configuration rather than requiring new implementations. Use renderer customization when you need to change the HTML output or CSS classes of form elements.
EntityFormSaveServiceInterface - Data Persistence
Interface: \Hyva\Checkout\Model\Form\EntityFormSaveServiceInterface
Each EntityFormInterface implementation requires a matching EntityFormSaveServiceInterface implementation to handle data persistence. The save service receives validated form data and stores it to the appropriate Magento entities.
Hyvä Checkout includes save services for both shipping addresses and billing addresses. If you create a custom EntityFormInterface implementation (rare), you must also implement a corresponding save service to persist the form data.