libMarshal
A small marshalling library used to encode/decode data from classes
How to use?
Using the library with objects is extremely simple.
MarshalTrait
This trait is the logic behind the marshaling/unmarshaling of objects. Like any other trait, you can use it through use MarshalTrait. Furthermore, this trait gives you access to two methods:
- A class method:
marshal()- Marshals the data into an array - A static method:
unmarshal(array $data, bool $strict)- Unmarshals the data back into an object
Field
This attribute is one of the largest parts of the library as it is what determines what MarshalTrait marshals/unmarshals. If a property is not annotated with this attribute, it will not be handled.
The Field attribute accepts one argument: name. If no name is specified, MarshalTrait will use the property name as the name to marshal/unmarshal with.
As examples:
#[Field]
public string $name; // When encoded, it will output to ["name" => x]
#[Field(name: "Specific Name")]
public string $specificName; // When encoded, it will output to ["Specific Name" => x]
public string $hiddenName; // This field will not be included in either marshalling methods.
Using Objects in properties
The only prerequisite behind marshalling/unmarshalling an embedded object is to have the class set up with the MarshalTrait and Fields. Here is an example on how you would use that:
class Range {
use MarshalTrait;
#[Field]
public int $min = 0;
#[Field]
public int $max = 10;
#[Field]
public int $default = 0;
}
class Options {
use MarshalTrait;
#[Field]
public string $username = "TestUserName";
#[Field]
public Range $range;
}
Example
Here is a full example:
class User {
use MarshalTrait;
#[Field(name: "first-name")]
public string $firstName;
#[Field(name: "last-name")]
public string $lastName;
#[Field]
public int $age;
#[Field]
public string $email;
}
// NOTE: This uses promoted properties to make it easier to construct.
// You can learn more about this below.
// Marshalling
$user = new User(firstName: "John", lastName: "Doe", age: 30, email: "[email protected]");
$data = $user->marshal(); // ["first-name" => "John", "last-name" => "Doe", "age" => 30, "email" => "[email protected]"]
$data["first-name"] = "Jane"; // Changing the first name
$data["email"] = "[email protected]"; // Changing the email
// Unmarshalling
$user = User::unmarshal($data); // User(firstName: "Jane", lastName: "Doe", age: 30, email: "[email protected]")
Limitations
As the library stands, the constructor is never called when creating an object. This is intentional as argument ordering may have unintended side effects. If you want to be able to pass in parameters to an object, you can take advantage of PHP's promoted properties like so:
class User {
use MarshalTrait;
public function __construct(
#[Field(name: "first-name")]
public string $firstName,
#[Field(name: "last-name")]
public string $lastName,
#[Field]
public int $age,
#[Field]
public string $email
) {}
}
This will allow you to create the objects through a constructor as usual while also declaring the properties.
Roadmap
At the moment, there are a few improvements that can be/or are being worked on. Here is a list of some of those improvements:
- Add a limit to recursive objects when marshalling/unmarshalling (50?)
- Cache properties for performance benefits
Issues
Any issues/suggestion can be reported here.
9 Oct 18, 2022
69 Dec 18, 2022
0 Jan 10, 2022
3 Jan 3, 2023
6 Dec 31, 2022
3 Nov 10, 2021
2k Dec 22, 2022
341 Dec 25, 2022
530 Dec 27, 2022
2 Oct 9, 2022
5 Apr 17, 2022
3 Nov 25, 2021
560 Nov 20, 2022
134 Dec 26, 2022
16 Jun 7, 2022
9 Dec 31, 2022
5 Jun 16, 2022
4.9k Dec 30, 2022