Un prix n'est pas un float

On stocke un prix dans un float, un e-mail dans un string, un pays dans deux lettres. Ça marche — jusqu'au jour où l'on additionne des euros avec des dollars sans que rien ne proteste.

Imagine une méthode qui calcule le total d'une commande. Elle reçoit des montants, elle les additionne, elle retourne un nombre. Un jour, une ligne en dollars se glisse parmi des lignes en euros. Le code additionne quand même — 10.0 + 12.5 fait 22.5, peu importe la devise. Aucune erreur, aucune alerte. Juste un total silencieusement faux, qui partira en facture.

Le problème n'est pas le calcul. C'est qu'on a représenté un concept riche — une somme d'argent — par un type pauvre : un simple nombre. Le nombre ne sait pas qu'il est en euros. Il ne sait pas qu'on ne mélange pas les devises. Toute cette connaissance métier vit ailleurs, éparpillée dans des if, ou nulle part.

Peter Hilton, dans une conférence consacrée à la modélisation des valeurs, résume l'enjeu d'une formule qu'on va garder en tête tout le cours :

Le remède porte un nom dans le Domain-Driven Design : le value object. Au lieu d'un float nu, une petite classe Money qui tient ensemble le montant et la devise, qui refuse d'être construite invalide, et qui sait qu'additionner des euros et des dollars n'a pas de sens. Le concept devient explicite, et les règles vivent avec lui.

Ce cours est la fondation tactique du DDD. On y verra deux natures d'objets — les entités et les value objects — puis tout ce qui fait la force des seconds : l'égalité par valeur, l'immutabilité, la validation à la construction, le « whole value ». On finira par les brancher sur Doctrine : embeddeds, types custom, enums. C'est la brique qui sert ensuite à bâtir les agrégats.

Entité ou value object : une question d'identité

Deux billets de dix euros sont interchangeables : personne ne te rendra « ton » billet précis. Deux personnes qui portent le même nom, elles, restent deux personnes distinctes. Toute la distinction est là.

Prends deux billets de dix euros dans ton portefeuille. Peux-tu les distinguer ? Non — et surtout, ça n'a aucune importance. Si tu en prêtes un et qu'on te rend « l'autre », tu n'as rien perdu. Ils sont définis entièrement par ce qu'ils valent : dix euros. C'est un value object.

Maintenant, deux clients de ton application qui s'appellent tous deux « Jean Martin ». Sont-ils interchangeables ? Absolument pas. Chacun a son historique, ses commandes, sa continuité dans le temps. Même s'ils partageaient tous leurs attributs — même nom, même adresse, même date de naissance — ils resteraient deux personnes différentes. C'est une entité.

Le test mental qui tranche presque toujours : « ai-je besoin de suivre cet objet dans le temps, de le distinguer d'un autre qui lui ressemble ? ». Si oui, c'est une entité, il lui faut une identité. Si non — si seule sa valeur compte — c'est un value object.

Notre fil rouge pour tout le cours : une entité Customer, qui porte plusieurs value objects — EmailAddress, PersonName, PostalAddress, Money pour son solde de fidélité. Le Customer a une identité stable ; ses valeurs, elles, se remplacent au fil du temps sans jamais le transformer en quelqu'un d'autre.

Une heuristique de Vaughn Vernon, qui a écrit la référence sur l'implémentation du DDD, vaut d'être gardée en boussole : « strive to use value objects ». En cas de doute, penche pour le value object. On verra en fin de cours pourquoi les value objects rendent le code tellement plus sûr et plus simple à tester — et cette section-ci va commencer par leur propriété la plus fondamentale : l'égalité.

L'égalité par valeur : même valeur, même objet

Deux value objects se comparent sur ce qu'ils contiennent, pas sur l'endroit où ils vivent en mémoire. En PHP, cette distinction se joue sur un caractère : `==` ou `===`.

Reprenons les deux billets de dix euros. Ils sont « égaux » parce qu'ils valent la même chose. C'est ça, l'égalité par valeur : deux value objects sont égaux si — et seulement si — tous leurs attributs sont égaux. Peu importe qu'il s'agisse de deux instances différentes en mémoire.

