<?php
/**
 * Validation error.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Validation;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * One reason a value was refused.
 *
 * Carries a machine readable code alongside the sentence shown to the visitor,
 * so an integration can react to `too_short` without parsing English, and the
 * data behind the message travels with it for clients that render their own.
 *
 * @since 1.0.0
 */
final class ValidationError {

	/**
	 * Constructor.
	 *
	 * @param string               $field   Key of the field that failed.
	 * @param string               $code    Machine readable reason, for example 'invalid_email'.
	 * @param string               $message Sentence shown to the visitor.
	 * @param array<string, mixed> $data    Values behind the message, such as the limit that was exceeded.
	 */
	public function __construct(
		private string $field = '',
		private string $code = '',
		private string $message = '',
		private array $data = array()
	) {}

	/**
	 * Returns the field key.
	 */
	public function field(): string {
		return $this->field;
	}

	/**
	 * Returns the machine readable reason.
	 */
	public function code(): string {
		return $this->code;
	}

	/**
	 * Returns the sentence shown to the visitor.
	 */
	public function message(): string {
		return $this->message;
	}

	/**
	 * Returns the values behind the message.
	 *
	 * @return array<string, mixed> The data.
	 */
	public function data(): array {
		return $this->data;
	}

	/**
	 * Returns a copy bound to a field.
	 *
	 * Rules build errors without knowing the key they will be filed under; the
	 * engine stamps it on the way out.
	 *
	 * @param string $field Field key.
	 */
	public function for_field( string $field ): ValidationError {
		return new self( $field, $this->code, $this->message, $this->data );
	}

	/**
	 * Returns the error as an array.
	 *
	 * @return array<string, mixed> The payload.
	 */
	public function to_array(): array {
		return array(
			'field'   => $this->field,
			'code'    => $this->code,
			'message' => $this->message,
			'data'    => $this->data,
		);
	}
}