xp-forge/marshalling

Marshalling

Maintainers

Details

github.com/xp-forge/marshalling

Homepage

Source

Issues

Installs: 44 591

Dependents: 5

Suggesters: 0

Security: 0

Stars: 0

Watchers: 3

Forks: 0

Open Issues: 1

v2.3.0 2024-11-01 12:16 UTC

Requires

Requires (Dev)

BSD-3-Clause b0a66c597947cae0d1abad934b66fbf75fa9030f

modulexp

This package is auto-updated.

Last update: 2024-12-01 12:30:14 UTC

README

Build status on GitHub XP Framework Module BSD Licence Requires PHP 7.0+ Supports PHP 8.0+ Latest Stable Version

Marshalling converts objects to maps and vice versa.

Example

All primitives, arrays and maps thereof are yielded as-is:

use util\data\Marshalling;

$m= new Marshalling();
$m->marshal('Test');            // "Test"
$m->marshal([1, 2, 3]);         // [1, 2, 3]
$m->marshal(['admin' => true]); // ["admin" => true]

Value objects are marshalled using field => getter lookups; supporting both method named for field and getField conventions.

use util\data\Marshalling;

class Person {
  private $name, $age;

  public function __construct(string $name, int $age) {
    $this->name= $name;
    $this->age= $age;
  }

  public function name(): string { return $this->name; }
  public function age(): int { return $this->age; }
}

$m= new Marshalling();
$m->marshal(new Person('...', 42)); // ["name" => "...", "age" => 42]

When unmarshalling from maps, pass the type as second parameter. Objects are created without invoking the constructor, and by either setting the fields directly or by using the setField convention.

use util\data\Marshalling;

$m= new Marshalling();
$person= $m->unmarshal(['name' => '...', 'age' => 42], Person::class);

Types from the util package are handled by default:

use util\data\Marshalling;
use util\{Date, Bytes, Money, UUID};

$m= new Marshalling();
$m->marshal(Date::now());                   // "2018-08-29T10:40:49+0200" (ISO 8601)
$m->marshal(new Bytes("\x50\x4b\x03\x04")); // "UEsDBA==" (base64)
$m->marshal(new Money(12.99, $currency));   // ["amount" => 12.99, "currency" => "EUR"]
$m->marshal(UUID::randomUUID());            // ["value" => "a2b15f7b-f6e0-45fa-9d7f-703fda05d4ac"]

Custom logic

To supply a function for marshalling and unmarshalling, use mapping() and resolving():

use util\data\Marshalling;

class User {
  public function __construct(public int $id, public string $name) { }
}

$marshalling= (new Marshalling())
  ->mapping(User::class, fn($user) => $user->id)
  ->resolving(User::class, fn($value) => new User($value, posix_getpwuid($value)['name'])
;
$value= $marshalling->marshal(new User(0, 'root'));
// 0

$user= $marshalling->unmarshal($value, User::class);
// User(id: 0, name: 'root')

See also