Une entité, elle, se compare sur son identité. Deux Customer sont le même si — et seulement si — ils ont le même identifiant, même si tous leurs autres attributs diffèrent. C'est l'exact opposé du value object.

En PHP, il y a un piège de langage à connaître par cœur, parce qu'il produit des bugs silencieux. Sur deux objets, l'opérateur == compare les propriétés une à une, tandis que === vérifie que c'est strictement la même instance en mémoire.

$a = new Money(10, 'EUR');
$b = new Money(10, 'EUR');

$a == $b   // true  — mêmes propriétés
$a === $b  // false — deux instances différentes

Se reposer sur == est fragile : il ne connaît pas les règles de ton domaine (faut-il ignorer la casse d'un e-mail ? normaliser une devise ?). La bonne pratique est d'exposer une méthode equals() explicite, qui dit exactement ce que « égal » veut dire pour ce concept.

final readonly class EmailAddress
{
    public function __construct(public string $value) { /* … validation … */ }

    public function equals(self $other): bool
    {
        // un e-mail est insensible à la casse : on compare en minuscules
        return strtolower($this->value) === strtolower($other->value);
    }
}

Le simulateur ci-dessous rend cette bascule tangible. Deux montants aux attributs strictement identiques : selon que tu les traites comme des value objects ou comme des entités, la réponse à « sont-ils égaux ? » s'inverse. Manipule, la conclusion n'est pas devinable à la lecture.

Immutabilité : remplacer plutôt que muter

Un value object ne change jamais après sa naissance. Pour « le modifier », on en fabrique un nouveau. Cette règle, qui paraît rigide, élimine toute une famille de bugs sournois.

Puisqu'un value object n'est que sa valeur, le modifier n'aurait aucun sens : changer le montant d'un Money(10, 'EUR') pour en faire 15, ce n'est plus « le même billet modifié », c'est un autre billet. Le principe en découle naturellement.

PHP 8 rend ce contrat vérifiable par le moteur lui-même. Une propriété readonly ne peut être écrite qu'une fois, dans le constructeur ; toute tentative ultérieure lève une erreur. Une classe final readonly gèle l'ensemble.

final readonly class Money
{
    public function __construct(
        public int    $amount,    // en centimes, pour éviter les flottants
        public string $currency,
    ) {}

    // Ne mute pas : retourne un NOUVEAU Money. C'est un « wither ».
    public function add(Money $other): self
    {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatchException($this->currency, $other->currency);
        }
        return new self($this->amount + $other->amount, $this->currency);
    }
}

Remarque la méthode add() : elle ne modifie pas $this, elle renvoie un tout nouveau Money. C'est ce qu'Eric Evans appelle une side-effect-free function — une opération qui calcule un résultat sans jamais altérer d'état. On les compose sans crainte, on les teste sans mock ni base de données.

Pour changer une valeur portée par une entité, on remplace donc le value object entier, via une méthode métier explicite :

// Dans l'entité Customer — on remplace, on ne mute pas.
public function changeEmail(EmailAddress $email): void
{
    $this->email = $email;   // nouveau VO, entièrement validé, mis à la place de l'ancien
}

Pourquoi tant de rigueur ? Parce que muter une valeur partagée provoque un bug particulièrement vicieux : l'aliasing. Si deux endroits de ton code pointent vers le même objet mutable et que l'un le modifie, l'autre se retrouve modifié à son insu. Avec des objets immuables, ce bug est structurellement impossible : personne ne peut changer une valeur sous les pieds d'un autre.

Toujours valide : la validation au constructeur

Un value object n'existe jamais à moitié faux. Il valide ses invariants à la naissance, ou il refuse de naître. Mais attention : valider n'est pas rejeter à tort — et là, la plupart des validateurs se trompent.

