Skip to content

Config step conditions

Step conditions control the visibility of checkout steps and the inclusion of layout handles in Hyvä Checkout. Conditions allow you to show or hide steps based on customer state, quote properties, or custom business logic.

Step conditions can be used in hyva_checkout.xml configuration in two ways: within a <condition if="..."> element to control step visibility, or within an <update if="..."> attribute to conditionally include layout handles.

The value of the if attribute accepts either a step condition identifier (a readable alias mapped to a class) or a condition class name (a fully qualified PHP class name). When multiple <condition if="..."> elements exist on a single step, the step will only be shown if all conditions evaluate to true.

Using step conditions in XML

The following example demonstrates both uses of step conditions in hyva_checkout.xml. The <update> element conditionally includes layout XML only when a condition is met, while the <condition> element controls whether the entire step appears:

<step name="example-step">
    <!-- Only include the example_handle.xml layout XML if the "is_physical" condition is true -->
    <update handle="example_handle" if="is_physical"/>

    <!-- Only show the "example-step" step if the "is_customer" condition is true -->
    <condition name="guest_login" if="is_customer"/>
</step>

Some common step condition identifiers are available out of the box:

  • is_always_allow - Always evaluates to true
  • is_customer - True if the customer is logged in
  • is_device - True if mobile device
  • is_guest - True if the customer is a guest (not logged in)
  • is_physical - True if the quote contains physical products
  • is_virtual - True if the quote contains only virtual products

Step condition identifiers

Step condition identifiers provide readable aliases for condition class names, improving the maintainability of hyva_checkout.xml files. These identifiers are mapped to class names via etc/frontend/di.xml dependency injection configuration.

The default step condition identifiers are declared in vendor/hyva-themes/magento2-hyva-checkout/src/etc/frontend/di.xml. This configuration maps each identifier to its implementing class:

<type name="Hyva\Checkout\Model\CustomConditionFactory">
    <arguments>
        <argument name="customConditionTypes" xsi:type="array">
            <item name="is_always_allow" xsi:type="string">Hyva\Checkout\Model\CustomCondition\IsAlwaysAllow</item>
            <item name="is_customer" xsi:type="string">Hyva\Checkout\Model\CustomCondition\IsCustomer</item>
            <item name="is_guest" xsi:type="string">Hyva\Checkout\Model\CustomCondition\IsGuest</item>
            <item name="is_physical" xsi:type="string">Hyva\Checkout\Model\CustomCondition\IsPhysical</item>
            <item name="is_virtual" xsi:type="string">Hyva\Checkout\Model\CustomCondition\IsVirtual</item>
            <item name="is_device" xsi:type="string">Hyva\Checkout\Model\CustomCondition\IsDevice</item>
        </argument>
    </arguments>
</type>

Custom step condition identifiers can be added to this array using your module's di.xml file. However, unless a condition will be reused frequently across multiple configurations, it is often simpler to use the condition class name directly as the value of the if attribute.

The following example shows how to use a fully qualified class name directly in the if attribute without registering a condition identifier:

<step name="example-step">
    <update handle="example_handle" if="My\Module\Model\Checkout\StepCondition\ExampleStepCondition"/>
    <condition name="show_if_valid" if="My\Module\Model\Checkout\StepCondition\ExampleStepCondition"/>
</step>

Step condition classes

Step condition classes must implement the Hyva\Checkout\Model\CustomConditionInterface interface. This interface declares a single method: public function validate(): bool. The validate method returns true when the condition is met and false otherwise.

For <condition> elements, an optional method attribute can specify an alternative validation method name. This allows grouping multiple related condition variations within a single class to avoid code duplication.

The following example shows how to use the method attribute to call a custom validation method instead of the default validate method:

<condition name="show_login" if="is_customer" method="required"/>

If no method attribute is specified, the default method validate will be called on the condition class.