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 3 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 21 days ago3:13am 2 April 2025
Comment 21 days ago →
🇮🇳India andol
We need more info on this ticket to proceed further. Updates to this ticket hasn't been made in a while.

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