-
Notifications
You must be signed in to change notification settings - Fork 12
JsonMarshaller
The JsonMarshaller providers serialization of PHP data-structures to/from JSON. It is superficially similar to Jackson in the Java world.
Currently it is configured using either \Doctrine\Common\Annotations the \Weasel\Annotation library, though there is no reason configuration cannot be loaded from elsewhere.
A major difference between Weasel and Jackson is that Weasel requires all properties to be annotated, as PHP does not provide typing information that would be of use during de-serialization.
Annotate up all the classes in your object model appropriately, then:
// Get the default factory
$factory = new \Weasel\WeaselDefaultAnnotationDrivenFactory();
// or the Doctrine driven one:
$factory = new \Weasel\WeaselDoctrineAnnotationDrivenFactory();
// Get a mapper
$marshaller = $factory->getJsonMapperInstance();
// Unmarshal to a given type (see the documentation on types.)
// This could return a derived class of the target if the target's a class with TypeInfo.
$object = $marshaller->readString($json, $targetType);
// Marshall to JSON
$json = $marshaller->writeString($object)You can also marshal primitive types and arrays, and subclasses which use TypeInfo, by passing a type string as the second parameter to writeString(). E.g.:
$json = $marshaller->writeString($arrayOfStrings, 'string[]');You've got a choice, the Doctrine driven annotations are probably the future though. Both use the same naming, though handling of constants/enums differ. Examples will be provided for both where there are differences.
NOTE: You MUST have use statements for any annotations that you intend to use.
Doctrine Namespace: \Weasel\JsonMarshaller\Config\DoctrineAnnotations
Weasel Namespace: \Weasel\JsonMarshaller\Config\Annotations
- @JsonCreator For constructors and factory methods
- @JsonIgnoreProperties Suppress unknown property warnings
- @JsonInclude What to serialize null/empty values as
- @JsonProperty A property or getter/setter to serialize/deserialize
- @JsonSubTypes Types which extend this class
- @JsonTypeInfo Configure inheritance
- @JsonTypeName The name of this class when dealing with inheritance
- @JsonAnyGetter and @JsonAnySetter Store and retrieve unknown properties
The JsonMarshaller has a pluggable type system. It uses the same syntax as AnnotationTypes and has the same types, plus datetime, available as builtins. When serializing arrays an array specified using [] will be serialized as a JSON array, while an array with a key type specified (even if the type is int) will be serialized as a JSON object.
New types should implement the \Weasel\JsonMarshaller\Types\JsonType interface. To register a type call the registerJsonType() method on your JsonMapper instance. You can override built-in types and aliases by registering replacements with the same name: the last type to be registered with a given name will win.
By default a PHP DateTime object in a field of type "datetime" will be serialized to an ISO 8601 string. Deserializing also expects this format. If you want to change the datetime format you can instantiate a new \Weasel\JsonMarshaller\Types\DateTimeType, passing a DateTime format constant (or date() format string) to the constructor. You can then register this new instance of the type with your JsonMapper (see above.)