A library to marshall and unmarshall JSON strings to populated PHP classes, driven by annotations.
We would like fine grain control over our marshalling and unmarshalling because:
- json_decode always returns a StdClass object. We want to be able to decode into our own classes.
- We can add expected type information about the data we are receiving/sending and validate it before using it.
- json_encode cannot be controlled on a property by property basis. This will allow us to do that.
The latest version can be found here: https://github.com/AnujRNair/php-json-marshaller.
$ git clone https://github.com/AnujRNair/php-json-marshaller.git
$ composer install
In your classes, add MarshallProperty annotations to your properties and methods to describe how JSON should be marshalled or unmarshalled.
The MarshallProperty annotation requires a name and type, otherwise an exception will be thrown.
You can do this on any public property or method.
use PhpJsonMarshaller\Annotations\MarshallProperty;
class User
{
/**
* @MarshallProperty(name="id", type="int")
* This property is public - it will be accessed directly
*/
public $id;
/**
* This property is NOT public - it must be accessed through a getter (marshalling) or a setter (unmarshalling)
*/
protected $name;
/**
* @MarshallProperty(name="name", type="string")
* This function will be used for marshalling json
*/
public function getName()
{
return $this->name;
}
/**
* @MarshallProperty(name="name", type="string")
* This function will be used for unmarshalling json
*/
public function setName($name)
{
$this->name = $name;
}
}
Once you have configured your class, load an instance of the JSONMarshaller class, and call the marshall or unmarshall function:
use PhpJsonMarshaller\Decoder\ClassDecoder;
use PhpJsonMarshaller\Marshaller\JsonMarshaller;
use PhpJsonMarshaller\Reader\DoctrineAnnotationReader;
$json = '{
"id": 12345,
"name": "Anuj"
}';
// Assuming autoloading
$marshaller = new JsonMarshaller(new ClassDecoder(new DoctrineAnnotationReader()));
// Notice the fully qualified namespace!
$user = $marshaller->unmarshall($json, '\My\Example\User');
// Use the new class
echo $user->getName(); // (string) 'Anuj'
// Marshall the class
$marshalled = $marshaller->marshall($user);
// $json and $marshalled are both json_encoded string holding the same data
$json == $marshalled;
The $user
variable should now be an instance of the \My\Example\User
class, and be populated with the id and name we passed in from the JSON string.
The $marshalled
variable will be a json encoded string holding data from the \My\Example\User
object instance.
You can also nest classes within classes for recursive marshalling and unmarshalling like so:
use PhpJsonMarshaller\Annotations\MarshallProperty;
class User
{
/**
* @MarshallProperty(name="address", type="\My\Example\Address")
* Notice the fully qualified namespace!
*/
public $address;
}
And then in your code:
use PhpJsonMarshaller\Decoder\ClassDecoder;
use PhpJsonMarshaller\Marshaller\JsonMarshaller;
use PhpJsonMarshaller\Reader\DoctrineAnnotationReader;
$json = '{
"id": 12345,
"name": "Anuj",
"address": {
"id": 1,
"street": "123 Main Street"
}
}';
// Assuming autoloading
$marshaller = new JsonMarshaller(new ClassDecoder(new DoctrineAnnotationReader()));
// Notice the fully qualified namespace!
$user = $marshaller->unmarshall($json, '\My\Example\User');
// Use the nested object
$user->getAddress()->getStreet(); // (string) "123 Main Street"
You can marshall and unmarshall arrays of scalars/objects by indicating so in the type of the MarshallProperty annotation:
use PhpJsonMarshaller\Annotations\MarshallProperty;
class User
{
/**
* @MarshallProperty(name="flags", type="\My\Example\Flag[]")
* Notice the fully qualified namespace and the array indicator in the type
*/
public $flags;
}
Then in your code:
use PhpJsonMarshaller\Decoder\ClassDecoder;
use PhpJsonMarshaller\Marshaller\JsonMarshaller;
use PhpJsonMarshaller\Reader\DoctrineAnnotationReader;
$json = '{
"id": 12345,
"name": "Anuj",
"flags": [
{
"id": 11087,
"value": 0
},
{
"id": 11088,
"value": 1
}
],
}';
// Assuming autoloading
$marshaller = new JsonMarshaller(new ClassDecoder(new DoctrineAnnotationReader()));
// Notice the fully qualified namespace!
$user = $marshaller->unmarshall($json, '\My\Example\User');
// Use the data
$user->getFlags()[0]->getId(); // (int) 11087
To unmarshall into an object with a constructor, with required params, use the @MarshallCreator annotation to describe to the marshaller which values to instantiate the class with.
This Annotation takes an array of @MarshallProperty objects like the following:
use PhpJsonMarshaller\Annotations\MarshallCreator;
use PhpJsonMarshaller\Annotations\MarshallProperty;
class User
{
/**
* @var int $id
*/
protected $id;
/**
* @var float $rank
*/
protected $rank;
/**
* @MarshallCreator({@MarshallProperty(name="id", type="int"), @MarshallProperty(name="rank", type="float")})
*/
public function __construct($id, $rank)
{
$this->id = $id;
$this->rank = $rank;
}
}
The marshaller will then look for these values in the json string passed to it (The same level on which the class was instantiated) and instantiate the object with these values.
You can cache decoded classes for performance boosts. This will not cache data from JSON strings.
To do so, instantiate an instance of the Cache
class, and pass in a storage type. Then pass this through to the ClassDecoder
instance:
use PhpJsonMarshaller\Cache\Cache;
use PhpJsonMarshaller\Cache\Storage\InMemoryStorage;
use PhpJsonMarshaller\Decoder\ClassDecoder;
use PhpJsonMarshaller\Marshaller\JsonMarshaller;
use PhpJsonMarshaller\Reader\DoctrineAnnotationReader;
$marshaller = new JsonMarshaller(
new ClassDecoder(
new DoctrineAnnotationReader(),
new Cache(
new InMemoryStorage()
)
)
);
See \PhpJsonMarshaller\Cache\Storage
for all storage types available. MemcachedStorage
has a few options you can set as well.
You can specifically allow a class to fail on any unknown json variables by adding a MarshallConfig annotation to a specific class:
use PhpJsonMarshaller\Annotations\MarshallConfig;
/**
* @MarshallConfig(ignoreUnknown=false)
*/
class User
{
}
Now if you try unmarshalling an unknown variable into this class, an exception will be thrown.
Testing is covered by PHPUnit. Browse to the root of the library and run phpunit
.
Please ensure you have the memcached daemon running to ensure the MemcachedStorageTest
tests pass.
Please see the License