README

This package provides a customizable wrapper around the Symfony Serializer Component to use it inside Laravel application.

Requirements

Installation

composer require lastdragon-ru/lara-asp-serializer

Usage

<?php declare(strict_types = 1);

// phpcs:disable PSR1.Files.SideEffects
// phpcs:disable PSR1.Classes.ClassDeclaration

namespace LastDragon_ru\LaraASP\Serializer\Docs\Examples\Usage;

use DateTimeInterface;
use Illuminate\Support\Facades\Date;
use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable;
use LastDragon_ru\LaraASP\Serializer\Contracts\Serializer;

class User implements Serializable {
    public function __construct(
        public int $id,
        public string $name,
        public DateTimeInterface $created,
    ) {
        // empty
    }
}

$user         = new User(1, 'User', Date::parse('2023-08-27T08:30:44.473+00:00'));
$serializer   = app()->make(Serializer::class);
$serialized   = $serializer->serialize($user);
$deserialized = $serializer->deserialize(User::class, $serialized);

Example::dump($serialized);
Example::dump($deserialized);

The $serialized is:

"{"id":1,"name":"User","created":"2023-08-27T08:30:44.473+00:00"}"

The $deserialized is:

LastDragon_ru\LaraASP\Serializer\Docs\Examples\Usage\User {
  +id: 1
  +name: "User"
  +created: Illuminate\Support\Carbon {
    +"date": "2023-08-27 08:30:44.473000"
    +"timezone_type": 1
    +"timezone": "+00:00"
  }
}

Partial deserialization

Sometimes you don't know (or do not want to support) the full structure of the object. In this case you can mark the class as Partial to allow unserialize only known (wanted) properties:

<?php declare(strict_types = 1);

// phpcs:disable PSR1.Files.SideEffects
// phpcs:disable PSR1.Classes.ClassDeclaration

namespace LastDragon_ru\LaraASP\Serializer\Docs\Examples\Partial;

use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\LaraASP\Serializer\Contracts\Partial;
use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable;
use LastDragon_ru\LaraASP\Serializer\Contracts\Serializer;

class User implements Serializable, Partial {
    public function __construct(
        public string $name,
    ) {
        // empty
    }
}

$serializer   = app()->make(Serializer::class);
$deserialized = $serializer->deserialize(User::class, '{"id":1,"name":"User"}');

Example::dump($deserialized);

The $deserialized is:

LastDragon_ru\LaraASP\Serializer\Docs\Examples\Partial\User {
  +name: "User"
}

Extending

Out of the box, the package supports only the following objects (see Factory for more details):

• Any object that implement Serializable (see SerializableNormalizer)
• Any object that implement \DateTimeInterface (see DateTimeNormalizer)
• \DateTimeZone
• \DateInterval
• PHP Enums

Publish the config and add normalizers/denormalizers if you need more:

php artisan vendor:publish --provider=LastDragon_ru\\LaraASP\\Serializer\\PackageProvider --tag=config

Eloquent Accessor/Mutator¹

You can use the Serialized attribute to populate a model attribute to/from an object:

<?php declare(strict_types = 1);

// phpcs:disable PSR1.Files.SideEffects
// phpcs:disable PSR1.Classes.ClassDeclaration

namespace LastDragon_ru\LaraASP\Serializer\Docs\Examples\Attribute;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\LaraASP\Serializer\Casts\Serialized;
use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable;

class UserSettings implements Serializable {
    public function __construct(
        public int $perPage,
        public bool $showSidebar,
    ) {
        // empty
    }
}

class User extends Model {
    /**
     * @return Attribute<?UserSettings, ?UserSettings>
     */
    protected function settings(): Attribute {
        return app()->make(Serialized::class)->attribute(UserSettings::class);
    }
}

$user           = new User();
$user->settings = new UserSettings(35, false);

Example::dump($user->settings);
Example::dump($user->getAttributes());

The $user->settings is:

LastDragon_ru\LaraASP\Serializer\Docs\Examples\Attribute\UserSettings {
  +perPage: 35
  +showSidebar: false
}

The $user->getAttributes() is:

[
  "settings" => "{"perPage":35,"showSidebar":false}",
]

Upgrading

Please follow Upgrade Guide.

Contributing

Please use the main repository to report issues, send pull requests, or ask questions.

Footnotes

1. https://laravel.com/docs/eloquent-mutators ↩