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().
Proposed text for @return documentation
A nested array of entities, the first level is keyed by the entity bundle (or the entity type ID if no bundles exist), which contains an array of entity labels (escaped), keyed by the entity ID.
Comment | File | Size | Author |
---|
Comments
Comment #2
jludwig CreditAttribution: jludwig at SciShield commentedSeems like this is not under the field system, so changing the component.
Also attaching a patch.
Comment #3
jludwig CreditAttribution: jludwig at SciShield commentedChanged to needs review
Comment #5
jludwig CreditAttribution: jludwig at SciShield commentedWoops, I deleted the line defining $target_type while making the patch against 8.4.x.
The attached patch actually works.
Comment #6
dawehner@jludwig
Do you mind trying to write some test for that? I could imagining looking into
\Drupal\KernelTests\Core\Entity\EntityReferenceFieldTest
would help here.Comment #7
jludwig CreditAttribution: jludwig at SciShield commentedUpon further investigation, it looks like core handles this correctly.
If the entity type returns no bundles, getReferenceableEntities() should return the entity type as the top level key:
It doesn't say it specifically here, but that is how Drupal actually handles it.
It was the module I was working with that returned a flat array with getReferenceableEntities that was the problem.
Perhaps this should be turned into a documentation issue instead, with the @return documentation in the interface specifying that if the entity type has no bundles, the entity type id should be the first level key?
Comment #8
jludwig CreditAttribution: jludwig at SciShield commentedDoes anyone else agree that this needs some more documentation?
Something as simple as
Comment #9
jludwig CreditAttribution: jludwig at SciShield commentedComment #10
prash_98 CreditAttribution: prash_98 at Google Summer of Code commentedSo the documentation needs to be done for the file which has the below mentioned section ryt?
/**
* 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);
Or did I get it wrong? :)
Comment #11
prash_98 CreditAttribution: prash_98 at Google Summer of Code commentedAny updates with these with this issue?