Add/require hard-coded key/value(s)

[Nadyita]

Been enjoying your package for a very long time now, and gradually replacing some custom components I wrote with this generic one.
A very common use case that I have is packages from protocols, where each package has a fixed {"type": <value>} attribute that determines the type of package. Deserializing is not an issue, but because that type is not a property in my data object (it's a constant after all), and the data objects tend to have public accessor functions, I'm forced to set serialization of public methods tofalse.
What I would love would be a way to annotate a class that it should always add a key/value pair when serializing the object, but also requiring this key/value pair when hydrating. Something like

#[FixedDefinition(key: 'type', value: 'get-users')]
class GetUsersCommand {
    /** @param list<string> $users */
    public function __construct(
        public readonly array $users
    ) {
    }
}

This should always add {"type": "get-users"} when serializing, and also require this key/value-pair when hydrating. So far, I'm not seeing an easy way to do this with the given codebase. Would you be open to a PR implementing this, or is this too much a niche thing?

[frankdejonge]

Interesting case, it's sort of like a discriminative union. From a hydration point of view, could you show an example?

[Nadyita]

Sure. Let's say we have two classes:

#[FixedDefinition(key: 'type', value: 'get-users')]
class GetUsersCommand {
    /** @param list<string> $users */
    public function __construct(
        public readonly array $users
    ) {
    }
}

#[FixedDefinition(key: 'type', value: 'del-users')]
class DelUsersCommand {
    /** @param list<string> $users */
    public function __construct(
        public readonly array $users
    ) {
    }
}

And now we receive this package:

{
    "type": "get-users",
     "users": [
         "UserOne",
         "UserTwo",
         "UserThree"
    ]
}

Now a successful hydration could look like this:

$data = json_decode($json, true));
$mapper = new ObjectMapperUsingReflection();
$command = $mapper->hydrateObject(GetUsersCommand::class, $data);
// this is now equal to new GetUsersCommand(users: ['UserOne', 'UserTwo', 'UserThree'])

This should throw an exception:

$data = json_decode($json, true));
$mapper = new ObjectMapperUsingReflection();
$command = $mapper->hydrateObject(DelUsersCommand::class, $data);
// throws an exception about an invalid expected type

The issue I'm facing is that type is an artificial property that's added to the JSON, so that data consumers know which layout to expect, but that's usually not a property you'd keep in PHP, because the class's name itself takes on that role. It's also a static property, tied to the class itself and not the instance. Originally I thought about solving it with public static string $type = 'get-users';, but that has 2 problems:

1. You cannot mark it readonly if you assign a value in the class definition, so every other code later on can just change it
2. You cannot serialize static properties with your package.