Evaluation examples
The Hyvä Checkout Evaluation API enables custom validation, frontend execution, and payment integration across Magewire components and Place Order Services. This page demonstrates practical implementation patterns for common use cases.
New features since 1.1.13 will be marked.
Credit card authorization
This example shows how to validate payment method fields before allowing checkout navigation or order placement. Custom validation executes when the customer clicks the primary navigation button, displaying a loading indicator until completion. If validation fails, an error message appears within the component. If successful, the customer proceeds to the next step.
Create the component
This Magewire component implements the EvaluationInterface to validate a credit card field when the customer attempts to navigate forward.
<?php
use Magewirephp\Magewire\Component;
use Hyva\Checkout\Model\Magewire\Component\EvaluationInterface;
use Hyva\Checkout\Model\Magewire\Component\EvaluationResultFactory;
use Hyva\Checkout\Model\Magewire\Component\Evaluation\EvaluationResult;
class Cc extends Component implements EvaluationInterface
{
public function evaluateCompletion(EvaluationResultFactory $resultFactory): EvaluationResult
{
/*
* Since 1.1.13
*
* Direct the frontend to execute "validateMyCustomCcComponent" and
* trigger an error message event in case of failure.
*/
return $resultFactory->createValidation('validateMyCustomCcComponent')
->withFailureResult(
$resultFactory->createErrorMessageEvent()
->withCustomEvent('payment:method:error')
->withMessage('Invalid credit card details provided. Please try again.')
->withVisibilityDuration(5000)
);
/*
* Before 1.1.13
*
* Either need to provide a mock success result or not implement the EvaluationInterface.
*/
return $resultFactory->createSuccess();
}
}
Inject the component into the checkout
Register the payment method component using the hyva_checkout_components.xml layout handle. The checkout framework automatically searches for a block matching the payment method alias and renders its template.
For complete payment method integration instructions, see the Payment Integration API documentation.
<!-- File: view/frontend/layout/hyva_checkout_components.xml -->
<referenceBlock name="hyva.checkout.components">
<block
name="checkout.payment.method.cc"
as="cc"
template="My_Example::checkout/payment/method/cc.phtml"
>
<arguments>
<argument name="magewire" xsi:type="object">
\My\Example\Magewire\Checkout\Payment\Method\Cc
</argument>
</arguments>
</block>
</referenceBlock>
Create the frontend validation
Register the frontend validator callback that executes when the customer attempts to navigate forward. While this script can be placed directly in the component's PHTML template, injecting it into the hyva.checkout.api-v1.after or hyva.checkout.init-evaluation.after containers improves maintainability.
<script>
/*
* Since 1.1.13
*
* We wait for the evaluation API to be initialized where after
* we register a validator named "validateMyCustomCcComponent".
*/
window.addEventListener('checkout:init:evaluation', event => {
hyvaCheckout.evaluation.registerValidator('validateMyCustomCcComponent', (element, component) => {
return Math.random() < 0.5 // Randomly return true of false.
})
})
// Before 1.1.13
window.addEventListener('checkout:init:validation', event => {
hyvaCheckout.validation.register('validateMyCustomCcValidation', () => {
const result = Math.random() < 0.5 // Randomly return true of false.
if (result) {
return true
}
// Dispatch a custom message to the payment method messenger block.
hyvaCheckout.messenger.dispatch(
'payment:method',
'Invalid credit card details provided. Please try again.'
)
return false
})
})
</script>
Marketing Opt-In Example
This example demonstrates using an Executable result with a Navigation Task to register customers for marketing communications after they successfully navigate to the next checkout step. The registration is optional, so it uses an Executable result combined with a Navigation Task result rather than a Validation result.
The Navigation Task executes the registration logic after the customer successfully proceeds, avoiding blocking navigation for optional functionality.
Create the Magewire Component
This Magewire component tracks whether the customer agreed to receive marketing communications and implements the EvaluationInterface to create the Navigation Task.
Note the use of the withParam() function. This can be used to forward data to the frontend upon execution.
<?php
declare(strict_types=1);
namespace Vendor\Module\Magewire;
use Magewirephp\Magewire\Component;
use Hyva\Checkout\Model\Magewire\Component\EvaluationInterface;
use Hyva\Checkout\Model\Magewire\Component\EvaluationResultFactory;
use Hyva\Checkout\Model\Magewire\Component\EvaluationResultInterface;
class MarketingCheckbox extends Component implements EvaluationInterface
{
public bool $shouldRegister = false;
public function evaluateCompletion(EvaluationResultFactory $resultFactory): EvaluationResultInterface
{
$executable = $resultFactory
->createExecutable('marketingRegistrationExecutable')
->withParam('shouldRegister', $this->shouldRegister);
return $resultFactory
->createNavigationTask('marketingRegistrationTask', $executable)
->executeAfter();
}
}
Create the Checkbox Block
Use the hyva_checkout_components.xml layout handle to add the marketing checkbox component to the checkout. This example appends it to the summary block.
<?xml version="1.0"?>
<page
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"
>
<body>
<referenceContainer name="hyva.checkout.api-v1.after">
<referenceContainer name="checkout.quote-summary.section">
<block
name="marketing.checkbox.component"
template="Vendor_Module::checkbox.phtml"
after="-"
>
<arguments>
<argument name="magewire" xsi:type="object">
Vendor\Module\Magewire\MarketingCheckbox
</argument>
</arguments>
</block>
</referenceContainer>
</referenceContainer>
</body>
</page>
Create the Checkbox Template
This template renders the marketing opt-in checkbox with two-way data binding to the Magewire component's shouldRegister property.
<?php
declare(strict_types=1);
use Magento\Framework\Escaper;
use Magento\Framework\View\Element\Template;
use Vendor\Module\Magewire\MarketingCheckbox;
/** @var Escaper $escaper */
/** @var Template $block */
/** @var MarketingCheckbox $magewire */
?>
<label>
<input
type="checkbox"
name="checkbox_component"
wire:model="shouldRegister"
>
<span><?= $escaper->escapeHtml(__(
'Would you like to receive marketing emails from us? %1',
$magewire->shouldRegister ? 'Yes' : 'No'
)); ?></span>
</label>
Create the Navigation Task Block
Use the hyva_checkout_index_index.xml layout handle to inject the block containing the navigation task callback into the checkout.
<?xml version="1.0"?>
<page
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"
>
<body>
<referenceContainer name="hyva.checkout.api-v1.after">
<block
name="marketing.checkbox.navigation.task"
template="Vendor_Module::js/checkbox.phtml"
/>
</referenceContainer>
</body>
</page>
Create the Navigation Task Template
Register the executable callback using hyvaCheckout.evaluation.registerExecutable() in an checkout:init:evaluation event listener. The callback name must match the name given in the Magewire component's evaluateCompletion() method.
The callback has access to a result parameter where we can find the data forwarded by our Magewire component.
<?php
declare(strict_types=1);
use Magento\Framework\Escaper;
use Magento\Framework\View\Element\Template;
/** @var Escaper $escaper */
/** @var Template $block */
?>
<script>
window.addEventListener('checkout:init:evaluation', event => {
hyvaCheckout.evaluation.registerExecutable(
'marketingRegistrationExecutable',
(result, element, component) => {
if (result.arguments.params.shouldRegister) {
// marketing registration logic
}
}
);
});
</script>
Notes
The Navigation Task callback will NOT execute after the initialization of the checkout, but WILL execute every time the customer navigates to or from the step that contains the MarketingCheckbox component.
For a production marketing integration, you would likely want a mechanism to flag when the API call has been successful, avoiding duplicate requests.