morrislaptop/laravel-popo-caster

Automatically cast JSON columns to rich PHP objects in Laravel using Symfony's Serializer

v0.12.0 2024-08-10 08:56 UTC

Requires

• php: ^8.0
• illuminate/contracts: ^8.67|^9.0|^10.0|^11.0
• morrislaptop/symfony-custom-normalizers: ^0.4|^0.5
• symfony/property-access: ^5.2|^6.0|^7.0
• symfony/property-info: ^5.2|^6.0|^7.0
• symfony/serializer: ^5.2|^6.0|^7.0

Requires (Dev)

• brick/money: ^0.5.1|^0.8
• friendsofphp/php-cs-fixer: ^3.8
• mockery/mockery: ^1.4
• orchestra/testbench: ^7.9|^8.0|^9.0
• phpunit/phpunit: ^9.3
• vimeo/psalm: ^4.4|^5.6

MIT

• Craig Morris

• morrislaptop
• laravel-popo-caster

README

Laravel is awesome. Spatie's data transfer object package for PHP is awesome. But they don't cast objects like dates to DateTimes and collections are a bit of pain. Plain Old PHP Objects (POPOs) are a bit better in that regard.

Have you ever wanted to cast your JSON columns to a value object?

This package gives you 2 caster classes:

• Serializer which serializes your value object and stores it in a single JSON field
• Normalizer which normalizes your value object and stores the properties as fields on your model

Under the hood it implements Laravel's Castable interface with a Laravel custom cast that handles serializing between the object (or a compatible array) and your JSON database column. It uses Symfony's Serializer to do this.

This package is inspired by Laravel Castable Data Transfer Object!

Installation

You can install the package via composer:

composer require morrislaptop/laravel-popo-caster

Serializer Usage

1. Create your POPO

namespace App\Values;

class Address
{
    public function __construct(
        public string $street,
        public string $suburb,
        public string $state,
        public Carbon $moved_at,
    ) {
    }
}

2. Configure your Eloquent attribute to cast to it:

Note that this should be a jsonb or json column in your database schema. Objects and arrays are both supported.

namespace App\Models;

use App\Values\Address;
use Illuminate\Database\Eloquent\Model;
use Morrislaptop\LaravelPopoCaster\Serializer;

/**
 * @property Address $address
 */
class User extends Model
{
    protected $casts = [
        'address' => Serializer::class . ':' . Address::class,
        'prev_addresses' => Serializer::class . ':' . Address::class . '[]',
    ];
}

And that's it! You can now pass either an instance of your Address class, or even just an array with a compatible structure. It will automatically be cast between your class and JSON for storage and the data will be validated on the way in and out.

$user = User::create([
    // ...
    'address' => [
        'street' => '1640 Riverside Drive',
        'suburb' => 'Hill Valley',
        'state' => 'California',
        'moved_at' => now(),
    ],
    'addresses' => [
        [
            'street' => '42 Wallaby Way',
            'suburb' => 'Sydney',
            'state' => 'NSW',
            'moved_at' => '2020-01-14T00:00:00Z',
        ],
    ]
])

$residents = User::where('address->suburb', 'Hill Valley')->get();

But the best part is that you can decorate your class with domain-specific methods to turn it into a powerful value object.

$user->address->toMapUrl();

$user->address->getCoordinates();

$user->address->getPostageCost($sender);

$user->address->calculateDistance($otherUser->address);

$user->address->moved_at->diffForHumans();

echo (string) $user->address;

Normalizer Usage

1. Create your POPO

namespace App\Values;

class Money
{
    public function __construct(
        public int $amount,
        public string $currency,
    ) {
    }
}

2. Configure your Eloquent attribute to cast to it:

Note that the properties of your value object should be columns in your database schema.

namespace App\Models;

use App\Values\Money;
use Illuminate\Database\Eloquent\Model;
use Morrislaptop\LaravelPopoCaster\Normalizer;

/**
 * @property Money $money
 */
class User extends Model
{
    protected $casts = [
        'money' => Normalizer::class . ':' . Money::class,
    ];
}

And that's it! You can now pass either an instance of your Money class, or set the individual properties on the model. It will automatically be cast between your class and properties for storage and the data will be validated on the way in and out.

$user = User::create([
    // ...
    'amount' => 1000,
    'curency' => 'AUD',
]);

$user = User::create([
    // ...
    'money' => new Money(1000, 'AUD'),
])

But the best part is that you can decorate your class with domain-specific methods to turn it into a powerful value object.

$user->money->convertTo('USD');

Plug

Want an easy way to mock or have factories for your POPOs? Check out morrislaptop/popo-factory

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Craig Morris
• All Contributors

License

The MIT License (MIT). Please see License File for more information.