Pyther.Json

A lightweight (de)serializer between json strings and data models with the following features:

• support for nested arrays and objects
• pre defined or custom naming policies
• support for basic or backed enumerations.
• meta/attribute support for
  • property renaming
  • property exclusion
  • (array) data type
  • datetime format
  • enum format
• several settings like
  • include protected properties
  • skip null values
  • skip empty arrays
  • skip inherited properties
  • enum format (name, value or full)
  • and more ...
• takes documentation "@var" hints into account
• no external dependencies
• straightforward to use

Requirements:

• PHP 8.1+

Installation

Install the Composer Package

composer require pyther/json

Examples:

Deserialization

// creates a new order class and populate its properties from a json string or array. $order = Json::deserialize($json, Order::class);

Serialization

// creates a json string populate from orders properties.$json = Json::serialize($order);

Optional Settings

$settings = newJsonSettings();
// set optional naming policy, default is none (json attrbiutes equals object attribute names).// supported policies: CamelToPascalNamingPolicy, CamelToSnakeNamingPolicy, CamelToKebabNamingPolicy, PascalToCamelNamingPolicy$settings->setNamingPolicy(newCamelToPascalNamingPolicy());
// Disable json indention (enabled by default).$settings->setPrettyPrint(false);
// Enable or disable to serialize DateTime as string (enabled by default).$settings->setDateTimeAsString(false);
// Set the default date time format (\DateTime::W3C by default).// This can be overwriten per Property using "#[JsonDateTime(...)]"$settings->setDateTimeFormat(\DateTime::W3C)
// Defines the default serialization format for enumerations (EnumFormat::Value by default). // This can be overridden using the "JsonEnum" meta tag.// values are: EnumFormat::Value, EnumFormat::Name, EnumFormat::Full$settings->setEnumFormat(EnumFormat::Value)
// Define to skip null values (false by default).$settings->setSkipNull(true);
// Define to skip empty arrays (false by defaut).$settings->setSkipEmptyArray(true);
// Set to true, to include protected members (false by default).$settings->setIncludeProtected(true)
// Define to skip inherited properties (false by default).$settings->setSkipInheritedProperties(true);
$json = Json::serialize($order, $settings);

Enums

enum Status : int {
case Inactive = 0;
case Active = 1;
}

EnumFormat::Name

class EnumTest {
#[JsonEnum(EnumFormat::Name)]
publicStatus$status;
}
// or set global for all enums$settings->setEnumFormat(EnumFormat::Name);

Result:

{
"Status": "Active"
}

EnumFormat::Value

class EnumTest {
#[JsonEnum(EnumFormat::Value)]
publicStatus$status;
}
// or set global for all enums$settings->setEnumFormat(EnumFormat::Value);

Result:

{
"Status": 1
}

EnumFormat::Full

class EnumTest {
#[JsonEnum(EnumFormat::Full)]
publicStatus$status;
}
// or set global for all enums$settings->setEnumFormat(EnumFormat::Full);

Result:

{
"Status": {
"Name": "Active",
"Value": 1
}
}

Meta/Attributes

Json

The attribute allows to manually match a single property with a json attribute. This attribute will ignore the selected naming policy.

usePyther\Json\Attributes\Json;
class MyClass
{
// fill the "sku" from the json "id" property. 
#[Json("id)] public string $sku;
}

JsonIgnore

Allows to ignore a single property during serialization, deserialization or both.

usePyther\Json\Attributes\JsonIgnore;
class MyClass
{
// ignore on serialization and deserialization
#[JsonIgnore]
publicstring$ignoreMe;
// ignore on serialization only
#[JsonIgnore(true, false)]
publicstring$ignoreMe;
// ignore on deserialization only
#[JsonIgnore(false, true)]
publicstring$ignoreMe;
}

JsonType

Defines a datatype for a single property. This is especially useful for arrays due the lack of type hint support for arrays in php.

usePyther\Json\Attributes\JsonType;
class MyClass
{
// definfes the type of the array items.
#[JsonType(OrderItem::class)]
publicarray$typedArrayByMeta;
// possible to replace the missing build in datatype.
#[JsonType(\int::class)]
public$intByMeta;
}

JsonDateTime

Allows to define a date/time format for a single property.

usePyther\Json\Attributes\JsonDateTime;
class MyClass
{
// parse this property by the given format.
#[JsonDateTime("d/m/Y")]
publicstring$dayOfBirth;
}

JsonEnum

Allows to define the enum serialization format for a single property.

usePyther\Json\Attributes\JsonEnum;
class MyClass
{
// parse this property by the given format.
#[JsonEnum(EnumFormat::Name)]
publicStatus$status;
}

JsonComplete

Allows a post process when the object and all child objects are ready.

usePyther\Json\Attributes\JsonComplete;
class MyClass
{
// ...// Any parameterless function with any name you want. 
#[JsonComplete]
publicfunctiononComplete() {
// $this is fully parsed and ready to use here
}
}