JsonCodec
Interfaces to serialize and deserialize PHP objects to/from JSON
Loading...
Searching...
No Matches
Wikimedia\JsonCodec\JsonCodec Class Reference

Helper class to serialize/unserialize things to/from JSON. More...

+ Inheritance diagram for Wikimedia\JsonCodec\JsonCodec:

Public Member Functions

 __construct (?ContainerInterface $serviceContainer=null)
 
 toJsonString ( $value, ?string $classHint=null)
 Recursively converts a given object to a JSON-encoded string.
 
 newFromJsonString ( $json, ?string $classHint=null)
 Recursively converts a JSON-encoded string to an object value or scalar.
 
 addCodecFor (string $className, JsonClassCodec $codec)
 Allow the use of a customized encoding for the given class; the given className need not be a JsonCodecable and if it does correspond to a JsonCodecable it will override the class codec specified by the JsonCodecable.
 
 toJsonArray ( $value, ?string $classHint=null)
 Recursively converts a given object to an associative array which can be json-encoded.
 
 newFromJsonArray ( $json, ?string $classHint=null)
 Recursively converts an associative array (or scalar) to an object value (or scalar).
 

Protected Member Functions

 codecFor (string $className)
 Maintain a cache giving the codec for a given class name.
 
 isArrayMarked (array $value)
 Determine if the given value is "marked"; that is, either represents a object type encoded using a JsonClassCodec or else is an array which contains values (or contains arrays containing values, etc) which are object types.
 
 markArray (array &$value, string $className, ?string $classHint)
 Record a mark in the array, reversibly.
 
 unmarkArray (array &$value, ?string $classHint)
 Remove a mark from an encoded array, and return an encoded class name if present.
 

Protected Attributes

ContainerInterface $serviceContainer
 
array $codecs
 
const TYPE_ANNOTATION = '_type_'
 Name of the property where class information is stored; it also is used to mark "complex" arrays, and as a place to store the contents of any pre-existing array property that happened to have the same name.
 

Detailed Description

Helper class to serialize/unserialize things to/from JSON.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\JsonCodec\JsonCodec::__construct ( ?ContainerInterface  $serviceContainer = null)
Parameters
?ContainerInterface$serviceContainer
Parameters
string$id
Returns
never

@inheritDoc

Member Function Documentation

◆ addCodecFor()

Wikimedia\JsonCodec\JsonCodec::addCodecFor ( string  $className,
JsonClassCodec  $codec 
)

Allow the use of a customized encoding for the given class; the given className need not be a JsonCodecable and if it does correspond to a JsonCodecable it will override the class codec specified by the JsonCodecable.

Parameters
class-string$className
JsonClassCodec$codecA codec to use for $className

◆ codecFor()

Wikimedia\JsonCodec\JsonCodec::codecFor ( string  $className)
protected

Maintain a cache giving the codec for a given class name.

Reusing this JsonCodec object will also reuse this cache, which could improve performance somewhat.

Parameters
class-string$className
Returns
?JsonClassCodec a codec for the class, or null if the class is not serializable.

◆ isArrayMarked()

Wikimedia\JsonCodec\JsonCodec::isArrayMarked ( array  $value)
protected

Determine if the given value is "marked"; that is, either represents a object type encoded using a JsonClassCodec or else is an array which contains values (or contains arrays containing values, etc) which are object types.

The values of unmarked arrays are not decoded, in order to speed up the decoding process. Arrays may also be marked even if they do not represent object types (or an array recursively containing them) if they contain keys that need to be escaped ("false marks"); as such this method is called both on the raw results of JsonClassCodec (to check for "false marks") as well as on encoded arrays (to find "true marks").

Arrays do not have to be marked if the decoder has a class hint.

Parameters
array$valueAn array result from JsonClassCodec::toJsonArray(), or an array result from ::markArray()
Returns
bool Whether the $value is marked

◆ markArray()

Wikimedia\JsonCodec\JsonCodec::markArray ( array &  $value,
string  $className,
?string  $classHint 
)
protected

Record a mark in the array, reversibly.

The mark should record the class name, if it is different from the class hint. The result does not need to trigger ::isArrayMarked if there is an accurate class hint present, but otherwise the result should register as marked. The provided value may be a "complex" array (one that recursively contains encoded object) or an array with a "false mark"; in both cases the provided $className will be array.

