This library is a port of google/gson written in PHP. Its purpose is to easily handle the conversion between PHP objects and JSON. It shares some of google/gson's goals such as:
- A simple interface using
toJson
andfromJson
methods - Enable serialization and deserialization of 3rd party classes
- Allow schema differences between PHP objects and JSON
And in addition:
- Utilize PHP 7 scalar type hints to be intelligent about property types
- Limit the number of annotations required to use
- Allow serialization decisions based on runtime information
Here are some simple use cases to get a feel for how the library works
If you have a PHP object you want to convert to JSON
// $object obtained elsewhere
$gson = Gson::builder()->build();
$json = $gson->toJson($object);
What this is doing is using the provided GsonBuilder
to set up the
Gson
object with sensible defaults. Calling Gson::toJson
and
passing in an object will return a string of JSON.
If you need to, you can force the type Gson will use to serialize
// $object obtained elsewhere
$gson = Gson::builder()->build();
$json = $gson->toJson($object, MyCustomClass::class);
The reverse is very similar
// $json obtained elsewhere
$gson = Gson::builder()->build();
$fooObject = $gson->fromJson($json, Foo::class);
Now we call Gson::fromJson
and pass in the json as a string and the type
of object we'd like to map to. In this example, we will be getting
an instantiated Foo
object back.
If you want to convert your object to a JsonElement, there's a convenience method to do that for you.
// $object obtained elsewhere
$gson = Gson::builder()->build();
$jsonElement = $gson->toJsonElement($object);
This provides a simple way to manipulate the JSON before final encoding.
From here, you can call json_encode()
on the element to convert it to
JSON.
$jsonElement = $gson->toJsonElement($object);
$jsonElement->asObject()->addString('foo', 'bar');
$json = json_encode($jsonElement);
Likewise, there are methods to operate on arrays instead of strings of json
// $object obtained elsewhere
$gson = Gson::builder()->build();
$jsonArray = $gson->toArray($object);
$object = $gson->fromArray($jsonArray);
- Customizing Serialization/Deserialization
- Excluding Classes and Properties
- Customizing Class Instantiation
- Types
- Json Element
- Annotation Reference
- Advanced Usage
This library requires PHP 7.1
composer require tebru/gson-php
Be sure and set up the annotation loader in one of your initial scripts.
\Doctrine\Common\Annotations\AnnotationRegistry::registerLoader('class_exists');
This project is licensed under the MIT license. Please see the LICENSE
file for more information.