<?php
/**
 * Environment check error value object.
 *
 * Describes a single failure detected by {@see EnvironmentChecker}.
 * An error identifies which axis failed (PHP / WordPress / WooCommerce),
 * what minimum was required, what was actually detected (when
 * detectable), and a human-readable message suitable for display in an
 * admin notice or log entry.
 *
 * Instances are immutable. Aggregated into {@see EnvironmentCheckResult}.
 *
 * @package CommerceLinkBuilder\Bootstrap
 */

declare(strict_types=1);

namespace CommerceLinkBuilder\Bootstrap;

/**
 * Immutable description of one environment check failure.
 */
final class EnvironmentCheckError {

	/**
	 * Axis identifier.
	 *
	 * One of the well-known values "php", "WordPress", "woocommerce".
	 * Kept as a plain string rather than an enum so that future axes
	 * (e.g. "mysql", "curl") can be introduced without a BC break.
	 *
	 * Note: the "woocommerce" axis is emitted only as an **optional
	 * coexistence check**. Commerce Link Builder is an affiliate-link
	 * plugin and does not depend on WooCommerce; a "woocommerce" error
	 * here means WooCommerce is present but too old for safe coexistence,
	 * never that WooCommerce is missing.
	 */
	private string $axis;

	/**
	 * Minimum version required on this axis.
	 */
	private string $required;

	/**
	 * Detected version on this axis, or null when it could not be
	 * determined (for example when WordPress is not yet loaded).
	 */
	private ?string $detected;

	/**
	 * Human-readable, English-language description of the failure.
	 *
	 * Intended to be passed through a translation function at the
	 * presentation layer when rendered to the operator. Stored in
	 * English here so the value object stays independent of the
	 * WordPress i18n pipeline.
	 */
	private string $message;

	/**
	 * @param string      $axis     Axis identifier ("php" / "WordPress" / "woocommerce").
	 * @param string      $required Minimum version required on this axis.
	 * @param string|null $detected Detected version, or null when unknown.
	 * @param string      $message  Human-readable failure description.
	 */
	public function __construct(
		string $axis,
		string $required,
		?string $detected,
		string $message
	) {
		$this->axis     = $axis;
		$this->required = $required;
		$this->detected = $detected;
		$this->message  = $message;
	}

	/**
	 * Axis identifier for this failure.
	 */
	public function axis(): string {
		return $this->axis;
	}

	/**
	 * Minimum version required on this axis.
	 */
	public function required(): string {
		return $this->required;
	}

	/**
	 * Detected version on this axis, or null when it could not be
	 * determined at check time.
	 */
	public function detected(): ?string {
		return $this->detected;
	}

	/**
	 * Human-readable, English description of the failure.
	 */
	public function message(): string {
		return $this->message;
	}

	/**
	 * Array representation suitable for logging or serialization.
	 *
	 * @return array{axis: string, required: string, detected: ?string, message: string}
	 */
	public function toArray(): array {
		return array(
			'axis'     => $this->axis,
			'required' => $this->required,
			'detected' => $this->detected,
			'message'  => $this->message,
		);
	}
}
