<?php
declare(strict_types=1);

namespace App\Media;

use App\Shared\Util\DateParser;
use DateTime;

/**
 * Modèle représentant un fichier média uploadé.
 *
 * Encapsule les métadonnées d'un fichier stocké dans public/media/.
 * Le fichier physique est identifié par son nom de stockage opaque (filename),
 * distinct du nom affiché à l'utilisateur.
 *
 * Le hash SHA-256 du contenu permet la détection des doublons à l'upload :
 * si un fichier identique a déjà été uploadé, son URL est retournée
 * directement sans créer un second fichier sur disque.
 */
final class Media
{
    /**
     * @var DateTime Date d'upload — toujours non nulle après construction
     *               (le constructeur accepte ?DateTime mais affecte `new DateTime()` si null)
     */
    private readonly DateTime $createdAt;

    /**
     * @param int           $id        Identifiant en base (0 pour un nouveau média)
     * @param string        $filename  Nom de stockage opaque sur disque (ex: "a3f8c1d2_9f33.jpg")
     * @param string        $url       URL publique d'accès au fichier (ex: "/media/a3f8c1d2_9f33.jpg")
     * @param string        $hash      Hash SHA-256 du contenu binaire du fichier
     * @param int|null      $userId    Identifiant de l'auteur (null si le compte a été supprimé)
     * @param DateTime|null $createdAt Date d'upload (défaut : maintenant)
     */
    public function __construct(
        private readonly int $id,
        private readonly string $filename,
        private readonly string $url,
        private readonly string $hash,
        private readonly ?int $userId,
        ?DateTime $createdAt = null,
    ) {
        $this->createdAt = $createdAt ?? new DateTime();
    }

    /**
     * Crée une instance depuis un tableau associatif (ligne de base de données).
     *
     * @param array<string, mixed> $data Données issues de la base de données
     *
     * @return self L'instance hydratée
     */
    public static function fromArray(array $data): self
    {
        return new self(
            id:        (int) ($data['id'] ?? 0),
            filename:  (string) ($data['filename'] ?? ''),
            url:       (string) ($data['url'] ?? ''),
            hash:      (string) ($data['hash'] ?? ''),
            userId:    isset($data['user_id']) ? (int) $data['user_id'] : null,
            createdAt: DateParser::parse($data['created_at'] ?? null),
        );
    }

    /**
     * Retourne l'identifiant du média.
     *
     * @return int L'identifiant en base (0 si non encore persisté)
     */
    public function getId(): int
    {
        return $this->id;
    }

    /**
     * Retourne le nom de stockage du fichier sur disque.
     *
     * Ce nom est opaque et généré aléatoirement à l'upload.
     * Il ne doit pas être affiché à l'utilisateur tel quel.
     *
     * @return string Le nom de fichier sur disque
     */
    public function getFilename(): string
    {
        return $this->filename;
    }

    /**
     * Retourne l'URL publique d'accès au fichier.
     *
     * @return string L'URL publique (ex: "/media/a3f8c1d2_9f33.jpg")
     */
    public function getUrl(): string
    {
        return $this->url;
    }

    /**
     * Retourne le hash SHA-256 du contenu binaire du fichier.
     *
     * Utilisé pour la détection des doublons à l'upload.
     *
     * @return string Le hash hexadécimal SHA-256
     */
    public function getHash(): string
    {
        return $this->hash;
    }

    /**
     * Retourne l'identifiant de l'auteur du média.
     *
     * @return int|null L'identifiant de l'auteur, ou null si le compte a été supprimé
     */
    public function getUserId(): ?int
    {
        return $this->userId;
    }

    /**
     * Retourne la date d'upload du fichier.
     *
     * @return DateTime La date d'upload
     */
    public function getCreatedAt(): DateTime
    {
        return $this->createdAt;
    }
}