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	$codec	A 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

$value

An 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	&$value	An 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	$json	A 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 embedding 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	&$value	An 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:

• src/JsonCodec.php