monkeyslegion-serializer

MonkeysLegion Serializer

Attribute-driven object↔JSON/XML serializer for the MonkeysLegion v2 framework.

PHP 8.4 property hooks • readonly DTOs • backed enums • typed collections • serialization groups • naming strategies • polymorphic discriminators • PHPStan Level 9

Installation

composer require monkeyscloud/monkeyslegion-serializer

Requirements: PHP ≥ 8.4 · ext-json · ext-simplexml · ext-dom

Quick Start

use MonkeysLegion\Serializer\Serializer;
use MonkeysLegion\Serializer\Attribute\{Serializable, SerializedName, Ignore, Groups, Type, DateFormat};

#[Serializable]
class User
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,

        #[SerializedName('email_address')]
        public readonly string $email,

        #[Ignore]
        public readonly string $passwordHash,

        #[Groups(['admin'])]
        public readonly string $role = 'user',

        #[DateFormat('Y-m-d')]
        public readonly \DateTimeImmutable $createdAt = new \DateTimeImmutable(),
    ) {}
}

$serializer = Serializer::create();

// Serialize to JSON
$json = $serializer->toJson(new User(
    id: 1,
    name: 'Jorge',
    email: 'jorge@monkeys.cloud',
    passwordHash: 'hashed',
    role: 'admin',
));
// {"id":1,"name":"Jorge","email_address":"jorge@monkeys.cloud","role":"admin","created_at":"2026-05-17"}

// Deserialize from JSON
$user = $serializer->fromJson($json, User::class);
echo $user->name; // Jorge

Attributes Reference

AttributeTargetDescription#[Serializable]ClassMark class as serializable (optional groups, xmlRoot)#[SerializedName('x')]PropertyOverride the output key name#[Ignore]PropertyExclude from serialization & deserialization#[Groups(['api'])]PropertyInclude only when group is active#[Type(Item::class)]PropertyHint collection item type#[DateFormat('Y-m-d')]PropertyCustom date format#[MaxDepth(2)]PropertyLimit nesting depth for this property#[Accessor(getter:, setter:)]PropertyCustom getter/setter for private properties#[Transform(serialize:, deserialize:)]PropertyCustom value transform callbacks#[PreSerialize]MethodHook: runs before serialization#[PostDeserialize]MethodHook: runs after deserialization#[Discriminator]ClassPolymorphic type mapping#[XmlRoot('user')]ClassXML root element name#[XmlElement('item')]PropertyXML child element name#[XmlAttribute]PropertySerialize as XML attribute

Lifecycle Hooks

use MonkeysLegion\Serializer\Attribute\{PreSerialize, PostDeserialize};

class Order
{
    public int $id;
    public float $subtotal;
    public float $tax;
    public float $total = 0;

    #[PreSerialize]
    public function computeTotal(): void
    {
        $this->total = $this->subtotal + $this->tax;
    }

    #[PostDeserialize]
    public function onLoaded(): void
    {
        $this->total = $this->subtotal + $this->tax;
    }
}

Value Transforms

use MonkeysLegion\Serializer\Attribute\Transform;

class Contact
{
    #[Transform(serialize: 'strtolower', deserialize: 'strtolower')]
    public string $email;

    #[Transform(serialize: 'trim')]
    public string $name;
}

Custom Accessors

use MonkeysLegion\Serializer\Attribute\Accessor;

class User
{
    #[Accessor(getter: 'getEmail', setter: 'setEmail')]
    private string $email;

    public function getEmail(): string { return $this->email; }
    public function setEmail(string $v): void { $this->email = strtolower($v); }
}

Per-Property Max Depth

use MonkeysLegion\Serializer\Attribute\MaxDepth;

class User
{
    public int $id;

    #[MaxDepth(1)]
    public ?Company $company; // Only serialized at top-level, not nested
}

Exception Handling

use MonkeysLegion\Serializer\Exception\{
    SerializerException,
    SerializationException,
    DeserializationException,
};

try {
    $user = $serializer->fromJson($invalidJson, User::class);
} catch (DeserializationException $e) {
    // Handle deserialization-specific errors
} catch (SerializerException $e) {
    // Catch all serializer errors
}

Serialization Groups

use MonkeysLegion\Serializer\DTO\SerializationContext;

// Only include 'api' group fields
$json = $serializer->serialize($user, 'json', new SerializationContext(
    groups: ['api'],
));

Naming Strategies

use MonkeysLegion\Serializer\Enum\NamingStrategy;

// camelCase output
$serializer = Serializer::create(NamingStrategy::CamelCase);

// snake_case output (default)
$serializer = Serializer::create(NamingStrategy::SnakeCase);

// kebab-case output
$serializer = Serializer::create(NamingStrategy::KebabCase);

XML Support

use MonkeysLegion\Serializer\Attribute\{XmlRoot, XmlElement, XmlAttribute};

#[XmlRoot('order')]
class Order
{
    #[XmlAttribute]
    public int $id;

    #[XmlElement('line_item')]
    public array $items;
}

$xml = $serializer->toXml($order);

Backed Enums

enum Status: string
{
    case Active   = 'active';
    case Inactive = 'inactive';
}

class Account
{
    public function __construct(
        public readonly int $id,
        public readonly Status $status,
    ) {}
}

// Enums serialize to their scalar value automatically
$json = $serializer->toJson(new Account(1, Status::Active));
// {"id":1,"status":"active"}

// And deserialize back
$account = $serializer->fromJson($json, Account::class);
$account->status === Status::Active; // true

Polymorphic Discriminator

use MonkeysLegion\Serializer\Attribute\Discriminator;

#[Discriminator(field: 'type', map: [
    'cat' => Cat::class,
    'dog' => Dog::class,
])]
abstract class Animal
{
    public string $name;
}

class Cat extends Animal { public int $lives = 9; }
class Dog extends Animal { public string $breed; }

$json = '{"type":"cat","name":"Whiskers","lives":7}';
$animal = $serializer->fromJson($json, Animal::class);
// Returns Cat instance

Collections

use MonkeysLegion\Serializer\Attribute\Type;

class Order
{
    public int $id;

    #[Type('list<OrderItem>')]
    public array $items = [];
}

// Serialize/deserialize lists
$json = $serializer->serializeList($orders);
$orders = $serializer->deserializeList($json, Order::class);

Context Options

SerializationContext

OptionTypeDefaultDescriptiongroupslist<string>[]Active groups (empty = all)maxDepthint10Max object nesting depthdateFormatstringISO 8601Default date formatserializeNullsboolfalseInclude null values

DeserializationContext

OptionTypeDefaultDescriptiongroupslist<string>[]Active groups (empty = all)ignoreUnknownbooltrueSkip unknown keysdateFormatstringISO 8601Expected date formatstrictTypesboolfalseEnforce strict coercion

DI Integration

use MonkeysLegion\Serializer\Provider\SerializerProvider;

// Register in your container
$serializer = SerializerProvider::register($config['serializer'] ?? []);

Configuration (config/serializer.mlc)

php ml serializer:install

serializer {
    default_format  = json
    naming_strategy = snake_case
    serialize_nulls = false
    date_format     = "Y-m-d\TH:i:sP"
    max_depth       = 10

    json {
        pretty_print = false
    }

    xml {
        version  = "1.0"
        encoding = "UTF-8"
        root_tag = "root"
    }
}

License

MIT © 2026 MonkeysCloud Team