<?php

/*
 * This file is part of the Serenity package.
 *
 * (c) CP Creation <web@cpcreation.fr>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Serenity\CoreBundle\Shared\Common;

/**
 * Interface EmptyInterface.
 *
 * Contrat minimal pour les objets pouvant être considérés comme « vides »
 * lors de leur sérialisation, notamment dans le cadre de l’utilisation du
 * {@see \Serenity\CoreBundle\Shared\Normalizer\DoctrineJsonEmptyNormalizer}.
 *
 * Cette interface permet d’uniformiser le comportement des Value Objects/Entités/Models
 * stockés en JSON (ou JSONB) dans la base de données.
 *
 * Un objet implémentant cette interface doit pouvoir indiquer s’il est
 * « vide » — c’est-à-dire qu’il ne contient pas de valeur métier significative
 * et peut être remplacé par `null` lors de la sérialisation.
 *
 * ## Rôle dans la sérialisation :
 * - Le `DoctrineJsonEmptyNormalizer` utilise `isEmpty()` pour déterminer
 *   si un objet doit être sérialisé en `false` (valeur vide en JSON).
 * - Lors de la désérialisation, une valeur `false`, `null` ou vide
 *   sera reconvertie en `null` au lieu d’une instance d’objet vide.
 *
 * ## Exemple :
 * ```php
 * use Serenity\CoreBundle\Domain\Common\EmptyInterface;
 *
 * class Metadata implements EmptyInterface
 * {
 *     public function __construct(private ?string $value = null) {}
 *
 *     public function isEmpty(): bool
 *     {
 *         return $this->value === null || $this->value === '';
 *     }
 * }
 *
 * // Normalisation via DoctrineJsonEmptyNormalizer :
 * $normalizer->normalize(new Metadata(null)); // false
 *
 * // Dé-normalisation :
 * $normalizer->denormalize(false, Metadata::class); // null
 * ```
 *
 * ## Utilité :
 * - Permet d’éviter la création d’objets `{}` inutiles dans les colonnes JSON.
 * - Facilite la gestion des Value Objects optionnels.
 * - Garantit la cohérence des données entre Doctrine et le Serializer Symfony.
 */
interface EmptyInterface
{
    public function isEmpty(): bool;
}