Un value object bien conçu a une garantie précieuse : dès qu'il existe, il est valide. Il n'y a pas de Money à devise vide qui traîne, pas d'EmailAddress sans arobase. La validation se fait dans le constructeur, et si les invariants ne sont pas respectés, l'objet n'est pas construit — une exception est levée.

final readonly class EmailAddress
{
    public function __construct(public string $value)
    {
        if (!str_contains($value, '@')) {
            // exception du DOMAINE, pas une exception PHP générique
            throw new InvalidEmailException($value);
        }
    }
}

Jusqu'ici, tout va bien. Mais voici le piège où presque tout le monde tombe, et c'est la contribution la plus précieuse de Peter Hilton : valider, ce n'est pas rejeter tout ce qui sort de l'ordinaire. Un validateur trop zélé fait plus de dégâts qu'un champ libre.

Prends la validation des noms de personnes. La tentation est d'écrire ^[A-Za-z ]+$ — « des lettres et des espaces ». Ce validateur rejette García, O'Brien, van der Berg, Nguyễn, 李, Æ — c'est-à-dire une bonne partie de l'humanité. Les recommandations du W3C sur les noms, rappelle Hilton, se résument à une phrase : « allow everything ».

À l'inverse, valider un e-mail comporte en réalité quatre niveaux de certitude, et confondre le premier avec les autres mène à sur-valider :

Le simulateur confronte les deux philosophies sur des noms bien réels. Bascule entre le validateur « naïf » et le « permissif », et compte les gens que le premier refuse alors qu'ils existent pour de vrai.

Le whole value : un tout qu'on ne découpe pas

Un montant sans sa devise ne veut rien dire. Un intervalle de dates dont on peut mettre la fin avant le début est un piège ambulant. Certaines valeurs ne se tiennent que d'un seul bloc.

Retour à notre Money. Pourquoi tenir le montant et la devise ensemble, dans le même objet, plutôt que de balader deux variables séparées ? Parce qu'un montant seul n'a aucun sens : « 10 » n'est ni riche ni pauvre tant qu'on ne sait pas si ce sont des euros ou des yens. Le montant et la devise forment un tout cohérent — un whole value.

Le whole value a un pouvoir qu'on sous-estime : il peut faire respecter un invariant qui porte sur plusieurs attributs à la fois. Un DateRange peut garantir, dès sa construction, que la fin ne précède jamais le début. Impossible de créer un intervalle absurde ; le concept se protège lui-même.

final readonly class DateRange
{
    public function __construct(
        public \DateTimeImmutable $debut,
        public \DateTimeImmutable $fin,
    ) {
        if ($fin < $debut) {
            throw new InvalidDateRangeException($debut, $fin);  // invariant sur le TOUT
        }
    }
}

Mais il y a un versant inverse, et c'est là que Peter Hilton apporte une leçon contre-intuitive : certaines valeurs sont des touts qu'il ne faut surtout pas décomposer. Le meilleur exemple, c'est le nom d'une personne.

La tentation universelle est de casser un nom en « prénom » + « nom de famille ». Ça marche pour « Jean Martin », et ça s'effondre partout ailleurs. Dans quel champ mets-tu « van der Berg » ? Et les cultures où le nom de famille se dit en premier ? Et celles où il n'y a qu'un seul nom ? La structure d'un nom est spécifique à chaque pays, et aucun découpage universel n'existe.

Retiens la double leçon : un whole value regroupe ce qui n'a de sens qu'ensemble (montant + devise), et refuse de découper ce dont la structure interne est trop variable pour être universelle (un nom). Dans les deux cas, la bonne granularité vient du domaine, jamais d'un réflexe technique de « normalisation ».

Modéliser les valeurs du monde réel

Noms, adresses, pays, devises, e-mails, numéros de téléphone : ces valeurs existent dans le monde, hors de ton logiciel. La façon de les modéliser, elle, appartient à ton domaine — et regorge de pièges.

Certaines valeurs ne t'appartiennent pas : elles existent dans le monde, bien avant ton application. Un pays, une devise, une langue, un e-mail — Peter Hilton les appelle les valeurs universelles. Le paradoxe, c'est que même universelles, la façon de les modéliser dépend entièrement de ton domaine.

