Make the payload context an enum and pass it on to nested objects

[loevgaard]

Summary

One of the 2.0 cleanups that was listed in #16 and then never done.

The payload context was a string with two constants on Parameters. With a string, a typo such as getPayload('brwoser') does not fail. It silently returns the server payload, IP address, user agent, fbc and fbp included, and FbqGenerator::generateInit() prints that payload into the page.

• New enum Setono\MetaConversionsApi\Event\PayloadContext with the cases Server (the default) and Browser.
• Parameters::getPayload() and getMapping() take it instead of a string, in Event, User, Custom and Content.
• Parameters::PAYLOAD_CONTEXT_SERVER and PAYLOAD_CONTEXT_BROWSER are removed.

// before
$event->userData->getPayload(Parameters::PAYLOAD_CONTEXT_BROWSER);

// after
$event->userData->getPayload(PayloadContext::Browser);

A fix on the same lines

The context was not passed on to nested objects: getPayload() called $value->getPayload() on nested Parameters without the argument. So $event->getPayload(BROWSER) still serialized the user data in the server context. It never showed, because FbqGenerator asks the user data and the custom data directly. The context now travels down, both for directly nested objects and for lists of them.

Backwards compatibility

Intentional breaks, documented in a new section of UPGRADE-2.0.md:

• Callers passing the constants switch to the enum.
• A subclass of Event that overrides getMapping(string $context) gets a signature mismatch and has to change it to getMapping(PayloadContext $context). The README encourages subclassing Event; a subclass that only overrides the constructor is not affected.

The Roave BC job is red by design.

Docs

README (the browser-side snippet), CLAUDE.md (the Parameters and payload context paragraphs), UPGRADE-2.0.md.

Test plan

• ParametersTest (new), with a small context-aware fixture: the server context is the default, and the context reaches a nested object, a doubly nested object and every item of a list
• EventTest::it_passes_the_context_on_to_the_user_data — the browser payload of an event contains only the hashed email of its user, the server payload contains the IP address, user agent, fbc and fbp as before
• FbqGeneratorTest switched to the enum, output unchanged
• 166 tests, 100 % line coverage; PHPStan (level max), ECS, dependency analyser green; Infection MSI 95 % / covered 95 %, no new escaped mutants

Not in this PR

The other two cleanups from the same list are still open: Fbp::$randomNumber being a public, mutable property, and native types for User::$fbc / $fbp and Fb::withCreationTime().