taquillacom/gson-php

Gson for PHP: Convert PHP objects to and from json

v0.9.5 2025-05-19 16:05 UTC

Requires

• php: >=8.2
• ext-ctype: *
• phpdocumentor/reflection-docblock: ^3.2.3|^4.0.1|^5
• psr/simple-cache: ^3.0
• symfony/cache: ^3.3|^4.0|^5.0|^6.0
• taquillacom/doctrine-annotation-reader: ^0.4
• tebru/php-type: ^0.1.7

Requires (Dev)

• phpunit/phpunit: ^8.0

MIT

• Nate Brunette

README

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 and fromJson 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

Overview

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.

Gson has a concept of "normalized" forms. This just means data that has been decoded with json_decode, or can be passed into json_encode.

// $object obtained elsewhere

$gson = Gson::builder()->build();
$jsonArray = $gson->toNormalized($object);
$object = $gson->fromNormalized($jsonArray, Foo::class);

Documentation

• Customizing Serialization/Deserialization
• Excluding Classes and Properties
• Customizing Class Instantiation
• Types
• Annotation Reference
• Advanced Usage
• Performance Considerations

Installation

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');

License

This project is licensed under the MIT license. Please see the LICENSE file for more information.