Documentation

JsonMapper
in package

Automatically map JSON structures into objects.

Tags
category

Netresearch

author

Christian Weiske cweiske@cweiske.de

license

OSL-3.0 http://opensource.org/licenses/osl-3.0

link
http://cweiske.de/

Table of Contents

$bEnforceMapType  : bool
If the types of map() parameters shall be checked.
$bExceptionOnMissingData  : bool
Throw an exception if the JSON data miss a property that is marked with @required in the PHP class
$bExceptionOnUndefinedProperty  : bool
Throw an exception when JSON data contain a property that is not defined in the PHP class
$bIgnoreVisibility  : bool
Allow mapping of private and proteted properties.
$bRemoveUndefinedAttributes  : bool
Remove attributes that were not passed in JSON, to avoid confusion between them and NULL values.
$bStrictNullTypes  : bool
Throw an exception, if null value is found but the type of attribute does not allow nulls.
$bStrictObjectTypeChecking  : bool
Throw an exception when an object is expected but the JSON contains a non-object type.
$classMap  : array<string|int, mixed>
Override class names that JsonMapper uses to create objects.
$postMappingMethod  : string|null
Method to call on each object after deserialization is done.
$undefinedPropertyHandler  : callable
Callback used when an undefined property is found.
$arInspectedClasses  : array<string|int, mixed>
Runtime cache for inspected classes. This is particularly effective if mapArray() is called with a large number of objects
$logger  : object
PSR-3 compatible logger object
map()  : mixed
Map data all data in $json into the given $object instance.
mapArray()  : mixed
Map an array
setLogger()  : null
Sets a logger instance on the object
checkMissingData()  : void
Check required properties exist in json
createInstance()  : object
Create a new object of the given type.
getCamelCaseName()  : string
Removes - and _ and makes the next letter uppercase
getFullNamespace()  : string
Convert a type name to a fully namespaced type name.
getMappedType()  : string
Get the mapped class/type name for this class.
getSafeName()  : string
Since hyphens cannot be used in variables we have to uppercase them.
inspectProperty()  : array<string|int, mixed>
Try to find out if a property exists in a given class.
isArrayOfType()  : bool
Returns true if type is an array of elements (bracket notation)
isFlatType()  : bool
Checks if the given type is a type that is not nested (simple type except array and object)
isNullable()  : bool
Checks if the given type is nullable
isObjectOfSameType()  : bool
Checks if the object is of this type or has this type as one of its parents
isSimpleType()  : bool
Checks if the given type is a "simple type"
log()  : null
Log a message to the $logger object
parseAnnotations()  : array<string|int, mixed>
Copied from PHPUnit 3.7.29, Util/Test.php
removeNullable()  : string
Remove the 'null' section of a type
removeUndefinedAttributes()  : void
Remove attributes from object that were not passed in JSON data.
setProperty()  : void
Set a property on a given object to a given value.

Properties

$bEnforceMapType

If the types of map() parameters shall be checked.

public bool $bEnforceMapType = \true

You have to disable it if you're using the json_decode "assoc" parameter.

json_decode($str, false)

$bExceptionOnMissingData

Throw an exception if the JSON data miss a property that is marked with @required in the PHP class

public bool $bExceptionOnMissingData = \false

$bExceptionOnUndefinedProperty

Throw an exception when JSON data contain a property that is not defined in the PHP class

public bool $bExceptionOnUndefinedProperty = \false

$bIgnoreVisibility

Allow mapping of private and proteted properties.

public bool $bIgnoreVisibility = \false

$bRemoveUndefinedAttributes

Remove attributes that were not passed in JSON, to avoid confusion between them and NULL values.

public bool $bRemoveUndefinedAttributes = \false

$bStrictNullTypes

Throw an exception, if null value is found but the type of attribute does not allow nulls.

public bool $bStrictNullTypes = \true

$bStrictObjectTypeChecking

Throw an exception when an object is expected but the JSON contains a non-object type.

public bool $bStrictObjectTypeChecking = \false

$classMap

Override class names that JsonMapper uses to create objects.

public array<string|int, mixed> $classMap = array()

Useful when your setter methods accept abstract classes or interfaces.

$postMappingMethod

Method to call on each object after deserialization is done.

public string|null $postMappingMethod = \null

Is only called if it exists on the object.

$undefinedPropertyHandler

Callback used when an undefined property is found.

public callable $undefinedPropertyHandler = \null

Works only when $bExceptionOnUndefinedProperty is disabled.

Parameters to this function are:

  1. Object that is being filled
  2. Name of the unknown JSON property
  3. JSON value of the property

$arInspectedClasses

Runtime cache for inspected classes. This is particularly effective if mapArray() is called with a large number of objects

protected array<string|int, mixed> $arInspectedClasses = array()

property inspection result cache

Methods

map()

Map data all data in $json into the given $object instance.

public map(object|array<string|int, mixed> $json, object $object) : mixed
Parameters
$json : object|array<string|int, mixed>

JSON object structure from json_decode()

$object : object

Object to map $json data into

Tags
see
mapArray()
Return values
mixed —

Mapped object is returned.

mapArray()

Map an array

public mapArray(array<string|int, mixed> $json, mixed $array[, string $class = null ][, string $parent_key = '' ]) : mixed
Parameters
$json : array<string|int, mixed>

JSON array structure from json_decode()

$array : mixed

