Problem/Motivation

When an object variable or a parameter or a returned value is type-hinted, the current policy requires the FQCN of the object to be used.

For example, 

   * @param array|\Drupal\Component\HtmlAttribute\HtmlAttributeCollection $attributes
   *   An optional array or HtmlAttributeCollection object of link attributes.

However, since the introduction of union types in PHP 8, readibility of such annotations got worse when multiple classes are allowed for a single object.

For example,

   * @param \Drupal\Component\Render\MarkupInterface|\Drupal\Component\HtmlAttribute\HtmlAttributeValueBase|scalar|array<scalar>|null $value
   *   The value to set.

Other projects just annotate the unqualified class name, and rely on the use imports at the top of each file to fully qualify the classes when needed. PHPStan supports this model natively (and IDEs too??).

Allow using the class name only in the annotations. If the class name is not present in the same namespace of the class where the annotation is present, a matching use import should be present to allow matching the referred class existance.

Given the second example above, this will become


namespace Drupal\Component\HtmlAttribute;

use Drupal\Component\Render\MarkupInterface;

   ...

   * @param MarkupInterface|HtmlAttributeValueBase|scalar|array<scalar>|null $value
   *   The value to set.

Benefits

If we adopted this change, the Drupal Project would benefit by having shorter and more readable PHPDoc annotations, which also makes it easier to adopt more complex PHPStan capabilities.
It also will make the PHPDoc annotations equal to the actual inlined type hints (as long as iterables are not involved, which is a different case). This will help removing unnecessary @var annotations from the code base.

Three supporters required

  1. https://www.drupal.org/u/Kingdutch (2024-04-10)
  2. https://www.drupal.org/u/borisson_ (2024-04-10)
  3. https://www.drupal.org/u/bbrala (2024-04-10)
  4. https://www.drupal.org/u/dww (2024-04-10)

Proposed changes

Create an MR with all proposed changes.

Remaining tasks

  1. Create this issue in the Coding Standards queue, using the defined template
  2. Add supporters
  3. Finish fleshing out the proposed standards changes
  4. Create a Change Record
  5. Review by the Coding Standards Committee
  6. Coding Standards Committee takes action as required
  7. Discussed by the Core Committer Committee, if it impacts Drupal Core
  8. Final review by Coding Standards Committee
  9. Documentation updates
    1. Edit all pages
    2. Publish change record
    3. Remove 'Needs documentation edits' tag
  10. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a full explanation of these steps see the Coding Standards project page

Issue fork coding_standards-3360160

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

mondrake created an issue. See original summary.

mondrake’s picture

mondrake
Location 🇮🇹
commented
Parent issue: #3309010: Support PHPDoc Types in @param @var @return annotations »
Related issues: +#3360163: Stop using FQCN in @param @var @return annotations

Opened #3360163: Stop using FQCN in @param @var @return annotations in Coder's issue queue to match this.

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented

I think I agree with this proposal. We could simply drop the check for FQN names in doc comments from Coder. Tools like PHPStan are better in verifying that the class names used there are valid references.

kingdutch’s picture

kingdutch
he/him
Primary language English
commented

I used to be against this because it led to codebases having `use` import statements for types that weren't used in code but only in comments. However:

  1. That was often specifically for annotations which are already being replaced by Attributes
  2. That was often because PHP did not yet support the type information within the language where now most PHPDoc comments will have a matching parameter or return type hint for which the use statement is already needed
  3. A reference in a comment is still a "usage' because it indicates some kind of contract, so for being able to find "Where something is used" with static analysis tools it's still important in case of deprecations and such; PHPStan already does these things for us which further proves that this is no longer a problem

Given those developments within PHP, I'm also happy to +1 this proposal :D

acbramley’s picture

acbramley commented

Big +1 on this, we've got some wildly long union types, could this also apply to @property annotations?

kingdutch’s picture

kingdutch
he/him
Primary language English
commented
Title: Stop using FQCN in @param @var @return annotations » Stop using FQCN in PHPDoc annotations
Issue summary: View changes

Moved into new coding standards template and added myself as supporter.

Generalised the title to PHPDoc annotations so we don't need to list all @ annotations that it may support.

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
commented
Issue summary: View changes
bbrala’s picture

bbrala
Location Netherlands
commented
Issue summary: View changes
mondrake’s picture

mondrake
Location 🇮🇹
commented

BTW Rector here can help a lot, https://getrector.com/documentation/import-names

Working with the configuration of withImportNames one can get (or not) existing FQCNs in PHPDoc be split between the use import and the remaining class name in the docs, can remove (or not) unused use imports.

Once this is finalized, a single rector run could just clean the entire codebase.

mondrake’s picture

