Document the return value expected by SelectionInterface::getReferenceableEntities() when used on an entity type with no bundles.

Issue description

The documentation in Drupal\Core\Entity\EntityReferenceSelection\SelectionInterface::getReferenceableEntities() doesn't specify the expected first level key when used on an entity type that does not contain bundles:

/** * Gets the list of referenceable entities. * * @return array * A nested array of entities, the first level is keyed by the * entity bundle, which contains an array of entity labels (escaped), * keyed by the entity ID. */ public function getReferenceableEntities($match = NULL, $match_operator = 'CONTAINS', $limit = 0);

The expected first level key when no bundles are available is the entity type ID; example: 'role'.

Without that first level entity type id key, any many other functions using this method will throw PHP notices etc; example: core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem::getSettableOptions().

If this had been documented, I would have known that my implementation of getReferenceableEntities() for a custom entity type was incorrect rather than assuming getSettableOptions() was incorrect and writing a patch etc. Adding a note will likely save others time debugging the PHP notices from not returning the expected value in getReferenceableEntities().

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Comment 5 months ago →
🇺🇸United States lhridley
From what I've been able to determine, there are no tests in Core that actually pass a value for the first parameter, $match. All calls that I can locate call this method with no values passed for the parameters, instead taking the default values. I limited my search to Drupal Core versions 10 and 11.

The Core Kernel test that exists calls the method without any parameters, so default values are used.

In addition, all of the tests that I have located are in core modules that have bundles, so I don't think that a test exists for this.

So, this begs the question:

* Are there Core or contrib entities that exist without a bundle?
* Do we need a test for this in Core?

If the answer to both is no, then:

* what is the purpose of the first parameter, and what is a use case where a value would be passed?
* If it has no real world purpose, should the API be changed to remove it?
Status changed to Needs review 3 months ago3:13am 2 April 2025
Comment 3 months ago →
🇮🇳India andol
We need more info on this ticket to proceed further. Updates to this ticket hasn't been made in a while.
Comment about 2 months ago →
needs-review-queue-bot
The Needs Review Queue Bot → tested this issue.

While you are making the above changes, we recommend that you convert this patch to a merge request → . Merge requests are preferred over patches. Be sure to hide the old patch files as well. (Converting an issue to a merge request without other contributions to the issue will not receive credit.)
Comment about 17 hours ago →
🇮🇳India priya.chat
Hey,
Adding a patch for documentation of the return type as I'm currently facing issues with the merge request setup, so submitting this as a patch instead (though MR is the preferred method).

Tried to add example for better understanding of the return type especially for entity types without bundles—where the array should use an empty string ('') as the top-level key.
Please review and share feedback. Happy to revise if needed.

Document the return value expected by SelectionInterface::getReferenceableEntities() when used on an entity type with no bundles.

Issue description

Proposed text for @return documentation

Comments & Activities