Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem/Motivation
With the current typehinting an IDE can't provide proper autocompletions for methods and other inspections.
Steps to reproduce
class C1 {
protected \Drupal\node\NodeStorageInterface $nodeStorage;
public function m1() {
foreach ($this->nodeStorage->loadMultiple() as $node) {
$node->isPromoted();
}
}
}
The problem is that several method signature are defined in the EntityStorageInterface or ConfigEntityStorageInterface or ContentEntityStorageInterface.
The implementer classes use {@inheritdoc} for ::load() and for other methods as well.
That means an IDE still thinks that the return value of a NodeStorageInterface::load() is null|EntityInterface instead of null|NodeInterface
That is why an IDE can't provide more accurate help.
Proposed resolution
Add @method PhpDoc entries for every EntityStorageInterface descendants.
Issue fork drupal-3323252
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:
changes
Comments
Comment #2
longwaveedit: ignore, wrong issue
Comment #4
sweetchuckComment #5
smustgrave commentedThink that looks correct but will wait for another +1 RTBC
Comment #6
quietone commentedHow does the API module handle @method, since @method is not part of the Drupal coding standards?
Ah, there is one PHP file using @method, \Drupal\Component\Datetime\DateTimePlus. It looks like this in the API docs. That is unreadable.
Looking in the Coding standards project. Yes, there is an issue, #2920333: Allow PHPDoc @method annotations in class headers.. That needs to be resolved first before changing core code. If approved, then changes to core core would not be made by single files but by some sensible, larger scope.
In summary, this is a won't fix and effort should go into the issue in the Coding standards project.
Comment #7
smustgrave commentedSo should we close this?
Comment #8
joachim commentedI don't understand what is needing to be fixed here.
I copy-pasted the sample code from the IS into my IDE (VSCode) and loadMultiple() is picked up and showing me the documentation for that method from EntityStorageInterface.
Comment #9
sweetchuckComment #10
sweetchuck@joachim Yes, the
::loadMultiple()is picked up, but the problem is that the$node->isPromoted()is not.Comment #11
sweetchuck@quietone I don't understand why we can't use
@methodnow, and enjoy the benefits.Why do we have to wait for "API docs" project?
Patch #3 is green. That means there is nothing against the coding standard.
Comment #12
quietone commentedIt is not just API docs project, there is also an existing Coding Standards issue that is still open about adding @method.
On a practical level, we should not be adding API documentation that will look like this on api.drupal.org.
@method $this add(\DateInterval $interval) @method static array getLastErrors() @method $this modify(string $modify) @method $this setDate(int $year, int $month, int $day) @method $this setISODate(int $year, int $week, int $day = 1) @method $this setTime(int $hour, int $minute, int $second = 0, int $microseconds = 0) @method $this setTimestamp(int $unixtimestamp) @method $this setTimezone(\DateTimeZone $timezone) @method $this sub(\DateInterval $interval) @method int getOffset() @method int getTimestamp() @method \DateTimeZone getTimezone()Comment #13
smustgrave commentedPostponing on #2920333: Allow PHPDoc @method annotations in class headers. though there hasn't been movement on that in 5 years so not super promising.
Comment #14
sweetchuck