Download the PHP package aternos/serializer without Composer

aternos/serializer

A PHP library for (de-)serialization using attributes and reflection.

• Installation
• Usage
• The Serialize Attribute
  • Name
  • Required
  • Allow Null
  • Item Type
  • Serializer and Deserializer
  • Item Serializer and Item Deserializer
• Exceptions
  • SerializationException
  • InvalidInputException
  • MissingPropertyException
  • IncorrectTypeException
  • UnsupportedTypeException
  • InvalidEnumBackingException
• Custom Serializers

Installation

Usage

This library adds a simple trait which implements \JsonSerializable by serializing all properties with the #[Serialize] attribute. This attribute can be used to configure the serialization of the property.

See Exceptions for more information on error handling.

The trait also adds static fromJson and tryFromJson methods for deserialization.

[!NOTE] Deserialization is not supported for intersection types as there is no way to determine the correct type.

[!NOTE] Serialization and deserialization of enums is only supported for backed enums.

If you prefer you can also serialize and deserialize manually.

The Serialize Attribute

The Serialize attribute can be used to configure the serialization of a property. It has the following options:

Name

This option can be used to change the name of the property in the serialized data. If not specified, the property name is used.

This is useful if the serialized data uses a different naming convention (e.g. snake-case).

It also allows serializing properties with identifiers that are not allowed in PHP.

Required

This option can be used to specify whether the property is required in the serialized data. If this is not set, the property is not required if it has a default value.

Allow Null

This option can be used to specify whether the property can be null in the serialized data. If this is not set, and the property is annotated with a type the nullability of that type is used. If no type is provided, the property is allowed to be null.

Item Type

This option can be used to specify the type of the items in an array. It allows the deserializer to convert objects in the array to the correct type. If this is not set, items will not be converted to any type.

Array keys are preserved during the conversion.

Serializer and Deserializer

A custom Serializer and Deserializer can be specified for a property. This can be useful if you want to serialize a specific property in a different way.

Note that the custom Deserializer is responsible for returning the correct type. If an incompatible type is returned, an IncorrectTypeException is thrown.

Item Serializer and Item Deserializer

Custom Serializers and Deserializers can also be specified for array items.

Exceptions

The following exceptions may be thrown during serialization or deserialization:

• MissingPropertyException
• IncorrectTypeException

Both of these exceptions extend InvalidInputException.

During deserialization, the following additional exceptions may be thrown:

• UnsupportedTypeException
• InvalidEnumBackingException
• JsonException

JsonException is a built-in PHP exception that is thrown when an error occurs during JSON encoding or decoding. All other exceptions extend SerializationException and are described below.

SerializationException

This is a common parent class for all exceptions thrown during serialization or deserialization (except the PHP-built-in JsonException). It is useful for catching, but never instantiated directly.

InvalidInputException

This is a parent class for all exceptions caused by an invalid input. During serialization, the input in question is the PHP object you want to serialize. For deserialization, the input refers to the JSON data.

MissingPropertyException

During serialization this is thrown if a required property is not initialized. During deserialization this is thrown if a required property is missing in the input data.

IncorrectTypeException

During serialization this is thrown if a property has a null value, but does not allow null. During deserialization this is thrown if a property has a value of an incorrect type (e.g. an int is passed for a string property).

UnsupportedTypeException

As noted above, deserializing intersection types is not supported. If an intersection type is encountered during deserialization, this exception is thrown. It's also thrown if a php built-in type is encountered that is not yet supported by the library.

InvalidEnumBackingException

This exception is thrown if an enum is deserialized with an invalid backing value. This can happen if the value that is deserialized is not scalar, or if the target enum does not have a matching case.

Custom Serializers

If you want to write a serializer for a different format, you can use the ArraySerializer and ArrayDeserializer class. These convert the object to an associative array and vice versa.

See the JsonSerializer and JsonDeserializer classes for an example implementation.