-
Notifications
You must be signed in to change notification settings - Fork 3
Normalize annotations
Note: Legacy docblock annotations are still supported. But since version 6 you should use PHP attributes.
The following annotation/attribute options are supported:
- maxDepth; Will set a maximum depth for nested objects/classes
- skipEmpty; If a value is null, don't normalize it (omit)
- group; Indicate a context
- name; A custom name for the value, instead of using the property/method name
- type; Indicate the value type of the property/method
- format; Indicate a format for the type="DateTime" option
- callback; Indicate a method that should be called for the type="object" option, or a method on the current class for a property
- normalizeCallbackResult; Put the content of a callback trough the normalizer again
Both docblock annotations and PHP 8 attributes are supported and can be mixed within the same codebase.
To normalize until a certain depth (type="object" / type="collection"). Property can only be set on class level.
/**
* @Bos\Normalize(maxDepth=2)
*/
#[Bos\Normalize(maxDepth: 2)]
class ClassToBeNormalized
{
You can omit properties that are empty to be normalized. If the property contains no data (empty, or null) the normalized output will not contain this property.
/**
* @Bos\Normalize(skipEmpty=true)
*/
#[Bos\Normalize(skipEmpty: true)]
private $propertyToBeNormalized;
This can also be used on class level. All properties which are empty, will now not be normalized.
/**
* @Bos\Normalize(skipEmpty=true)
*/
#[Bos\Normalize(skipEmpty: true)]
class ClassToBeNormalized
{
Use property 'group' to separate context.
/**
* @Bos\Normalize(group={"default"})
* @Bos\Normalize(group={"customgroup", "customgroup2"}, name="something")
*/
#[Bos\Normalize(group: ['default'])]
#[Bos\Normalize(group: ['customgroup', 'customgroup2'], name: 'something')]
private $propertyToBeNormalized;
Use property 'name' to change the key (name) of the class property to be normalized.
/**
* @Bos\Normalize(name="automobile")
*/
#[Bos\Normalize(name: 'automobile')]
private $propertyToBeNormalized;
Indicate if the class property is of a 'special' type. Type can be 'collection', 'object', or 'datetime'. If an object is empty, value 'null' will be returned.
/**
* @Bos\Normalize(type="DateTime")
* @Bos\Normalize(type="object")
* @Bos\Normalize(type="collection", callback="toListArray")
*/
#[Bos\Normalize(type: 'DateTime')]
#[Bos\Normalize(type: 'object')]
#[Bos\Normalize(type: 'collection', callback: 'toListArray')]
private $propertyToBeNormalized;
If you have a property which contains a collection of other entities, you can use the type 'collection'. If you specify a callback, it will be applied to each item of the collection and placed in the result array.
Format the 'DateTime' type. Can only be used for type="DateTime".
/**
* @Bos\Normalize(type="DateTime", format="Y-m-d")
*/
#[Bos\Normalize(type: 'DateTime', format: 'Y-m-d')]
private $propertyToBeNormalized;
Sometimes you encounter an object for which you still want to use a legacy method, or just a custom method to normalize data for a property to normalize. If used together with type="object", the callback is the method that is bound to the class property the annotation is set on. If used without type="", the callback relates to a method within the current class.
/**
* @Bos\Normalize(type="object", callback="toListArray")
* @Bos\Normalize(callback="getPropertyToBeNormalized")
*/
#[Bos\Normalize(type: 'object', callback: 'toListArray')]
#[Bos\Normalize(callback: 'getPropertyToBeNormalized')]
private $propertyToBeNormalized;
Note: callbacks can't be used on methods, since a method can surely function as callback.
It is possible to normalize output from a callback method. E.g. if you return an array with objects or just a single object from a callback method it will also normalize those objects.
/**
* @Bos\Normalize(callback="legacyMethod", normalizeCallbackResult=true)
* @Bos\Normalize(type="object", callback="legacyMethod", normalizeCallbackResult=true)
* @Bos\Normalize(type="collection", callback="legacyMethod", normalizeCallbackResult=true)
*/
#[Bos\Normalize(callback: 'legacyMethod', normalizeCallbackResult: true)]
#[Bos\Normalize(type: 'object', callback: 'legacyMethod', normalizeCallbackResult: true)]
#[Bos\Normalize(type: 'collection', callback: 'legacyMethod', normalizeCallbackResult: true)]
private $propertyToBeNormalized;
Note: callbacks can't be used on methods.