<?php
/**
 * Submission entity.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Models;

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

/**
 * Immutable representation of a single row of the submissions table.
 *
 * @since 1.0.0
 */
final class Submission {

	/**
	 * Status of a submission nobody opened yet.
	 */
	public const STATUS_UNREAD = 'unread';

	/**
	 * Status of a submission that has been opened.
	 */
	public const STATUS_READ = 'read';

	/**
	 * Constructor.
	 *
	 * @param int    $id         Row ID.
	 * @param int    $form_id    Form the submission belongs to.
	 * @param int    $user_id    User who submitted, 0 for guests.
	 * @param string $status     One of the status constants.
	 * @param string $entry_key  Public token.
	 * @param string $ip_address Stored client address.
	 * @param string $user_agent Stored client user agent.
	 * @param string $referer    Page the form was submitted from.
	 * @param int    $post_id    Post holding the form.
	 * @param string $created_at Creation date in MySQL format.
	 * @param string $updated_at Last modification date in MySQL format.
	 */
	public function __construct(
		private int $id = 0,
		private int $form_id = 0,
		private int $user_id = 0,
		private string $status = self::STATUS_UNREAD,
		private string $entry_key = '',
		private string $ip_address = '',
		private string $user_agent = '',
		private string $referer = '',
		private int $post_id = 0,
		private string $created_at = '',
		private string $updated_at = ''
	) {}

	/**
	 * Builds an entity from a database row.
	 *
	 * @param object|array<string, mixed> $row Row returned by wpdb.
	 */
	public static function from_row( object|array $row ): Submission {
		$row = (array) $row;

		return new self(
			id: (int) ( $row['id'] ?? 0 ),
			form_id: (int) ( $row['form_id'] ?? 0 ),
			user_id: (int) ( $row['user_id'] ?? 0 ),
			status: (string) ( $row['status'] ?? self::STATUS_UNREAD ),
			entry_key: (string) ( $row['entry_key'] ?? '' ),
			ip_address: (string) ( $row['ip_address'] ?? '' ),
			user_agent: (string) ( $row['user_agent'] ?? '' ),
			referer: (string) ( $row['referer'] ?? '' ),
			post_id: (int) ( $row['post_id'] ?? 0 ),
			created_at: (string) ( $row['created_at'] ?? '' ),
			updated_at: (string) ( $row['updated_at'] ?? '' )
		);
	}

	/**
	 * Returns the available statuses and their labels.
	 *
	 * @return array<string, string> Translated labels keyed by status.
	 */
	public static function statuses(): array {
		return array(
			self::STATUS_UNREAD => __( 'Unread', 'devplugins-custom-form-builder' ),
			self::STATUS_READ   => __( 'Read', 'devplugins-custom-form-builder' ),
		);
	}

	/**
	 * Returns the row ID.
	 */
	public function id(): int {
		return $this->id;
	}

	/**
	 * Returns the owning form ID.
	 */
	public function form_id(): int {
		return $this->form_id;
	}

	/**
	 * Returns the submitting user.
	 *
	 * @return int The user ID, or 0 for guests.
	 */
	public function user_id(): int {
		return $this->user_id;
	}

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

	/**
	 * Returns the translated status label.
	 *
	 * @return string The label, falling back to the raw status.
	 */
	public function status_label(): string {
		return self::statuses()[ $this->status ] ?? $this->status;
	}

	/**
	 * Determines whether the submission has been opened.
	 *
	 * @return bool True when the status is read.
	 */
	public function is_read(): bool {
		return self::STATUS_READ === $this->status;
	}

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

	/**
	 * Returns the stored client address.
	 */
	public function ip_address(): string {
		return $this->ip_address;
	}

	/**
	 * Returns the stored user agent.
	 */
	public function user_agent(): string {
		return $this->user_agent;
	}

	/**
	 * Returns the page the form was submitted from.
	 */
	public function referer(): string {
		return $this->referer;
	}

	/**
	 * Returns the post holding the form.
	 */
	public function post_id(): int {
		return $this->post_id;
	}

	/**
	 * Returns the creation date.
	 */
	public function created_at(): string {
		return $this->created_at;
	}

	/**
	 * Returns the last modification date.
	 */
	public function updated_at(): string {
		return $this->updated_at;
	}

	/**
	 * Returns the entity as an array.
	 *
	 * @return array<string, mixed> The entity data.
	 */
	public function to_array(): array {
		return array(
			'id'         => $this->id,
			'form_id'    => $this->form_id,
			'user_id'    => $this->user_id,
			'status'     => $this->status,
			'entry_key'  => $this->entry_key,
			'ip_address' => $this->ip_address,
			'user_agent' => $this->user_agent,
			'referer'    => $this->referer,
			'post_id'    => $this->post_id,
			'created_at' => $this->created_at,
			'updated_at' => $this->updated_at,
		);
	}
}