Première bonne nouvelle : pour beaucoup de ces valeurs, quelqu'un a déjà fait le travail. Des standards internationaux existent, et les réutiliser t'évite de réinventer — mal — une roue mondiale.

Ces valeurs à ensemble fini et connu ont une traduction naturelle en PHP : l'enum. C'est d'ailleurs, note Hilton, un motif récurrent — « a common theme with modeled values is that they are frequently enumerated types ». Un enum backed est le value object le plus simple qui soit : un ensemble fermé de valeurs, validées par le langage lui-même.

// Le value object le plus simple : un enum. Impossible d'inventer une devise inconnue.
enum Currency: string
{
    case EUR = 'EUR';
    case USD = 'USD';
    case JPY = 'JPY';
}

Vient ensuite un piège que tout le monde a déjà commis : croire que « ce qui s'appelle numéro est un nombre ».

Un numéro de téléphone commence parfois par un zéro (que le type int mangerait), contient un +, des espaces. Un numéro de maison peut être « 12 bis ». Un IBAN, un ISBN, un numéro de sécurité sociale : tous « numéros » de nom, tous du texte par nature. Les stocker comme des entiers, c'est perdre de l'information dès la première écriture.

Cela conduit à distinguer deux représentations d'une même valeur : la forme de stockage (canonique, sans fioritures) et la forme d'affichage (groupée, lisible). Un IBAN se stocke d'un bloc et s'affiche par groupes de quatre ; un téléphone se stocke en +33612345678 et s'affiche 06 12 34 56 78. Le value object peut porter les deux, et même valider un check digit — l'IBAN embarque une clé de contrôle qui détecte les fautes de frappe et les chiffres intervertis.

Deux derniers principes, brefs mais tranchants. D'abord, la règle d'or de Hilton contre le réflexe binaire :

Enfin, la minimisation des données, qui rejoint l'article 5 du RGPD : « you shouldn't ask for things you don't need, especially when it's personal data ». Avant de modéliser un attribut, demande-toi si tu en as vraiment besoin. La meilleure donnée personnelle à sécuriser est celle que tu n'as jamais collectée.

Mapper un value object composite : les embeddeds

Ton Money vit dans le code. Reste à le ranger en base sans lui inventer une table ni une identité qu'il n'a pas. Doctrine a un outil taillé pour ça : l'embeddable.

Un value object composite comme Money pose une question concrète de persistance : il n'a pas d'identité, donc pas de table à lui. Ses données doivent vivre dans la table de l'objet qui le porte. Doctrine appelle ça un embeddable : une classe dont les colonnes sont fondues dans la table du parent.

Deux attributs suffisent. #[ORM\Embeddable] marque la classe value object, et #[ORM\Embedded] l'insère dans une entité.

use Doctrine\ORM\Mapping as ORM;

#[ORM\Embeddable]
final readonly class Money
{
    public function __construct(
        #[ORM\Column(type: 'integer')]
        public int $amount,                // en centimes
        #[ORM\Column(type: 'string', length: 3)]
        public string $currency,
    ) {
        if ($amount < 0)  throw new NegativeMoneyException($amount);
    }
}

#[ORM\Entity]
class Order
{
    #[ORM\Embedded(class: Money::class, columnPrefix: 'total_')]
    private Money $total;   // → colonnes total_amount, total_currency
}

Le columnPrefix évite les collisions quand une entité porte plusieurs value objects du même type — une adresse de facturation et une de livraison, par exemple. La signature de l'attribut, vérifiée dans le code de Doctrine ORM 3, est #[Embedded(?string $class = null, string|bool|null $columnPrefix = null)] : passer false au préfixe colle les colonnes sans aucun préfixe.

L'embeddable règle le cas des value objects à plusieurs champs. Reste le cas plus fréquent encore : le value object à une seule valeur, souvent une identité typée. C'est l'objet de la section suivante.

Value object mono-valeur : types DBAL custom & enums

Comment ranger un EmailAddress dans une simple colonne texte, tout en le récupérant comme un vrai objet validé ? Doctrine te laisse écrire ta propre passerelle entre la base et le type PHP.

Un value object qui n'enveloppe qu'une valeur — un e-mail, un slug, un identifiant typé — n'a pas besoin de plusieurs colonnes. Il lui faut une traduction : objet PHP ↔ chaîne en base. Doctrine appelle ça un type DBAL custom, et c'est exactement le mécanisme qu'utilise ce projet pour ses identifiants.

Un type custom hérite d'un type Doctrine existant et implémente deux conversions : convertToPHPValue() (base → objet) et convertToDatabaseValue() (objet → base). Voici le patron réel du projet pour l'identité de cours :

// src/Infrastructure/Persistence/Doctrine/Type/CourseIdType.php  (extrait réel du projet)
final class CourseIdType extends GuidType
{
    public const NAME = 'course_id';

    public function convertToPHPValue(mixed $value, AbstractPlatform $platform): ?CourseId
    {
        return null === $value ? null : new CourseId($value);   // base → value object
    }

    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): ?string
    {
        return $value instanceof CourseId ? $value->getValue() : $value;   // VO → base
    }
}

Le type se déclare une fois dans la configuration, puis s'utilise sur n'importe quelle colonne :

# config/packages/doctrine.yaml
doctrine:
  dbal:
    types:
      course_id: App\Infrastructure\Persistence\Doctrine\Type\CourseIdType

// puis dans l'entité :
#[ORM\Column(type: CourseIdType::NAME, length: 36)]
private CourseId $id;

Pour les value objects à ensemble fini — ceux qu'on modélise en enum, comme vu en section 06 — Doctrine offre une voie encore plus directe : enumType. Pas de classe de type à écrire, on branche l'enum backed directement.

// enum backed comme value object, mappé sans type custom (usage réel du projet)
#[ORM\Column(enumType: AccentColor::class)]
private AccentColor $accent;

Le guide de décision : value object ou entité ?

Face à un concept nouveau, une seule question bien posée tranche presque toujours. Et par défaut, la réponse penche du même côté : value object.

Tu tiens maintenant les deux natures et tout ce qui les distingue. Reste à décider, dans le feu de la modélisation, à quel camp appartient un concept. La question qui tranche tient en une phrase :

Applique-la à quelques cas, et vois comme elle glisse toute seule :

Et quand le doute persiste ? La communauté DDD a une réponse claire, résumée par l'heuristique de Vaughn Vernon : « strive to use value objects ». Penche par défaut vers le value object, pour trois raisons très concrètes.

Le réflexe pratique le plus rentable, c'est de refactorer une primitive dès qu'elle porte des règles. Le jour où tu écris pour la troisième fois « un e-mail doit contenir un @ » ou « on ne mélange pas les devises », c'est le signal : ce string, ce float, veut devenir un value object. La règle a trouvé son foyer naturel.

Synthèse : rendre l'implicite explicite

Tout ce cours tient dans une idée : les concepts de ton métier méritent des types à eux, qui portent leurs règles. Un prix n'est pas un float — c'est un Money.

On est parti d'un total silencieusement faux, faute d'avoir donné à un montant un type qui connaisse sa devise. On termine avec une boîte à outils complète pour ne plus jamais laisser un concept métier se cacher derrière une primitive.

Les deux natures

Checklist d'un bon value object

• Immuable — final readonly class ; pour changer, on remplace.
• Égalité par valeur — un equals() explicite, jamais === pour l'égalité métier.
• Toujours valide — validation au constructeur, exception du domaine (pas \InvalidArgumentException).
• Whole value — regroupe ce qui n'a de sens qu'ensemble, ne décompose pas ce dont la structure est trop variable.
• Side-effect-free — les opérations retournent une nouvelle valeur, ne mutent rien.
• Bien modélisé — standards ISO/CLDR, enums pour les ensembles finis, « les numéros ne sont pas des nombres », jamais de booléen là où un enum s'impose.

Côté Doctrine

Pour aller plus loin