mondrake
Location 🇮🇹
commented
Issue summary: View changes
dww’s picture

dww
we/he/they
commented
Issue summary: View changes
Issue tags: +Needs issue summary update
  1. Adding myself as another (enthusiastic!) supporter. I never understood why we required FQCNs for these.
  2. Fixed the dates for supporters (h/t https://xkcd.com/1179 😆)
  3. Started identifying the docs that need updating.

Tagging for a summary update since I'm out of time to start fleshing out the proposed changes. Also worth reviewing that I found all the spots we need to fix.

Thanks!
-Derek

quietone’s picture

quietone commented
Related issues: +#2341405: Decide on standard for referencing namespaced classes
andypost’s picture

andypost
he/him
Primary language Russian
commented
Related issues: +#1624564: Coding standards for "use" statements
quietone’s picture

quietone commented
Issue summary: View changes

quietone opened merge request !14

quietone’s picture

quietone commented
Status: Active » Needs review

Started an MR with a minor change just to show where this needs to be changed. Not sure if there are other places.

Or, the text could be like what is in the PHPStan docs

Class and Interface names should be a relative name like Baz when resolved on the current namespace or via a use statements. Otherwise use a fully-qualified name (FQN) like \Foo\Bar\Baz.

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
commented

I think this is the only place that needs to change, I like the proposed text, to me that is clear. I like that phpstan docs a bit more because it also includes this part: resolved on the current namespace or via a use statements. If we can add that it seems good to go.

quietone’s picture

quietone commented

I made that change.

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
commented
Status: Needs review » Reviewed & tested by the community

Looks good to me, thanks @quietone

drunken monkey’s picture

drunken monkey
he/him
Primary language German
Location Vienna, Austria
commented

Not sure, I do think there are other places where this needs to be changed. I see the following other lines on this page:

  • Always prefix types with the fully-qualified namespace for classes and interfaces (beginning with a backslash). If the class/interface is in the global namespace, prefix by a backslash.
  • When documenting variables with the @var tag note that you should use the special /** */ delimiters with a double opening asterisk. Always use the fully qualified namespace of the class or interface, and include the name of the variable at the end.

I’d say those should be changed (or maybe even removed, in the former case) as well.
I also think we should be consistent in whether we hyphenate “fully-qualified” but that might be a different issue. (I see two occurences without a hyphen, here and in namespaces.md.)

The change itself looks good to me, though, so +1 on that.

quietone’s picture

quietone commented
Status: Reviewed & tested by the community » Needs review

Updated the MR so the change is described in 'data types in documentation' and have other places reference that. That should help to keep future changes in one place, not many.

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
commented
Status: Needs review » Reviewed & tested by the community

This looks great. I really like that last change, it should help keep us up to date in future.

jonathan1055 made their first commit to this issue’s fork.

quietone’s picture

quietone commented
Issue summary: View changes
Issue tags: -Needs issue summary update

This was brought up in meeting, #3576923: Coding Standards Meeting Wednesday 2026-03-04 0700 UTC, and there was no disagreement with this. Removing the tag for an IS update since that seemed about getting the wording correct and that is now in the MR.

quietone’s picture

quietone commented
Issue tags: +Needs change record
jonathan1055’s picture

jonathan1055 commented

I ran the 'pages' manual job and here is the updated (temporary) site, so that you can check the actual changes:
https://coding-standards-3360160-86968b.pages.drupalcode.org/php/documen...

I would have linked to the actual paragraph, but not all of them have automatic links to the sub-sections. It's confusing because the ones that do have links appear to be smaller with a smaller title. It should be easy to do, and would really help with navigation, so maybe would you like me to open a new issue for that?

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
commented

@jonathan1055 I think that's a good idea, can you open a new issue for that?

jonathan1055’s picture

jonathan1055 commented

OK here is it #3580194: Titles and automatic links to sub-sections

jonathan1055’s picture

jonathan1055 commented

Actually I was wrong, there are links to the sections. Here is a link to the updated paragraph
https://coding-standards-3360160-86968b.pages.drupalcode.org/php/documen...

I was thinking of the functionality of sites such as the Gitlab Templates documentaion, where if you hover over the title you see the pop-up link which gives you the permalink url. But that feature is provided by Zensical not MkDocs.

I will close the other issue, sorry for the distraction.

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
commented
Status: Reviewed & tested by the community » Needs work
Issue tags: -Needs change record

The cr looks good, but we should resolve the remark by @drunken monkey as well.

joachim’s picture

joachim commented

We don't seem to have checked that IDEs actually support this?

I can confirm that Visual Studio Code does.

mstrelan’s picture

mstrelan commented

PhpStorm does too.