Make opting into loading API files more granular to support finding deprecated hooks from Drupal core more easily

[mglaman]

Feature request

Follows up on #641

Drupal Slack link: https://drupal.slack.com/archives/C03L6441E1W/p1718043125262999

Summary:

:four: Detecting deprecated hooks with upgrade status module for Drupal 11 readiness

Added with #634. But then we had issues due to broken .api.php files somehow, made opt-in with #641.

Proposal: make current flag more granular so we load Drupal core .api.php files which shouldn't be broken.

1. Fix current docs, wording is wrong
2. Deprecate the current flag, treat it as controlling loading of contrib .api.php files, still defaults to false
3. Introduce a new flag for controlling loading of Drupal core .api.php files, defaults to false

Upgrade Status can opt-into loading core .api.php files.

[bbrala]

That would be awesome <3

[Kingdutch]

Not sure the current flag should be deprecated if we're going to change the meaning of it right? Or do you want to deprecate this one while making it control both things and then introduce a new flag for contrib as well?

Should we make the Drupal core .api.php files opt-out? I think for Drupal core we can be more certain that the .api.php files are well-behaved and this makes it likelier that at least Drupal core deprecations are picked up. In the issue opened previously only contrib issues were mentioned, so leaving that opt-in makes sense..

[mglaman]

Not sure the current flag should be deprecated if we're going to change the meaning of it right? Or do you want to deprecate this one while making it control both things and then introduce a new flag for contrib as well?

I wrote the issue hastily, so it may need to be clarified. I'm trying to prevent causing breaking changes and willy-nilly doing minor releases.

New bleedingEdge options:

• checkCoreDeprecatedHooksInApiFiles: false: to be turned true in the next minor release
• checkContribDeprecatedHooksInApiFiles: false to remain false.

checkDeprecatedHooksInApiFiles will be deprecated. The value will be mapped to checkCoreDeprecatedHooksInApiFiles and checkContribDeprecatedHooksInApiFiles if present. It is controlling the two and removing the granularity if it is set.

Does that make sense?

Although if we have upgrade_status automatically opt-in to checkCoreDeprecatedHooksInApiFiles for the project update bot, phpstan-drupal may as well turn it on by default since a lot of folks are using upgrade_status.

[bbrala]

I've implemented the description by @mglaman in #774