[vinayak-iyer-paysera]

Summary

This change makes the bundle install and run on Symfony 7.4, keeps 3.4 to 6.4 working as they do today, and ships as
2.0.0. It needed paysera/lib-dependency-injection 1.5.0, lib-pagination 1.6.0 and lib-normalization-bundle 1.4.0, all
of which are now released.

Why

• Every Symfony constraint stops at ^6.0, and Symfony 7 requires getConfigTreeBuilder(): TreeBuilder.
• Seven components the code uses are missing from composer.json, so a PHP 8.3 install can mix 7.4 components into 6.4.
• Symfony 7.1 and 7.3 rewrote Request::getPreferredLanguage(). Since then, de-DE (from 7.1) and de (from 7.3) lose
  to the listener's 'default' placeholder.
• In three setups Symfony passes no annotation reader to the route loader: Symfony 7, Symfony 6.4 with
  framework.annotations disabled, and FrameworkBundle 6.4 with symfony/routing 7. There the loader has no way to read
  the bundle's docblock options.

Changes

• composer.json.

  • ^7.4 on framework-bundle, http-kernel, security-bundle, validator and yaml.
  • ^7.0 on config, dependency-injection, http-foundation, property-access, routing and security-core,
    which FrameworkBundle and SecurityBundle 6.4 accept at 7.x.
  • The seven missing components are now required.
  • psr/log 3.
  • doctrine/annotations ^1.14.4 || ^2.0.2. Earlier releases never refuse opcache.save_comments=0, and read stripped
    docblocks as empty.
  • In require-dev: ORM ^2.6.3, and DoctrineBundle ^2.5, because 2.4 does not boot on Symfony 6.0.

• Signatures. getConfigTreeBuilder(): TreeBuilder, and Configuration is marked @final. load() gets only
  @return void. 11 parameters become ?Type $x = null.

• LocaleListener. It picks the locale with Request::getPreferredLanguage(), as 1.x did. The placeholder is now
  '' instead of 'default', so no language tag can match it. As a result, an item that Symfony reads as the language
  default (default, i-default) now gives the configured locale that follows it. An item read as an empty language
  ("", i-, -de on 3.4–7.0; "", 0 on 7.1) now keeps the default locale. The CHANGELOG lists both under
  Changed. Configured locales are compared as strings.

• docblock_annotations option, false by default. It applies where Symfony passes no annotation reader, from
  Symfony 6.4.

  • false reads only the attributes.
  • true reads the docblocks of #[Route] actions and of their classes with Doctrine's AnnotationReader, and fails
    where that reader fails: on a tag that is neither imported nor ignored, and when OPcache is loaded with
    save_comments=0.
  • Where Symfony passes its reader, the bundle uses it as in 1.x, whatever the option says.

• Mixed routes. From Symfony 6.4, wherever the bundle reads docblock annotations, a route configured with both
  docblock annotations and attributes that implement the bundle's interfaces, on the action or on its class, fails to
  load with a ConfigurationException. In 1.x, the attributes silently replaced the docblock options.

• Services. PayseraApiExtension::load() registers them, and the six XML files under Resources/config are removed.
  Definitions, aliases and parameters match the XML ones on Symfony 3.4, 4.4, 5.4, 6.0, 6.4 and 7.4, with two
  exceptions:

  • ErrorBuilder's class name lost its leading backslash;
  • on 7.4.0, the internal .container.known_envs parameter that XmlFileLoader set is gone.

  The extension extends Symfony\Component\DependencyInjection\Extension\Extension, not HttpKernel's Extension, which
  is internal since Symfony 7.1.

• Tests and CI.

  • New tests cover the locale rule, the docblock reading (unit tests, plus the loader run in a PHP process under
    OPcache settings), mixed routes and the registered services.
  • The test application and the workflow run on every Symfony line. PHP 8.4 is added, and 7.* runs on PHP 8.2 to 8.4.
  • Every job also runs with lowest dependencies where they install and run: 45 jobs, 16 of them lowest.
  • The attribute fixture routes live under /attributed/, so both kinds of route are tested on 6.4.

• Docs. CHANGELOG.md 2.0.0. The README shows type: attribute route imports for Symfony 7 in the setup section and
  Attribute\Route in the attribute examples. The option has its own README section.

