NelmioApiDocBundle v5 overview

[DjordyKoert]

I think we should start preparing for NelmioApiDocBundle v5 and move forward with this bundle.

PHP 8.1+

First of all I would like to remove support for PHP 7. PHP 7 has been EOL for quite some time now (PHP 7.4 active support stopped 2 years ago https://endoflife.date/php) and is currently preventing us from using new PHP 8 features (typed properties, native attributes, property promotion, union types).

Additionally I would like to start using PHP 8.1 as a minimum instead of PHP 8.0 because:

1. Enums (could replace https://github.com/nelmio/NelmioApiDocBundle/blob/daadb0b567c637d737f58fd25da0b4db2321560d/Render/Html/AssetsMode.php)
2. new in initializers https://stitcher.io/blog/new-in-php-81#new-in-initializers-rfc
   • Simplifies some constructors even more by using new as default parameters

     NelmioApiDocBundle/ApiDocGenerator.php

     Line 69 in daadb0b

     $this->generator = $generator ?? new Generator($this->logger);

3. readonly properties
   • Simplifies some classes by replacing getters with a public readonly property

     NelmioApiDocBundle/Model/Model.php

     Line 39 in daadb0b

     public function getType()

Planned changes:

• Rewrite every class for constructor property promotion
• Add proper types for every class property

Static analysis

PHP 8 is also a perfect time to start using static analysis tools. That's why I would like to introduce (PHPStan) to this project. This would also include some refactoring here and there to remove PHPStan's detected problems.

Symfony version bump to 6.4+ Drop support for Symfony 6.0, 6.1, 6.2 & 6.3

Symfony 6.0, 6.1, 6.2 & 6.3 have already stopped receiving bug fixes & security updates which is why a bump to Symfony 6.4 would be ideal, this version also closely align with our new minimum PHP version support.
Additionaly let's keep supporting Symfony 5.4 for now. Support for it should be dropped in a different minor release. Preferably we wait until after November 2024 (end of bug fixes for Symfony 5.4 https://symfony.com/releases/5.4).

General refactoring

• Remove current deprecations
• Add proper return types to methods (including void)

  NelmioApiDocBundle/PropertyDescriber/PropertyDescriberInterface.php

  Line 25 in daadb0b

  public function describe(array $types, Schema $property, array $groups = null /* , ?Schema $schema = null */ /* , array $context = [] */);

• Add inline (union)types to methods where it is currently missing (this should also be detected by PHPStan)
• Mark classes as final
  • All classes implementing PropertyDescriberInterface (prefer class decoration)
• Drop support for sensio/framework-extra-bundle? (unmaintained & all annotations are available from Symfony 6.2 onward)

[DjordyKoert]

Try and and see if https://github.com/rectorphp/rector is a good solution for easy refactoring

[mathroc]

It could make upgrading harder, but it could be the opportunity to drop support for annotations. It seems to be that having both attributes & annotations adds a lot of complexity. Especially when the 2 are mixed

[cjgordon]

Just thought I would add this here.

As mentioned be @mathroc if a project switches to Attributes from Annotations (which I think makes sense) we would need to provide an upgrade path for going from annotations to attributes to bring most of the install base with us.

Fortunately rectorphp gets us there... nearly. See:
zircote/swagger-php#1047

I have used this method with only one issue I had to manually fix which is this issue with nested annotations:
zircote/swagger-php#1047 (comment)

Will see what I can do to resolve this as I would like to migrate my own project.

[DjordyKoert]

Reopening this issue because I encountered various issues in the codebase while attempting to bump Symfony minimum to 6.4 in #2335.

Most of these issues were related to updating the tests to prefer attributes over annotations.

In the end I strongly believe that in order for this bundle to be ready for the future we will have to move to a major v5 by doing the changes mentioned in this issue.