dcarbone/gojson

PHP lib intended to assist in marshalling and unmarshalling JSON data from Golang-based services

Fund package maintenance!
dcarbone

dev-main 2023-12-28 13:33 UTC

This package is auto-updated.

Last update: 2024-10-28 15:33:39 UTC


README

WIP: this is a work in progress, and not suitable for actual use at this time.

PHP lib intended to assist in marshalling and unmarshalling JSON data from Golang-based services

Transcoding class

The Transcoding class is a container for this package's constants and a few helper functions.

Unmarshaller trait

The Unmarshaller trait is intended to be embedded within any class that you wish to unmarshall from JSON. As a basic example:

use DCarbone\Go\JSON\Transcoding;
use DCarbone\Go\JSON\Unmarshaller;

class Classname {
    use Unmarshaller;
    
    protected const FIELDS = [
        'stringField' => [
            Transcoding::FIELD_TYPE => Transcoding::STRING,
        ],
        'intField' => [
            Transcoding::FIELD_TYPE => Transcoding::INTEGER,
        ],
        'floatField' => [
            Transcoding::FIELD_TYPE => Transcoding::DOUBLE,
        ],
    ];
    
    public string $stringField;
    public int $intField;
    public float $floatField;
}

$inst = Classname::UnmarshalGoJSON(<<<EOT
{
    "stringField": "value",
    "intField": 1,
    "floatField": 1.1
}
EOT
);

Marshaller trait

The Marshaller trait is intended to be embedded within any class that you wish to marshall to JSON. As a basic example:

use DCarbone\Go\JSON\Transcoding;

class Classname {
    use \DCarbone\Go\JSON\Marshaller;
    
    protected const FIELDS = [
        'stringField' => [
            Transcoding::FIELD_TYPE => Transcoding::STRING,
            Transcoding::FIELD_OMITEMPTY => true,
        ],
        'intField' => [
            Transcoding::FIELD_TYPE => Transcoding::INTEGER,
            Transcoding::FIELD_OMITEMPTY => true,
        ],
        'floatField' => [
            Transcoding::FIELD_TYPE => Transcoding::DOUBLE,
            Transcoding::FIELD_OMITEMPTY => true,
        ],
    ];
    
    public string $stringField = '';
    public int $intField = 1;
    public float $floatField = 0.0;
}

$inst = new Classname();
$json = $inst->MarshalGoJSON();
echo $json; // {"intField": 1}

FIELD_X constants

"Zero" Values

Every type in Golang has an accompanying "zero" value. You can reference this Tour of Go chapter for some examples.

This has significant impact when marshalling and unmarshalling Go types with JSON, as depending upon the configured struct tags, marshaller used, and field type, an otherwise "empty" field may still have a non-null value when accessed.

To assist with this, this lib comes with a Zero type that allows you to check if a given value is "zero" or not.

Custom Zero Values

In some cases, null may not be desirable for a "zero-val" or "default" field on a type. To that end, you may either implement the ZeroVal interface on the type directly, or register a ZeroState to the Zero::$zeroStates static parameter.