Add 2.0 upgrade guide

[DavidBadura]

Adds UPGRADE-2.0.md in the repository root, documenting every breaking change between 1.24.x and 2.0.x with before/after migration steps.

Covered areas:

• Hydrator: MetadataHydrator (and its static create()) removed in favor of StackHydrator / StackHydratorBuilder; defaultLazy moved to enableDefaultLazy(); HydratorWithContext merged into Hydrator, OBJECT_TO_POPULATE now on Hydrator.
• Normalizer: normalize/denormalize now require an array $context parameter; NormalizerWithContext removed; ReflectionTypeAwareNormalizer replaced by TypeAwareNormalizer (handleType(Type)).
• Lifecycle Hooks: attributes moved to Extension\Lifecycle\Attribute, hooks must now be static and receive $context, enabled via LifecycleExtension.
• Events: the PreHydrate/PostExtract events and the eventDispatcher constructor argument are gone; global listeners are migrated to a custom Middleware registered via addMiddleware().
• Cryptography: namespace moved to Extension\Cryptography, setup via CryptographyExtension + BaseCryptographer::createWithOpenssl(), PersonalData renamed to SensitiveData, DataSubjectId moved and now supports named subjects, changed CipherKeyStore interface.
• Dependencies: symfony/event-dispatcher is no longer required.

[github-actions]

Hello 👋

here is the most recent benchmark result:

HydratorWithLazyBench
=====================

+------------------------------------------+--------------------+--------------------+-----------------+------------+
|                                          | time (kde mode)                         | memory                       |
+------------------------------------------+--------------------+--------------------+-----------------+------------+
| subject                                  | Tag: <current>     | Tag: base          | Tag: <current>  | Tag: base  |
+------------------------------------------+--------------------+--------------------+-----------------+------------+
| benchHydrate1Object ()                   | 1.000μs (±0.00%)   | 0.800μs (±0.00%)   | 2.813mb         | 3.250mb    |
| benchHydrate1ObjectTriggerInit ()        | 4.200μs (±0.00%)   | 4.200μs (±0.00%)   | 2.813mb         | 3.250mb    |
| benchHydrate1000Objects ()               | 433.000μs (±0.00%) | 435.667μs (±0.00%) | 2.813mb         | 3.267mb    |
| benchHydrate1000ObjectsTriggerInit ()    | 3.236ms (±0.00%)   | 3.295ms (±0.00%)   | 2.845mb         | 3.306mb    |
| benchHydrate1000000Objects ()            | 295.233ms (±0.00%) | 291.323ms (±0.00%) | 2.813mb         | 3.267mb    |
| benchHydrate1000000ObjectsTriggerInit () | 2.086s (±0.00%)    | 2.071s (±0.00%)    | 2.845mb         | 2.845mb    |
+------------------------------------------+--------------------+--------------------+-----------------+------------+

StackHydratorWithCryptographyBench
==================================

+-------------------------------+-------------------+-------------------+-----------------+------------+
|                               | time (kde mode)                       | memory                       |
+-------------------------------+-------------------+-------------------+-----------------+------------+
| subject                       | Tag: <current>    | Tag: base         | Tag: <current>  | Tag: base  |
+-------------------------------+-------------------+-------------------+-----------------+------------+
| benchHydrate1Object ()        | 7.200μs (±0.00%)  | 7.600μs (±0.00%)  | 2.791mb         | 2.791mb    |
| benchExtract1Object ()        | 16.400μs (±0.00%) | 16.800μs (±0.00%) | 2.791mb         | 2.791mb    |
| benchHydrate1000Objects ()    | 4.196ms (±0.00%)  | 4.181ms (±0.00%)  | 3.085mb         | 3.085mb    |
| benchExtract1000Objects ()    | 8.973ms (±0.00%)  | 9.008ms (±0.00%)  | 3.197mb         | 3.197mb    |
| benchHydrate1000000Objects () | 2.429s (±0.00%)   | 2.440s (±0.00%)   | 3.085mb         | 3.085mb    |
| benchExtract1000000Objects () | 6.793s (±0.00%)   | 6.784s (±0.00%)   | 3.197mb         | 3.197mb    |
+-------------------------------+-------------------+-------------------+-----------------+------------+