Parameters
array&$valueAn array result from JsonClassCodec::toJsonArray() or a "complex" array
'array'|class-string$className The name of the class encoded by the codec, or else array if $value is a "complex" array or a "false mark"
class-string|'array'|null$classHint The class name provided as a hint to the encoder, and which will be in turn provided as a hint to the decoder, or null if no hint was provided. The class hint will be array when the array is a homogeneous list of objects.

◆ newFromJsonArray()

Wikimedia\JsonCodec\JsonCodec::newFromJsonArray (   $json,
?string  $classHint = null 
)

Recursively converts an associative array (or scalar) to an object value (or scalar).

While converting this value JsonCodec delegates to the appropriate JsonClassCodecs of any classes which implement JsonCodecable.

For objects encoded using implicit class information, a "class hint" can be provided to guide deserialization; this is unnecessary for objects serialized with explicit classes.

Parameters
mixed | null$json
?class-string$classHint An optional hint to the type of the encoded object. In the absence of explicit type information in the JSON, this will be used as the type of the created object.
Returns
mixed|null

Implements Wikimedia\JsonCodec\JsonCodecInterface.

◆ newFromJsonString()

Wikimedia\JsonCodec\JsonCodec::newFromJsonString (   $json,
?string  $classHint = null 
)

Recursively converts a JSON-encoded string to an object value or scalar.

While deserializing the $json JsonCodec delegates to the appropriate JsonClassCodecs of any classes which implement JsonCodecable.

For objects encoded using implicit class information, a "class hint" can be provided to guide deserialization; this is unnecessary for objects serialized with explicit classes.

Parameters
string$jsonA JSON-encoded string
?class-string$classHint An optional hint to the type of the encoded object. In the absence of explicit type information in the JSON, this will be used as the type of the created object.
Returns
mixed|null

◆ toJsonArray()

Wikimedia\JsonCodec\JsonCodec::toJsonArray (   $value,
?string  $classHint = null 
)

Recursively converts a given object to an associative array which can be json-encoded.

(When embeddeding an object into another context it is sometimes useful to have the array representation rather than the string JSON form of the array; this can also be useful if you want to pretty-print the result, etc.) While converting $value the JsonCodec delegates to the appropriate JsonClassCodecs of any classes which implement JsonCodecable.

If a $classHint is provided and matches the type of the value, then type information will not be included in the generated JSON; otherwise an appropriate class name will be added to the JSON to guide deserialization.

Parameters
mixed | null$value
?class-string$classHint An optional hint to the type of the encoded object. If this is provided and matches the type of $value, then explicit type information will be omitted from the generated JSON, which saves some space.
Returns
mixed|null

Implements Wikimedia\JsonCodec\JsonCodecInterface.

◆ toJsonString()

Wikimedia\JsonCodec\JsonCodec::toJsonString (   $value,
?string  $classHint = null 
)

Recursively converts a given object to a JSON-encoded string.

While serializing the $value JsonCodec delegates to the appropriate JsonClassCodecs of any classes which implement JsonCodecable.

If a $classHint is provided and matches the type of the value, then type information will not be included in the generated JSON; otherwise an appropriate class name will be added to the JSON to guide deserialization.

Parameters
mixed | null$value
?class-string$classHint An optional hint to the type of the encoded object. If this is provided and matches the type of $value, then explicit type information will be omitted from the generated JSON, which saves some space.
Returns
string

◆ unmarkArray()

Wikimedia\JsonCodec\JsonCodec::unmarkArray ( array &  $value,
?string  $classHint 
)
protected

Remove a mark from an encoded array, and return an encoded class name if present.

The provided array may not trigger ::isArrayMarked is there was a class hint provided.

If the provided array had a "false mark" or recursively contained objects, the returned class name should be 'array'.

Parameters
array&$valueAn encoded array
'array'|class-string|null$classHint The class name provided as a hint to the decoder, which was previously provided as a hint to the encoder, or null if no hint was provided.
Returns
'array'|class-string The class name to be used for decoding, or 'array' if the value was a "complex" or "false mark" array.

The documentation for this class was generated from the following file: