Download the PHP package morebec/domain-normalizer without Composer

DomainNormalizer

DomainNormalizer is an Orkestra Component used to easily normalize domain objects, through a fluent interface. It has the benefit of moving serialization/persistence concerns out of the domain classes, while providing a quick and easy way of defining primitive mapping information for domain classes.

It contains features for both serialization and deserialization (through normalization).

Normalization

Normalization is the process of transforming a Domain Object instance to an array representation of primitive (int,string,float.bool, array) values. This array representation is called a normalized form.

Given a class structure like:

Using the following definition:

Would return the following normalized form:

It is also possible to contain your definitions inside classes:

The rules are simple:

• If the normalizer cannot find a definition for a given object:
  • It will look in its registry to find out if there is a definition for one of the object's parent class that it can use.
  • Otherwise: It will throw an exception
• Definitions follow an explicit declaration approach:
  • If a property exists on the instance but is not part the definition, it will not be normalized. It will be ignored.
  • If a property exists does not exists on the instance but is part of the definition:
    • Unless it is a "bound" property, the normalizer will throw an exception.
    • In the case of Bound properties, they will be added to the resulting normalized form. (This can be defined either though the bound definition when using definition factory or through the createProperty)

Denormalization

The process of denormalization is the opposite of normalization: Transforming a normalized form to a Domain Object Instance.

In denormalization definitions, instead of defining properties, we define keys.

The rules are similar to normalization but presets some subtle differences:

• Definitions also follow an explicit declaration approach:
  • If key exists on the normalized form but it not part of the definition, it will not be denormalized.
  • Every nested normalized forms must have an associated definition.
    • If none is found, the denormalizer will throw an exception.
  • If a key definition exists but the associated data does not:
    • It will apply the configured missing transformer which is usually to either throw an error, or provide a default value.
      • By default it is to throw an error
  • If a key definition exists, but no corresponding property exists on the class:
    • Throw an exception.

Automatic De/Normalization

Although we recommend using explicit definitions, it is also possible to use automatic normalization and denormalization.
This can be useful when dealing with simple DTOs to normalize/denormalize: