Frontend Evaluation API for Hyva Checkout

Since: 1.1.0

The hyvaCheckout.evaluation sub-namespace provides methods for registering frontend validators that integrate with the Hyva Checkout backend Evaluation API. Magewire components define validation rules on the server, while the hyvaCheckout.evaluation API executes JavaScript validation logic on the client - creating a unified validation system across the entire checkout flow.

How Frontend Evaluation Works in Hyva Checkout

The frontend evaluation system connects backend validation rules to client-side JavaScript execution. A Magewire component implements EvaluationInterface and returns a validation result type. The Hyva Checkout Frontend API then looks for a matching registered validator by name. The backend component defines what validation should occur and what happens on failure. The frontend validator defines how the validation executes using JavaScript.

For a complete overview of the Evaluation system including backend implementation, result types, and practical examples, see the dedicated backend Evaluation API documentation.

registerValidator

hyvaCheckout.evaluation.registerValidator registers a named JavaScript validator function that pairs with a backend Validation result type. When the backend component returns a validation result matching the registered name, the Frontend API executes the corresponding JavaScript callback.

Since: 1.3.5

Parameters:

• name (string) - A unique validator name that must match the name used in the backend createValidation() call.
• callback (function) - The validator callback function. Receives (component, element, evaluation) parameters and must return true (valid) or false (invalid).

Returns:

• Promise - Resolves when the validator is successfully registered.

Backend Magewire Component with EvaluationInterface

The following PHP code shows a Magewire component that defines a validation result type named my-unique-validator. When validation fails, the backend specifies the failure behavior (console log and warning dialog).

Backend: Magewire component with EvaluationInterface

Magewire Component Implementing EvaluationInterface

<?php

namespace Vendor\Module\Magewire;

use Magewirephp\Magewire\Component;
use Hyva\Checkout\Model\Magewire\Component\EvaluationInterface;
use Hyva\Checkout\Model\Form\EntityFormInterface;
use Hyva\Checkout\Model\Magewire\Component\Evaluation\EvaluationResultFactory;

class MyComponent extends Component implements EvaluationInterface
{
    /**
     * Define validation result that triggers frontend validator registration lookup.
     * The 'my-unique-validator' name must match the frontend registerValidator() name.
     */
    public function evaluateCompletion(EvaluationResultFactory $resultFactory): EntityFormInterface
    {
        return $resultFactory->createValidation('my-unique-validator')
            // Optional: Define what happens when the frontend validator returns false
            ->withFailureResult(
                $resultFactory->createConsoleLog('My unique validator failed... please try again.')
            )
            ->withFailureResult(
                $resultFactory->createMessageDialog('Validation Failure')
                    ->withMessage('My unique validator failed... please try again.')
                    ->asWarning()
            );
    }
}

Frontend JavaScript Validator Registration

The following JavaScript registers a frontend validator that pairs with the backend EvaluationInterface component above. The validator name my-unique-validator must exactly match the name passed to createValidation() in the Magewire PHP component.

Frontend: Registering the JavaScript validator callback

JavaScript Validator Registration

<script>
    (() => {
        // Wait for Frontend API initialization before registering
        hyvaCheckout.api.after(() => {
            // Register validator with name matching backend createValidation() call
            hyvaCheckout.evaluation.registerValidator(
                'my-unique-validator',
                async (component, element, evaluation) => {
                    // Implement custom validation logic here
                    // component: The Magewire component instance
                    // element: The DOM element associated with the component
                    // evaluation: The evaluation context object

                    // Return true for valid, false for invalid
                    // On false, the backend-defined withFailureResult() actions execute
                    return true;
                }
            ).then(() => console.log('my-unique-validator registered successfully.'));
        });
    })();
</script>