Array or ArrayObject that gets filled with data from $json

$class : string = null

Class name for children objects. All children will get mapped onto this type. Supports class names and simple types like "string" and nullability "string|null". Pass "null" to not convert any values

$parent_key : string = ''

Defines the key this array belongs to in order to aid debugging.

Return values
mixed —

Mapped $array is returned

setLogger()

Sets a logger instance on the object

public setLogger(LoggerInterface $logger) : null
Parameters
$logger : LoggerInterface

PSR-3 compatible logger object

Return values
null —

checkMissingData()

Check required properties exist in json

protected checkMissingData(array<string|int, mixed> $providedProperties, object $rc) : void
Parameters
$providedProperties : array<string|int, mixed>

array with json properties

$rc : object

Reflection class to check

Tags
throws
JsonMapper_Exception
Return values
void —

createInstance()

Create a new object of the given type.

protected createInstance(string $class[, bool $useParameter = false ][, mixed $jvalue = null ]) : object

This method exists to be overwritten in child classes, so you can do dependency injection or so.

Parameters
$class : string

Class name to instantiate

$useParameter : bool = false

Pass $parameter to the constructor or not

$jvalue : mixed = null

Constructor parameter (the json value)

Return values
object —

Freshly created object

getCamelCaseName()

Removes - and _ and makes the next letter uppercase

protected getCamelCaseName(string $name) : string
Parameters
$name : string

Property name

Return values
string —

CamelCasedVariableName

getFullNamespace()

Convert a type name to a fully namespaced type name.

protected getFullNamespace(string $type, string $strNs) : string
Parameters
$type : string

Type name (simple type or class name)

$strNs : string

Base namespace that gets prepended to the type name

Return values
string —

Fully-qualified type name with namespace

getMappedType()

Get the mapped class/type name for this class.

protected getMappedType(string $type[, mixed $jvalue = null ]) : string

Returns the incoming classname if not mapped.

Parameters
$type : string

Type name to map

$jvalue : mixed = null

Constructor parameter (the json value)

Return values
string —

The mapped type/class name

getSafeName()

Since hyphens cannot be used in variables we have to uppercase them.

protected getSafeName(string $name) : string

Technically you may use them, but they are awkward to access.

Parameters
$name : string

Property name

Return values
string —

Name without hyphen

inspectProperty()

Try to find out if a property exists in a given class.

protected inspectProperty(ReflectionClass $rc, string $name) : array<string|int, mixed>

Checks property first, falls back to setter method.

Parameters
$rc : ReflectionClass

Reflection class to check

$name : string

Property name

Return values
array<string|int, mixed> —

First value: if the property exists Second value: the accessor to use ( ReflectionMethod or ReflectionProperty, or null) Third value: type of the property Fourth value: if the property is nullable

isArrayOfType()

Returns true if type is an array of elements (bracket notation)

protected isArrayOfType(string $strType) : bool
Parameters
$strType : string

type to be matched

Return values
bool —

isFlatType()

Checks if the given type is a type that is not nested (simple type except array and object)

protected isFlatType(string $type) : bool
Parameters
$type : string

type name from gettype()

Tags
see
isSimpleType()
Return values
bool —

True if it is a non-nested PHP type

isNullable()

Checks if the given type is nullable

protected isNullable(string $type) : bool
Parameters
$type : string

type name from the phpdoc param

Return values
bool —

True if it is nullable

isObjectOfSameType()

Checks if the object is of this type or has this type as one of its parents

protected isObjectOfSameType(string $type, mixed $value) : bool
Parameters
$type : string

class name of type being required

$value : mixed

Some PHP value to be tested

Return values
bool —

True if $object has type of $type

isSimpleType()

Checks if the given type is a "simple type"

protected isSimpleType(string $type) : bool
Parameters
$type : string

type name from gettype()

Tags
see
isFlatType()
Return values
bool —

True if it is a simple PHP type

log()

Log a message to the $logger object

protected log(string $level, string $message[, array<string|int, mixed> $context = array() ]) : null
Parameters
$level : string

Logging level

$message : string

Text to log

$context : array<string|int, mixed> = array()

Additional information

Return values
null —

parseAnnotations()

Copied from PHPUnit 3.7.29, Util/Test.php

protected static parseAnnotations(string $docblock) : array<string|int, mixed>
Parameters
$docblock : string

Full method docblock

Return values
array<string|int, mixed> —

Array of arrays. Key is the "@"-name like "param", each value is an array of the rest of the @-lines

removeNullable()

Remove the 'null' section of a type

protected removeNullable(string $type) : string
Parameters
$type : string

type name from the phpdoc param

Return values
string —

The new type value

removeUndefinedAttributes()

Remove attributes from object that were not passed in JSON data.

protected removeUndefinedAttributes(object $object, array<string|int, mixed> $providedProperties) : void

This is to avoid confusion between those that were actually passed as NULL, and those that weren't provided at all.

Parameters
$object : object

Object to remove properties from

$providedProperties : array<string|int, mixed>

Array with JSON properties

Return values
void —

setProperty()

Set a property on a given object to a given value.

protected setProperty(object $object, object $accessor, mixed $value) : void

Checks if the setter or the property are public are made before calling this method.

Parameters
$object : object

Object to set property on

$accessor : object

ReflectionMethod or ReflectionProperty

$value : mixed

Value of property

Return values
void —

Search results