Backward compatibility

This is a major release: PHP 7.1+ and Symfony 3.4+ stay supported, and composer constraints need ^2.0. A check from
1.8.2 lists 2 changes to the bundle's own API:

• the TreeBuilder return type, which breaks only a subclass that overrides getConfigTreeBuilder() without it;
• the extension's new parent, which breaks only a subclass that calls addAnnotatedClassesToCompile() or
  getAnnotatedClassesToCompile().

Configuration is @final, so Symfony's DebugClassLoader reports any subclass.

Where Symfony passes no annotation reader, the bundle ignores its docblock annotations unless docblock_annotations is
true. That includes @RequiredPermissions, which 1.x also ignored on 6.4 with framework.annotations disabled. An
application that moves there from a setup where Symfony's reader applied them (3.4 to 6.4 with framework.annotations
enabled) must set the option to keep them; the CHANGELOG says so under Security. From 6.4, a route with both docblock
annotations and attributes fails to load wherever docblocks are read. The locale placeholder changes the result for
items that Symfony reads as the language default or as an empty language, listed under Changed.

Exclusions in the workflow

Every excluded combination either cannot be installed or fails inside a dependency's oldest release:

• Symfony 5 on PHP 7.1, 6 on PHP 7.x, and 7 on PHP 8.1 and older: Composer cannot install them (PHP version).
• Symfony 3 on PHP 8.x: Composer cannot install it (doctrine/orm).
• Symfony 4 lowest on PHP 8.x: Symfony 4's old routing annotation loader misreads the fixture class names.
• Symfony 5 and 6 lowest on PHP 8.1+: paysera/lib-normalization 1.2.0 installs paysera/lib-object-wrapper 0.3.0,
  whose ArrayAccess methods break on PHP 8.1 (paged queries answer 500). Symfony 6 lowest runs on PHP 8.0.

Test plan

• All 45 workflow jobs run locally with the workflow's own installs, and the suite passes on each with 328 tests. It
  also passes on 4 installs of FrameworkBundle 6.4 with routing 7 (7.0, 7.1, 7.3), and with http-foundation
  7 on three of them.

• Round 8: the new data sets fail against the commit before them and pass after. The exceptions pin unchanged
  behaviour, and those fail with the mutant they guard:

  • the reader: 4 on Symfony 7.4, and the same 4 on 6.4;
  • the default: 4 on 7.4 and 1 on 6.4;
  • mixed routes: 2 on 7.4 and 4 on 6.4;
  • the locale: 5 on 7.4, the line where the behaviour changes;
  • the follow-ups: the method's message, 2 on 7.4 and 4 on 6.4. The data sets for default, i-default and i- fail
    with 1.x's placeholder on 3.4, 6.4 and 7.4.

  The tests catch a mutant of each new behaviour: the mixed-route throw, the default, the injected-reader branch, the
  option gate, both annotation filters, the message and the placeholder.

• Compared with FrameworkBundle 6.4's own reader over 226 routed actions in 224 controllers, on doctrine/annotations
  2.0.2 and 1.14.4, the bundle with docblock_annotations: true gives the same result for 225. The other one is a
  lowercase @required, listed under Known gaps.

• The loader runs in a PHP process under four settings:

  • attributes only with docblocks stripped, default configuration: the routes load;
  • true with docblocks kept: the permission applies;
  • true with docblocks stripped: the load fails, also with OPcache off for the command line.

  On doctrine/annotations 1.14.0, the stripped case reads empty docblocks, which is why the floor is 1.14.4.

• On PHP 8.4, php -l over src/ reports 0 deprecations (master has 11 implicitly nullable parameters). The changed
  files also lint on PHP 7.1.

• A test application on Symfony 7.4 and another on 4.4 install the bundle from this branch: 27 tests each, none
  failing (2 skipped on 4.4).

• A Symfony 6.4 production application without an annotation reader: 2,195 tests, the same result for each.

• CI on this pull request after these commits.

Known gaps

• No booted-kernel test runs Symfony 7 with the default false. The functional configuration sets true, so that the
  @RequiredPermissions route keeps answering 401, 403 and 200. Unit data sets pin the default.
• doctrine/annotations is abandoned upstream. 2.0.0 uses it only where Symfony passes its reader, or where
  docblock_annotations is true.
• Doctrine reads @IgnoreAnnotation only in the class docblock. A bundle annotation listed there is skipped unless a
  use statement imports it or it is written with its full class name.
• With true on Symfony 7, a lowercase @required on a routed action fails the load. FrameworkBundle 6.4's reader
  ignores it globally; it has been deprecated since 6.3.
• On Symfony 7.1+, getPreferredLanguage() returns Symfony's formatting of a configured locale (es_419 → es,
  en-us → en_US), as 1.x did with http-foundation 7.1+. q=0 is not honoured, as on master.
• Class-level options of a parent controller never reach its inherited routes, as on master.
• testAnItemOfOnlyASemicolonIsNotALanguage is skipped where Symfony's parser throws on ; (http-foundation 4.4 only).
• PayseraApiExtensionTest collects E_USER_DEPRECATED itself. Turning on convertDeprecationsToExceptions instead
  fails 167 of 320 tests on PHP 8.4, all from lib-normalization 1.3.1.

Decisions you may question

• docblock_annotations defaults to false, as round 8 suggested. The reply asks whether 2.0.0 should ship true
  instead. Pinned by testLoadWithoutAnnotationReaderReadsOnlyAttributesByDefault, data sets "docblock annotation" and
  "annotation on the class and attribute on the action: only the attribute is read".

🤖 Generated with Claude Code

[mSprunskas]

  1. Attribute-only apps with OPcache save_comments=0 can no longer load routes

  src/Service/RoutingLoader/RoutingAttributeLoader.php:105 (checkDocblocksAreKept())

  - Before: with no reader, docblocks were never read, so opcache.save_comments=0 didn't matter. Routes using #[Route] and #[Body] loaded fine.
  - Now: the first route throws a ConfigurationException, so router and cache warmup fail, even when the app has no docblock annotations at all.
  - Status: listed as Breaking in the CHANGELOG, so it's a deliberate choice, but it is still a regression. The check can't be made lazy, because stripped comments look the same as missing ones. Ways out: log a warning instead
    of throwing, add a config switch to turn off docblock reading, or keep it and accept the break.

  2. Class references in annotation arguments fail for same-namespace classes and namespace aliases

  RoutingAttributeLoader.php:212-228 (getResolvableImports()). This is the issue you pasted, confirmed against Doctrine's DocParser::Constant() source.

  - Before: docblock annotations were ignored in this setup, so their arguments were never evaluated.
  - Now: these docblocks are parsed, but __NAMESPACE__ is only set for the bundle's own namespace and namespace-alias imports are dropped:
    - Roles::ADMIN for a same-namespace class, or Sec\Roles::ADMIN with use App\Security as Sec, fails the route load with Doctrine's "Couldn't find constant" error.
    - UserDto::class for a same-namespace class silently becomes "UserDto". Route loading then fails with the misleading "Denormalizer UserDto does not exist".
  - Docs: neither case is listed under Changed in the CHANGELOG.
  - Fix: for each Identifier:: with no import, add an import for a matching same-namespace class or namespace-alias class, as long as it exists and isn't an annotation. Don't set __NAMESPACE__ in general. One catch: the alias
    import also lets @Sec\SomeAnnotation tags resolve, so skip it when the docblock has an @Sec\ tag. Alternatively, document it as Breaking.

[vinayak-iyer-paysera]

Thank you for the sixth round. I have answered both points in follow-up commits.

1. Done in c749ac4, as a switch: a docblock_annotations option, true by default. The bundle is public and its
   consumers are unknown, so the default keeps the docblock annotations applied for the applications that use them, and
   the route load still fails when OPcache strips docblocks. An application that uses only the attributes sets
   docblock_annotations: false: the loader then reads none of the bundle's docblock annotations and does not check
   OPcache, so save_comments=0 no longer matters to the bundle. The option takes effect from Symfony 6.4, where the
   bundle decorates the attribute loader. There it also covers @Route routes, and where framework.annotations is
   enabled, Symfony's own annotation reader still needs save_comments. Before 6.4 the option has no effect. The README
   and CHANGELOG say so. The extension adds the setter call only for false, so the default service definitions do
   not change. New tests cover the configuration, the extension and the loader with the option off, with and without an
   annotation reader. With docblocks stripped in a PHP process and the option off, the routes load.
2. Fixed in 1e4205e, as you suggested. For each Name:: or Name\Sub:: reference in the docblock whose first segment is
   not imported, the loader adds an import when the class exists and is not an annotation: relative to the
   controller's namespace, or under an imported namespace alias. It skips an alias that the same docblock also writes
   as a tag (@Sec\…, in any letter case), so another library's annotation reached through that alias stays ignored.
   __NAMESPACE__ is still set only inside the bundle's annotation namespace. New data sets cover a same-namespace
   ::class, a relative Support\Roles::ADMIN, an aliased Security\Roles::ADMIN and an alias followed by several
   namespace segments. Two more cover an alias used both for a tag Doctrine rejects and for a ::class reference, once
   with the tag in another letter case: the tag stays ignored and the reference stays as written. None of the 644
   docblocks with the bundle's annotations in the local applications uses either form; all 7 class references there
   are imported classes.

Two more fixes in 1e4205e, from my own review:

• self::ROLE now resolves, as with Doctrine's reader.
• The second DocParser pass from round 5, which finds a tag written as an annotation's short name that does not
  resolve to it, now maps only the names the docblock writes as a tag (@Query, not @QueryParam). It used to remap
  every short name the controller did not import. So a constant of an imported class that shares an annotation's
  short name, such as Validation::ROLE, failed the route load. With point 2, the new forms would have failed the
  same way whenever their first segment was such a name (Query\Roles::ADMIN).

All 45 workflow jobs pass locally with 364 tests each, and so do 4 installs of FrameworkBundle 6.4 with routing and
security-core at 7.0, 7.1 and 7.3. A Symfony 6.4 production application without an annotation reader gives the same
result for each of its 2,195 tests.

Edited on 2026-10-14: the docblock count in point 2 said 641, from a scan a day older. A recount of the local
applications gives 644 docblocks in 209 files; all 7 class references are still imported classes, so the conclusion is
unchanged.

[mSprunskas]

  1. Medium: a tag through an unimported namespace alias is silently ignored, including @Rest\RequiredPermissions
  src/Service/RoutingLoader/RoutingAttributeLoader.php:202, :214, :288
  - The parser runs with setIgnoreNotImportedAnnotations(true). Doctrine's DocParser then drops @Rest\X when rest isn't imported, without an error.
  - The check after parsing only looks at short names (@RequiredPermissions) and at aliases that the class or one of its traits imports. An alias that nothing imports is never checked.
  - So @Rest\RequiredPermissions({"ROLE_ADMIN"}) in a controller without use … as Rest removes the permission check on Symfony 7. On Symfony 6.4 with the reader, the same code fails to load.
  - The CHANGELOG ("still ignored") and README document this. But it is a gap in the same control that the release's Security section says is fixed.
  - Fix: in parseTags(), find tags matching @<alias>\<bundle annotation short name> where <alias> isn't in $useStatements, and throw ConfigurationException for them, as is already done for short names.

  2. Low–Medium: the app's own RestAnnotationInterface annotations are skipped unless written fully qualified
  RoutingAttributeLoader.php:236, :259, :278
  - getResolvableImports() only keeps a use statement that points into the bundle's annotation namespace or to a class that isn't an annotation. It only sets __NAMESPACE__ for the bundle's own namespace.
  - So use App\Annotation\AuditAccess; with @AuditAccess gives no annotation. The same happens for an annotation class in the controller's own namespace. Doctrine's reader reads both.
  - My earlier "namespace-resolved" finding is the same issue. getUnresolvedAnnotationImports treats <controller ns>\RequiredPermissions as resolved, but the parser never resolves it, so the app's annotation is dropped.
  - RestAnnotationInterface is a public extension point. A custom security or audit annotation would stop working silently when an app moves from 6.4 with the reader to Symfony 7. This is documented in the README, but it fails
    silently.
  - Fix: also import use statements, and resolve controller-namespace names, whose class implements RestAnnotationInterface. Or throw when a tag resolves to such a class but isn't read.
  
  3. Low: the error message is wrong when the use statement names another class
  RoutingAttributeLoader.php:321
  - With use App\Entity\Query; and @Query(...), the error says the tag "does not resolve to a class". It actually resolves to a class that isn't an annotation.
  - The route load still fails as intended (the reader path fails too), so only the wording is wrong. Say "resolves to <class>, not to <bundle annotation>" when the alias is in $useStatements.
  
  4. Cleanup: readLanguages() copies Request::getLanguages()
  src/Listener/LocaleListener.php:74
  - It repeats the same AcceptHeader parsing, the i- handling and the casing. getLanguages() is the same in every supported Symfony version; only getPreferredLanguage() changed. Calling $request->getLanguages() removes the
    copy.

[vinayak-iyer-paysera]

Thank you for the seventh round. I have answered the four points in follow-up commits, in your order. Before answering,
I compared the reader-less reading with Doctrine's AnnotationReader over 184 routed methods, so the answer covers each
class of input rather than only the case you named; the differences that remain are listed in the description.

1. Fixed in 92375fb. A tag written through a namespace alias, ending in one of the bundle's seven annotation names and
   resolving to no class, now fails the route load with a ConfigurationException: an alias that nothing imports
   (@Rest\RequiredPermissions without use … as Rest), and an alias imported for a namespace that has no such class.
   fcdc389 extends the same control to a tag that resolves into Paysera\Bundle\ApiBundle\Annotation to a class that does
   not exist, such as an import of a misspelled …\Annotation\RequiredPermission, also inside another annotation.
   Tags are read as Doctrine's lexer reads them, so a name split across lines or written with a space after the
   backslash is refused too, and an @ in prose such as `@Api\Body` is not a tag. Another library's tag through
   an unimported alias stays ignored unless its name is one of the seven (@Lib\Cache loads).
2. Fixed in 92375fb, as you suggested first: an application's own annotation that implements RestAnnotationInterface is
   read as with Doctrine's reader, through a use statement, in the controller's namespace or relative to it, through a
   namespace alias, or fully qualified. Only classes implementing that interface are imported, so another library's
   annotation in the controller's namespace stays ignored. fcdc389 also resolves constants and ::class of annotation
   classes in arguments (AppPermission::ROLE), which failed with "Couldn't find constant" before; an annotation class
   the same docblock writes as a tag keeps its tag ignored, and an own annotation written with a doubled backslash is
   refused, where PHP stopped with "Cannot redeclare class".
3. Fixed in 92375fb: when the use statement names another class, the message says the tag resolves to that class, not to
   the annotation. fcdc389 adds a message for an import in another letter case, which otherwise named the same class
   twice, and replaces Doctrine's "[Syntax Error]" for an unresolved nested annotation with the bundle's message.
4. Changed in 47de41a: the listener calls $request->getLanguages() and compares its tags with the configured locales
   ignoring letter case, so DE now matches a configured de on every line. getLanguages() is not the same on every
   supported line, though: 3.4.34 iterates the header's keys (Request.php:1757), so a numeric tag comes back as an
   int; 5.4.50 upper-cases every subtag (:1727, zh_HANT_TW); 7.4.20 formats the tag and removes duplicates
   (:1741, :1743, zh_Hant_TW). Comparing without case covers the first two. The third remains by design: from 7.1
   getLanguages() drops a numeric region or a variant and keeps an x- tag and a short i- tag whole, so such a tag
   can pick another locale than on 6.4 (es-419 no longer matches a configured es_419, nor i-ami a configured
   ami). The CHANGELOG says so, and a data set pins the result on each line.

All 45 workflow jobs pass locally with 407 tests each, and so do 4 installs of FrameworkBundle 6.4 with routing and
security-core at 7.0, 7.1 and 7.3. A Symfony 6.4 production application without an annotation reader gives the same
result for each of its 2,195 tests. Over 184 routed methods the comparison with Doctrine's reader finds no case where
the bundle drops an annotation the reader applies; the remaining differences are tabled in the description.

One question. The remaining difference in the lenient direction: a tag that resolves to no class is ignored like any
unknown tag, so a forgotten import of an application's own RestAnnotationInterface annotation, one written in another
letter case before its class is loaded, or a bare misspelled @RequiredPermission, goes unnoticed where Doctrine's
reader fails. It follows from ignoring unknown tags, which your round-2 review asked for ("Do not let unrelated docblock
content stop route loading"). The alternative for 2.0.0 is Doctrine's strictness, where every unresolved tag fails the
route load: the reading would then match Doctrine's on 8 more of the 184 routed methods, and a Symfony 7 application
with a stray @note or @SomeCustomTag on a routed docblock would fail to load its routes. I kept the lenient reading;
if you prefer the strict one, I will make that change. The other decisions I kept, with their evidence and the test that
pins each, are in the description under "Decisions you may question".

[vinayak-iyer-paysera]

Before your next look: after my round-7 reply I ran two more passes over its follow-up commit. They found docblock forms where, without an annotation reader, the bundle loaded a route without its @RequiredPermissions while Doctrine's reader fails: @Rest\ continued with \RequiredPermissions on the next line, a colon in a name (@RequiredPermissions:admin), and a space or a dot instead of the backslash (@Rest RequiredPermissions). They also found a few it refused where the reader loads: an own annotation through class_alias(), and an import in another letter case once its class is loaded. All of them came from the regex that approximated Doctrine's lexer. Instead of patching it again, 8574742 reads the tags with Doctrine's own DocLexer, as DocParser finds them, and refuses only where Doctrine's reader fails as well, apart from the decisions listed in the description. It also closes the "Cannot redeclare class" gap for a nested annotation with a doubled backslash. The comparison with Doctrine's reader now covers 224 controllers on annotations 1.14 and 2.0, and the description has the updated table. The lenient-vs-strict question from my last reply still stands.

[mSprunskas]

 1. A REST attribute on a route silently drops its docblock annotations, including @RequiredPermissions (permission bypass)
  - Where: src/Service/RoutingLoader/RoutingAttributeLoader.php:123-126, :948, and src/Service/RestRequestHelper.php:129
  - Cause: configureRoute() runs loadAnnotations() and then loadAttributes(). Both call setOptionsForRoute(), and both write the same SERIALIZED_REST_OPTIONS_KEY default on the route. If a route has any REST attribute, the
    attribute options replace the docblock options entirely instead of merging with them.
  - Example: a half-migrated controller has @RequiredPermissions in its class docblock and #[Body] on one action. That action runs with no permission check and no error.
  - Why this change makes it worse: before, this only happened on Symfony 6.4 with a reader. The new docblock parser now enables it on Symfony 7 as well.
  - CHANGELOG: the Security entry says the docblock annotations "are now applied", which is not true for mixed routes.
  - Tests: no fixture has both docblock annotations and REST attributes on one route. AttributedDocblockOptionsController uses only the docblock.
  - Fix: merge both sets into one RestRequestOptions before writing it, or throw a ConfigurationException when a route has both. Then add a fixture with both on the same route.

  2. LocaleListener no longer matches a bare language to a configured locale with a region
  - Where: src/Listener/LocaleListener.php:47
  - Example: on Symfony 7.1+, with locales [en_US, lt_LT], a request with Accept-Language: en used to get en_US through prefix matching. It now silently gets the default locale.
  - CHANGELOG: this is not listed under Changed.
  
  3. The docblock_annotations: true default can break apps that don't use docblocks at all
  - Where: RoutingAttributeLoader.php:135
  - Cause: checkDocblocksAreKept() runs for every route whenever there is no annotation reader.
  - Example: a Symfony 7 app that uses only attributes and runs with opcache.save_comments=0 now fails to load its routes.
  - Fix: default the option to false, or only run the check when a docblock actually contains bundle tags.
  
  Design decision

  4. The custom docblock parser duplicates Doctrine's AnnotationReader
  - Where: RoutingAttributeLoader.php:211
  - Problem: about 800 lines reimplement how Doctrine resolves imports and ignored names, and add more than ten heuristic refuse* checks. doctrine/annotations is already a hard dependency.
  - Fix: when no reader is injected, use new AnnotationReader().
  - Payoff: this alone removes findings 5–8 and 11–12 and most of the roughly 150 fixture controllers.

[vinayak-iyer-paysera]

Thank you for the eighth round. I have answered the four points in follow-up commits, in your order, each with a
remedy you offered.

1. Fixed in 6d45dfe. From Symfony 6.4, wherever the bundle reads docblock annotations, a route configured with both
   docblock annotations and attributes fails to load with a ConfigurationException that names the method.
   • "Reads docblock annotations" means Symfony passes its reader (6.4 with framework.annotations), or
     docblock_annotations is true.
   • The check counts the bundle's classes and an application's own RestAnnotationInterface and
     RestAttributeInterface classes, on the action or on its class. Since 896cf5b the message says so.
   • Your example, a class @RequiredPermissions with #[Body] on the action, now fails there instead of running
     without the permission. On master with Symfony's 6.4 reader, the same controller loads with no permission.
   • Under the new default of point 3, Symfony 7 reads no docblocks, so that controller loads with #[Body] only. A
     data set pins this, and my question below is about it.
   • Before 6.4 the bundle's annotation loader reads no attributes, as in 1.x.
2. Fixed in c128796. The listener calls Request::getPreferredLanguage() again, as 1.x did, so on 7.1+ en, en-GB
   and lt reach a configured en_US or lt_LT again.

   • The placeholder is now '' instead of 'default', so de-DE and de no longer lose to it (the Fixed entry).

   • The placeholder also changes the result for header items that Symfony reads as the language default, or as an
     empty language. A CHANGELOG line under Changed lists them since 896cf5b and 4d5ec4f:

     • default and i-default before a configured locale now give that locale on every line, where 1.x kept the
       default one;
     • "", i- and -de keep the default locale on 3.4–7.0, and so do "" and 0 on 7.1, where 1.x gave the
       configured one.

     I measured each shape on http-foundation 3.4, 4.4, 6.4, 7.0, 7.1, 7.3 and 7.4. Data sets pin default,
     i-default and i-, and they fail with 1.x's placeholder on 3.4, 6.4 and 7.4.

   • This also undoes two things round 7 had changed. The letter-case matching is gone: on 3.4–7.0, DE no longer
     matches a configured de, the same as on master. The copy of getLanguages() is gone too.

   • Against master, the listener now changes only the placeholder, a string cast and round 5's strval.

3. Fixed in 9e61258. docblock_annotations defaults to false.
   • Where Symfony passes no reader, the bundle then reads only attributes. It runs no OPcache check and parses no
     docblock, so an attributes-only application with save_comments=0 loads its routes. A data set in a PHP subprocess
     with docblocks stripped pins this.
   • Where Symfony passes its reader, the bundle uses it as in 1.x, whatever the option says. Before 6.4 the option has
     no effect.
4. Fixed in 4225ad0. With docblock_annotations: true and no injected reader, the loader builds one
   new AnnotationReader().
   • The docblock parser, DocblockTagReader and 149 fixture files are gone. The loader went from 953 lines to 161, and
     the pull request shrinks from 216 files to 69.
   • Reading now fails where Doctrine's reader fails: on an unimported tag that is not ignored, and when OPcache runs
     with save_comments=0. That answers my lenient-vs-strict question in favour of Doctrine's strictness, and retires
     round 5's per-SAPI OPcache rule.
   • 5fabfc3 requires doctrine/annotations 1.14.4 or 2.0.2. Earlier releases (1.14.0–1.14.3, 2.0.0, 2.0.1) compare
     save_comments with === 0 and never refuse, so a test with stripped docblocks fails on 1.14.0.
   • Compared with FrameworkBundle 6.4's own reader, 225 of 226 routed actions in 224 controllers give the same result.
     The one difference is a lowercase @required on an action. FrameworkBundle 6.4 ignores it globally (deprecated
     since 6.3, gone in 7.0); the plain reader fails on it.
   • @IgnoreAnnotation: Doctrine reads it only in the class docblock. An annotation of the bundle listed there is
     skipped only when no use statement imports it and it is not written with its full class name. An imported one
     still applies. The notes say so since 4d5ec4f, and data sets pin the unimported and the imported case.

All 45 workflow jobs pass locally with 328 tests each, and so do 4 installs of FrameworkBundle 6.4 with routing 7
(7.0, 7.1, 7.3). A Symfony 6.4 production application without an annotation reader gives the same result for each of
its 2,195 tests. The data sets of the four answers fail against the commit before each. The data sets that pin
unchanged behaviour fail with the mutant they guard. The tests catch a mutant of each new behaviour: the mixed-route throw, the default, the injected-reader branch, the option gate, both annotation
filters, the message and the placeholder.

One question, about point 3. With false, an application that moves to Symfony 7 from a setup where Symfony's
reader applied the annotations (3.4 to 6.4 with framework.annotations enabled) loses its docblock
@RequiredPermissions without an error, unless it sets docblock_annotations: true. The CHANGELOG says so under
Security.

Of the 40 internal applications I checked that require the bundle, 22 write its annotations in docblocks and 10 use
attributes. None mixes the two, and none runs Symfony 7 yet.

I kept false, as you suggested. With true, an upgrading application would keep its docblock permissions, and an
attributes-only one under save_comments=0 would fail to load its routes instead (your point 3). If you prefer true,
I will change the default.

[mSprunskas]

     Location: src/DependencyInjection/Configuration.php:26, src/Service/RoutingLoader/RoutingAttributeLoader.php:105
     On Symfony 7, or on Symfony 6.4 with framework.annotations disabled, docblock_annotations is false by default. Then getRestAnnotations() returns an empty array without any error, so @RequiredPermissions is dropped and the
     endpoint is open to any authenticated user.
     Fix before release: check the docblock text for the bundle's annotation names, and also confirm the controller imports Paysera\Bundle\ApiBundle\Annotation, so that short names like @Body from other libraries do not match.
     If both are found, throw ConfigurationException and tell the user to set docblock_annotations: true or to use attributes.
  2. Medium. One unknown docblock tag stops all routes from loading
     Location: src/Service/RoutingLoader/RoutingAttributeLoader.php:137
     With the option on, the bare AnnotationReader reads the docblocks of every #[Route] controller, vendor ones included. A tag that is not imported (for example @note) throws AnnotationException, and route loading fails for
     the whole app.
     Fix: only parse controllers that use the bundle's annotation namespace, or catch the exception and rethrow it with context.
  3. Low to medium. The mixed-configuration check breaks the whole router
     Location: src/Service/RoutingLoader/RoutingAttributeLoader.php:79
     One controller that mixes a class-level docblock annotation with a method attribute throws during route loading, so every route in the app returns 500, not just that controller's routes.
     Fix: accept it as a documented break, or make the error message clearer.
  4. Low. The class docblock is parsed again for every action
     Location: src/Service/RoutingLoader/RoutingAttributeLoader.php:111
     The reader has no cache, so a controller with 20 actions has its class docblock parsed 20 times.
     Fix: cache the result per class name, or wrap the reader in PsrCachedReader.
  5. Low. docblock_annotations: true sometimes does nothing, with no warning
     Location: src/DependencyInjection/PayseraApiExtension.php:263
     On Symfony before 6.4 the value is dropped. When Symfony passes its own reader, that reader is used instead.
     Fix: document this, or log a warning.
  6. Low. New untested CI combinations
     Location: .github/workflows/ci.yml:47
     Removing the exclusion adds PHP 8.0 runs against Symfony 5 and 6 (including the end-of-life 6.0.x). These may fail to install and turn CI red for reasons unrelated to this change.
     Fix: run CI once and add the exclusion back if needed.
  7. Low (tests). The paged query test starts the kernel and database before it decides to skip
     Location: tests/Functional/FunctionalPagedQueryTest.php:39, tests/Functional/FunctionalTestCase.php:57
     makeTest() boots the kernel and adds 100 entities, then may skip.
     Fix: add "if ($this->kernel === null) { return; }" at the top of tearDown(), then call skipUnlessRoutesAreLoaded() before setUpFor(). Moving the skip without the guard makes every skipped data set fail with "Call to a
     member function getContainer() on null".
  8. Nit. The docblock_annotations setting is stored as bool|null
     Location: src/Service/RoutingLoader/RoutingAttributeLoader.php:41
     The setter is only ever called with true.
     Fix: pass $config['docblock_annotations'] directly and type the property as bool = false.

[vinayak-iyer-paysera]

Superseded by #21, which restarts the Symfony 7.4 support on a fresh branch and maps every review point from this pull request to its resolution in its description.