HydratorWithCryptographyBench
=============================

+-------------------------------+-------------------+-------------------+-----------------+------------+
|                               | time (kde mode)                       | memory                       |
+-------------------------------+-------------------+-------------------+-----------------+------------+
| subject                       | Tag: <current>    | Tag: base         | Tag: <current>  | Tag: base  |
+-------------------------------+-------------------+-------------------+-----------------+------------+
| benchHydrate1Object ()        | 8.000μs (±0.00%)  | 7.400μs (±0.00%)  | 2.791mb         | 2.791mb    |
| benchExtract1Object ()        | 16.600μs (±0.00%) | 18.000μs (±0.00%) | 2.791mb         | 2.791mb    |
| benchHydrate1000Objects ()    | 4.205ms (±0.00%)  | 4.199ms (±0.00%)  | 3.085mb         | 3.085mb    |
| benchExtract1000Objects ()    | 9.288ms (±0.00%)  | 9.039ms (±0.00%)  | 3.197mb         | 3.197mb    |
| benchHydrate1000000Objects () | 2.393s (±0.00%)   | 2.422s (±0.00%)   | 3.085mb         | 3.085mb    |
| benchExtract1000000Objects () | 6.759s (±0.00%)   | 6.812s (±0.00%)   | 3.197mb         | 3.197mb    |
+-------------------------------+-------------------+-------------------+-----------------+------------+

StackHydratorBench
==================

+-------------------------------+------------------+------------------+-----------------+------------+
|                               | time (kde mode)                     | memory                       |
+-------------------------------+------------------+------------------+-----------------+------------+
| subject                       | Tag: <current>   | Tag: base        | Tag: <current>  | Tag: base  |
+-------------------------------+------------------+------------------+-----------------+------------+
| benchHydrate1Object ()        | 3.600μs (±0.00%) | 3.400μs (±0.00%) | 2.813mb         | 2.813mb    |
| benchExtract1Object ()        | 4.000μs (±0.00%) | 4.000μs (±0.00%) | 2.813mb         | 2.813mb    |
| benchHydrate1000Objects ()    | 2.478ms (±0.00%) | 2.474ms (±0.00%) | 2.932mb         | 2.932mb    |
| benchExtract1000Objects ()    | 2.226ms (±0.00%) | 2.251ms (±0.00%) | 2.860mb         | 2.860mb    |
| benchHydrate1000000Objects () | 1.408s (±0.00%)  | 1.418s (±0.00%)  | 2.932mb         | 2.932mb    |
| benchExtract1000000Objects () | 1.405s (±0.00%)  | 1.440s (±0.00%)  | 2.860mb         | 2.860mb    |
+-------------------------------+------------------+------------------+-----------------+------------+

HydratorBench
=============

+-------------------------------+------------------+------------------+-----------------+------------+
|                               | time (kde mode)                     | memory                       |
+-------------------------------+------------------+------------------+-----------------+------------+
| subject                       | Tag: <current>   | Tag: base        | Tag: <current>  | Tag: base  |
+-------------------------------+------------------+------------------+-----------------+------------+
| benchHydrate1Object ()        | 3.200μs (±0.00%) | 3.800μs (±0.00%) | 2.813mb         | 2.813mb    |
| benchExtract1Object ()        | 4.000μs (±0.00%) | 3.600μs (±0.00%) | 2.813mb         | 2.813mb    |
| benchHydrate1000Objects ()    | 2.487ms (±0.00%) | 2.469ms (±0.00%) | 2.932mb         | 2.932mb    |
| benchExtract1000Objects ()    | 2.232ms (±0.00%) | 2.263ms (±0.00%) | 2.860mb         | 2.860mb    |
| benchHydrate1000000Objects () | 1.404s (±0.00%)  | 1.418s (±0.00%)  | 2.932mb         | 2.932mb    |
| benchExtract1000000Objects () | 1.443s (±0.00%)  | 1.442s (±0.00%)  | 2.860mb         | 2.860mb    |
+-------------------------------+------------------+------------------+-----------------+------------+

This comment gets update everytime a new commit comes in!