[B/C Break] Make the Annotations package optional in the builder API #1471

mbabker · 2023-02-05T18:29:04Z

Q	A
Bug fix?	no
New feature?	yes
Doc updated	no
BC breaks?	yes
Deprecations?	no
Tests pass?	no
Fixed tickets	N/A
License	MIT

The below are the changes needed to (in theory) make the Annotations package an optional thing (note that Annotations is hard required by the dev PHPCR ODM and PHPBench dependencies, so right now it's not possible to actually not install the package without playing with Composer)

mbabker · 2023-02-05T18:31:44Z

src/Builder/DriverFactoryInterface.php

@@ -9,5 +9,5 @@

 interface DriverFactoryInterface
 {
-    public function createDriver(array $metadataDirs, Reader $annotationReader): DriverInterface;
+    public function createDriver(array $metadataDirs, ?Reader $annotationReader = null): DriverInterface;


This one line is why there is a B/C break; widening the annotation reader argument to allow null causes compile errors in classes if they don't do the same.

I think it should not be a big issues. JMS Bundle seems to not using those classes, so it will affect only people who is using package without Bundle.

scyzoryck

Thanks for contribution!

scyzoryck · 2023-02-10T19:21:03Z

src/Builder/DriverFactoryInterface.php

@@ -9,5 +9,5 @@

 interface DriverFactoryInterface
 {
-    public function createDriver(array $metadataDirs, Reader $annotationReader): DriverInterface;
+    public function createDriver(array $metadataDirs, ?Reader $annotationReader = null): DriverInterface;


I think it should not be a big issues. JMS Bundle seems to not using those classes, so it will affect only people who is using package without Bundle.

scyzoryck · 2023-02-10T19:27:37Z

src/Builder/DefaultDriverFactory.php

        }

-        $driver = new AnnotationDriver($annotationReader, $this->propertyNamingStrategy, $this->typeParser);
+        if ($annotationReader) {


I wonder is we should modify ChainDriver too?

The instance at line 76 just outside this diff or something about the class itself?

There isn't a prepend method on the chain, so the implementation I have now ended up being the simplest one considering that when metadata paths are given, the factory pushes the YAML and XML drivers up in priority over the annotations driver (and the same goes for the default ordering in the bundle service definitions).

mbabker · 2023-08-01T13:22:30Z

Rebased, should be good to go now. I've also gone ahead and moved the Annotations package to require-dev.

The high CI fails are unrelated, if I had to take a guess it's related to the ORM 2.16 release as the CI from when #1494 was merged passed but both this and #1497 are now failing and the only difference in the dependency lists between those runs is that new release. If I had to guess, doctrine/orm#10547 is the root cause as the CI fails are changed IDs between objects, so the test probably needs an update to accommodate that change in behavior.

scyzoryck · 2023-10-30T07:17:03Z

Looks good for me. Personally I would release it after adding support for ORM 3.0. @goetas what do you think? Should we release it as a new major version?

kevinpapst · 2024-02-12T15:55:34Z

Bump: one of the last major packages that still has a hard dependency on doctrine/annotations.
Would be nice to get rid of it.
Anything I can do to help?

scyzoryck · 2024-02-24T14:12:10Z

I will release it on Monday morning. Thanks @mbabker for your work on this ticket!

Steveb-p · 2024-02-26T10:35:51Z

I think it should not be a big issues. JMS Bundle seems to not using those classes, so it will affect only people who is using package without Bundle.

@scyzoryck We are, in fact, using it with bundle and replacing the implementation with our own. And given that we have stable releases with this serializer as a dependency, we will have projects of our partners breaking.

scyzoryck · 2024-02-26T11:27:17Z

Hello!
Thanks for feedback! Yes, we are aware about potential affect on some users - but expect that BC break will affect only few of them - with easy fix and easy way to fix that before deploying to production. I'm sorry that your work will be affected too.

The package itself is not backed by any big companies - it is mainly voluntary work of few people with limited amount of free time. Unfortunately sometimes we need to make the some tough decisions to bring more exciting features and ensure long stability of the project. We always tries to deliver best value and features for others. If you found it useful for your project - it is always a good idea to support this project with contribution or funding :)

Best!

Steveb-p · 2024-02-26T11:42:43Z

@scyzoryck Understandable 😅 I kinda just wanted to note that it broke the software that we are giving to others. Given the broad experience spread in our little PHP world, it will take a little more or less for different developers.

I hope I didn't offend you, as my intent is only to note that this particular choice had some impact, nothing more :) I actually deleted a more playful part of the comment when writing, and text is rather bad at conveying intent :)

As for a potential resolution and/or fix for similar things happening in the future, you might consider going the same way as Symfony often does - by removing the argument from the interface altogether, and adding it as a comment. They do that often for things they deprecate.

Similarly maybe to how Symfony changed the argument order in EventDispatcherInterface a couple years ago:
https://github.com/nicolas-grekas/symfony/blob/75369dabb8af73b0d0ad7f206d85c08cf39117f8/src/Symfony/Component/EventDispatcher/EventDispatcherInterface.php#L32

Not ideal, but allows some flexibility without introducing major release, I guess?

scyzoryck · 2024-02-26T12:24:58Z

Thanks for suggestion! I know Symfony approach - however it do not work so well when removing required dependencies - so it would not be super useful in that case 😓

mbabker · 2024-02-26T13:59:38Z

I think just shipping this as is and calling it out as the B/C break it was without a major version bump was probably the best least disruptive option. Yeah, there was a chance it was going to impact someone, but there was no code change that wouldn't have.

Fully removing the argument would've introduced static analysis issues (passing more arguments than defined), commenting the argument is generally Symfony's signal that a new argument is being added to the signature, and Symfony has a history of treating moving dependencies from require to require-dev as soft breaks to avoid breaking apps relying on transient dependencies. I think if I would've made this PR a full "deprecate all annotations support" PR I'd have done the remove the argument from the signature bit, but as is this should be the last purposeful B/C issue until a 4.0 release comes together.

Steveb-p · 2024-02-26T15:16:25Z

Allow me to have a differing opinion on the matter, and respond. Note that those are my personal opinions and I fully value the approach you have taken (and work put into removing annotation dependency). I just don't agree with the notion of "there would always be some impact".

...Yeah, there was a chance it was going to impact someone, but there was no code change that wouldn't have.

With all due respect, I disagree with that. This could've been solved without breaking the implementations.

Thanks for suggestion! I know Symfony approach - however it do not work so well when removing required dependencies - so it would not be super useful in that case 😓

...commenting the argument is generally Symfony's signal that a new argument is being added to the signature...

The example I've given is exactly when a required argument was being removed from the interface, and arguments were swapping places (event name argument becoming an optional one).

...Fully removing the argument would've introduced static analysis issues (passing more arguments than defined)...

Yes, but no. That could've been solved by adding a stub file, where the newer interface declaration could be used to give static analysis correct information about expected class shape. This has been done in phpstan/phpstan-symfony as well, even specifically for the mentioned EventDispatcher changes.

...and Symfony has a history of treating moving dependencies from require to require-dev as soft breaks to avoid breaking apps relying on transient dependencies...

I agree that this is what often happens with Symfony, as those soft-breaks happened to us too. I would not have anything against annotation package removal, as this would indicate that a direct dependency was missing from one's library/project.

I'll be happy to provide you with static analysis compatible interface declaration (including the mentioned stub) if you're willing to take it into consideration.

ebitkov · 2024-02-27T11:00:20Z

Can someone please explain how I re-enable annotation support for the moment, as long as some packages still switching to attributes? The documentation wasn't really clear about it.

note: I'm initializing the serializer like SerializerBuilder::create()->build();

edit: As @Levivb suggested, requiring doctrine/annotations seems to do the trick.

Levivb · 2024-02-27T13:01:32Z

@ebitkov I'de suggest requiring doctrine/annotations explicitly yourself in your composer.json. That way, the JMS Serializer will automatically pick up the AnnotationReader

boesing · 2024-03-08T15:57:06Z

Any reason on why this was not a new major? I mean, this is not boesing/typed-arrays with 18k overall installs but jms/serializer which supposed to be THE serializer (along with the symfony one I guess) which has almost 100 million installs overall.

IMHO there is responsibility for packages like this one and just "yah lets merge and put it in the changelog" is not what I was expecting from a project this size.

Just wanted to drop this here, might be helpful for future releases...

goetas · 2024-04-04T19:31:23Z

As pointed out by @scyzoryck in #1471 (comment) this is a project run by volunteers working in their limited free time.

Releasing a new major version would have forced us to upgrade a few other projects such as fos rest, nelmio apidoc, Hateoas bundle... As you can see, it would force us to do a lot more work than what it seems.

I was aware that the changes were a possible BC break for some projects, but was the best trade off option I had in mind given the limited time we have.

I'm sorry that the bc break impacted some users, hopefully tests were able to catch the issue and no disruption in production happened.

mbabker commented Feb 5, 2023

View reviewed changes

scyzoryck reviewed Feb 10, 2023

View reviewed changes

scyzoryck approved these changes Apr 22, 2023

View reviewed changes

scyzoryck requested a review from goetas April 22, 2023 14:18

mbabker mentioned this pull request Jun 27, 2023

Don't return a metadata object unless there is explicit annotation or attribute configuration #1494

Merged

mbabker force-pushed the optional-annotations branch 2 times, most recently from dab3e9d to 50a8d22 Compare August 1, 2023 13:10

mbabker marked this pull request as ready for review August 1, 2023 13:14

mbabker mentioned this pull request Aug 3, 2023

Synchronize metadata driver setup with upstream changes schmittjoh/JMSSerializerBundle#933

Merged

mbabker force-pushed the optional-annotations branch 2 times, most recently from 77337a2 to 5244355 Compare August 3, 2023 14:46

scyzoryck mentioned this pull request Aug 30, 2023

The dependency on doctrine/annotations should become an optional one #1511

Closed

scyzoryck mentioned this pull request Oct 11, 2023

ORM 3.0 Compat #1516

Closed

mbabker force-pushed the optional-annotations branch from 5244355 to f85f9d8 Compare October 17, 2023 19:38

mbabker mentioned this pull request Oct 17, 2023

Inject an attribute metadata driver into the DoctrineDriver when testing #1520

Merged

mbabker force-pushed the optional-annotations branch from f85f9d8 to 38559b9 Compare October 23, 2023 13:22

mbabker force-pushed the optional-annotations branch from 38559b9 to 2ff672d Compare December 22, 2023 16:40

mbabker force-pushed the optional-annotations branch from 2ff672d to 1892456 Compare January 4, 2024 15:57

scyzoryck force-pushed the optional-annotations branch from 1892456 to 2ccf709 Compare February 18, 2024 10:46

Make the Annotations package optional in the builder API

c7e6eb1

scyzoryck force-pushed the optional-annotations branch from 2ccf709 to c7e6eb1 Compare February 18, 2024 10:49

goetas approved these changes Feb 19, 2024

View reviewed changes

scyzoryck merged commit bf11053 into schmittjoh:master Feb 24, 2024
17 of 18 checks passed

mbabker deleted the optional-annotations branch February 24, 2024 17:10

fredericgboutin-yapla mentioned this pull request Feb 27, 2024

Change to optional Doctrine/Annotations package introduces a breaking change #1537

Closed

ebitkov mentioned this pull request Feb 27, 2024

Switch to PHP Attributes ujamii/openimmo#83

Open

mbaschnitzi mentioned this pull request Feb 29, 2024

Missing dependency doctrine/annotations since jms/serializer:3.30.0 easybill/zugferd-php#58

Closed

W0rma mentioned this pull request Oct 15, 2024

Make dependency doctrine/annotations optional willdurand/Hateoas#333

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[B/C Break] Make the Annotations package optional in the builder API #1471

[B/C Break] Make the Annotations package optional in the builder API #1471

mbabker commented Feb 5, 2023

mbabker Feb 5, 2023

scyzoryck Feb 10, 2023

scyzoryck left a comment

scyzoryck Feb 10, 2023

scyzoryck Feb 10, 2023

mbabker Feb 10, 2023

mbabker commented Aug 1, 2023

scyzoryck commented Oct 30, 2023

kevinpapst commented Feb 12, 2024

scyzoryck commented Feb 24, 2024 •

edited

Loading

Steveb-p commented Feb 26, 2024

scyzoryck commented Feb 26, 2024

Steveb-p commented Feb 26, 2024 •

edited

Loading

scyzoryck commented Feb 26, 2024

mbabker commented Feb 26, 2024

Steveb-p commented Feb 26, 2024 •

edited

Loading

ebitkov commented Feb 27, 2024 •

edited

Loading

Levivb commented Feb 27, 2024

boesing commented Mar 8, 2024

goetas commented Apr 4, 2024

[B/C Break] Make the Annotations package optional in the builder API #1471

[B/C Break] Make the Annotations package optional in the builder API #1471

Conversation

mbabker commented Feb 5, 2023

mbabker Feb 5, 2023

Choose a reason for hiding this comment

scyzoryck Feb 10, 2023

Choose a reason for hiding this comment

scyzoryck left a comment

Choose a reason for hiding this comment

scyzoryck Feb 10, 2023

Choose a reason for hiding this comment

scyzoryck Feb 10, 2023

Choose a reason for hiding this comment

mbabker Feb 10, 2023

Choose a reason for hiding this comment

mbabker commented Aug 1, 2023

scyzoryck commented Oct 30, 2023

kevinpapst commented Feb 12, 2024

scyzoryck commented Feb 24, 2024 • edited Loading

Steveb-p commented Feb 26, 2024

scyzoryck commented Feb 26, 2024

Steveb-p commented Feb 26, 2024 • edited Loading

scyzoryck commented Feb 26, 2024

mbabker commented Feb 26, 2024

Steveb-p commented Feb 26, 2024 • edited Loading

ebitkov commented Feb 27, 2024 • edited Loading

Levivb commented Feb 27, 2024

boesing commented Mar 8, 2024

goetas commented Apr 4, 2024

scyzoryck commented Feb 24, 2024 •

edited

Loading

Steveb-p commented Feb 26, 2024 •

edited

Loading

Steveb-p commented Feb 26, 2024 •

edited

Loading

ebitkov commented Feb 27, 2024 •

edited

Loading