Attributes in documentation

[carlos-granados]

Currently there is no mention at all about PHP Attributes in the documentation but you should be able to use them everywhere that Behat uses annotations. We should include documentation about Attributes. There are two options:

• Keep the bulk of the documentation using annotations and just make sure that we mention in some places that attributes can be used instead of annotations with examples
• Move all the documentation to use attributes and just mention that you can use annotations instead with examples

Given the global trend in the PHP world to use attributes everywhere, I lean towards the second option but would like to hear the opinion of others.

As a reference, PHPUnit documentation now uses attributes everywhere and just provides a section on annotations

[stof]

As a reference, PHPUnit documentation now uses attributes everywhere and just provides a section on annotations

The difference here is that PHPUnit 11 has deprecated annotations and PHPUnit 12 will drop them.

However, I'm in favor of using annotations by default in examples.

[carlos-granados]

As a reference, PHPUnit documentation now uses attributes everywhere and just provides a section on annotations

The difference here is that PHPUnit 11 has deprecated annotations and PHPUnit 12 will drop them.

However, I'm in favor of using annotations by default in examples.

annotations or attributes?

[stof]

Sorry, I meant using attributes by default, not annotations.

[acoulton]

👍 to updating the docs to use attributes.

I'd also be in favour of eventually at least deprecating the annotations (maybe with an opt-in standalone package to parse them into attributes at runtime, or a tool/script/Rector to convert existing feature files). In a future major, obviously.

[carlos-granados]

Before we can work on this I believe there should be an easy way to update all existing annotations to attributes in a project. I tried to use the AnnotationToAttributeRector Rector rule but found out that it did not work as required (it discarded the text of the step) so I have create a PR to fix this, hopefully this will be merged into Rector and released in the next release
rectorphp/rector-src#6468

[carlos-granados]

My Rector pull request has been merged, so this should be part of the Rector 2.0 release that should happen soon 🎉

[carlos-granados]

Created a draft PR with these changes #178 comments and reviews welcome!