<?php
/**
 * Form 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 forms table.
 *
 * The entity carries no persistence logic; storage is the repository's job.
 *
 * @since 1.0.0
 */
final class Form {

	/**
	 * Draft status.
	 */
	public const STATUS_DRAFT = 'draft';

	/**
	 * Published status.
	 */
	public const STATUS_PUBLISHED = 'published';

	/**
	 * Constructor.
	 *
	 * @param int                  $id               Row ID, 0 for an unsaved form.
	 * @param string               $title            Form title.
	 * @param string               $slug             Unique slug.
	 * @param string               $status           One of the status constants.
	 * @param array<string, mixed> $settings         Decoded settings payload.
	 * @param int                  $author_id        User who created the form.
	 * @param int                  $submission_count Cached number of submissions.
	 * @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 string $title = '',
		private string $slug = '',
		private string $status = self::STATUS_DRAFT,
		private array $settings = array(),
		private int $author_id = 0,
		private int $submission_count = 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 ): Form {
		$row = (array) $row;

		$settings = isset( $row['settings'] ) && is_string( $row['settings'] )
			? json_decode( $row['settings'], true )
			: array();

		return new self(
			id: (int) ( $row['id'] ?? 0 ),
			title: (string) ( $row['title'] ?? '' ),
			slug: (string) ( $row['slug'] ?? '' ),
			status: (string) ( $row['status'] ?? self::STATUS_DRAFT ),
			settings: is_array( $settings ) ? $settings : array(),
			author_id: (int) ( $row['author_id'] ?? 0 ),
			submission_count: (int) ( $row['submission_count'] ?? 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_DRAFT     => __( 'Draft', 'devplugins-custom-form-builder' ),
			self::STATUS_PUBLISHED => __( 'Published', 'devplugins-custom-form-builder' ),
		);
	}

	/**
	 * Returns the row ID.
	 *
	 * @return int The form ID, or 0 when unsaved.
	 */
	public function id(): int {
		return $this->id;
	}

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

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

	/**
	 * 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;
	}

	/**
	 * Returns the decoded settings.
	 *
	 * @return array<string, mixed> The settings payload.
	 */
	public function settings(): array {
		return $this->settings;
	}

	/**
	 * Reads a single setting.
	 *
	 * @param string $key      Setting name.
	 * @param mixed  $fallback Optional. Value returned when the setting is absent. Default null.
	 *
	 * @return mixed The stored value, or the fallback.
	 */
	public function setting( string $key, mixed $fallback = null ): mixed {
		return array_key_exists( $key, $this->settings ) ? $this->settings[ $key ] : $fallback;
	}

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

	/**
	 * Returns the cached submission count.
	 */
	public function submission_count(): int {
		return $this->submission_count;
	}

	/**
	 * 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 shortcode embedding this form.
	 */
	public function shortcode(): string {
		return sprintf( '[formpilot id="%d"]', $this->id );
	}

	/**
	 * Determines whether the form is published.
	 *
	 * @return bool True when the status is published.
	 */
	public function is_published(): bool {
		return self::STATUS_PUBLISHED === $this->status;
	}

	/**
	 * Returns the entity as an array.
	 *
	 * @return array<string, mixed> The entity data.
	 */
	public function to_array(): array {
		return array(
			'id'               => $this->id,
			'title'            => $this->title,
			'slug'             => $this->slug,
			'status'           => $this->status,
			'settings'         => $this->settings,
			'author_id'        => $this->author_id,
			'submission_count' => $this->submission_count,
			'created_at'       => $this->created_at,
			'updated_at'       => $this->updated_at,
		);
	}
}