<?php
/**
 * Stored upload.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Uploads;

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

/**
 * A file that has been accepted and moved into place.
 *
 * The object is stored as JSON in the submission meta, so it round trips
 * through {@see UploadedFile::to_array()} and {@see UploadedFile::from_array()}.
 *
 * @since 1.0.0
 */
final class UploadedFile {

	/**
	 * Constructor.
	 *
	 * @param string $name          Original file name.
	 * @param string $file          Absolute path on disk.
	 * @param string $url           Public URL.
	 * @param string $type          Mime type.
	 * @param int    $size          Size in bytes.
	 * @param int    $attachment_id Media library ID, 0 when not attached.
	 */
	public function __construct(
		private string $name = '',
		private string $file = '',
		private string $url = '',
		private string $type = '',
		private int $size = 0,
		private int $attachment_id = 0
	) {}

	/**
	 * Rebuilds an upload from a stored value.
	 *
	 * @param array<string, mixed> $data Stored payload.
	 */
	public static function from_array( array $data ): UploadedFile {
		return new self(
			name: (string) ( $data['name'] ?? '' ),
			file: (string) ( $data['file'] ?? '' ),
			url: (string) ( $data['url'] ?? '' ),
			type: (string) ( $data['type'] ?? '' ),
			size: (int) ( $data['size'] ?? 0 ),
			attachment_id: (int) ( $data['attachment_id'] ?? 0 )
		);
	}

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

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

	/**
	 * Returns the path only when it resolves inside the plugin upload directory.
	 *
	 * The payload behind this object is a JSON blob out of a database row, so
	 * `path()` is a value the plugin stored, not a value it can vouch for. Any
	 * caller about to hand the path to the filesystem — attaching it to mail,
	 * unlinking it, streaming it — should ask through here instead, and treat the
	 * empty string as "there is nothing safe to act on".
	 *
	 * A regular file only, and never one of the directory's guard files.
	 *
	 * @return string The resolved path, or an empty string.
	 */
	public function managed_path(): string {
		return UploadManager::stored_file( $this->file );
	}

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

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

	/**
	 * Returns the size in bytes.
	 */
	public function size(): int {
		return $this->size;
	}

	/**
	 * Returns the media library ID.
	 *
	 * @return int The attachment ID, or 0 when the file is not attached.
	 */
	public function attachment_id(): int {
		return $this->attachment_id;
	}

	/**
	 * Determines whether the file lives in the media library.
	 *
	 * @return bool True when an attachment was created.
	 */
	public function is_attachment(): bool {
		return $this->attachment_id > 0;
	}

	/**
	 * Returns the upload as a storable array.
	 *
	 * @return array<string, mixed> The payload.
	 */
	public function to_array(): array {
		return array(
			'name'          => $this->name,
			'file'          => $this->file,
			'url'           => $this->url,
			'type'          => $this->type,
			'size'          => $this->size,
			'attachment_id' => $this->attachment_id,
		);
	}
}