Entity reference selection plugins break when not following a weird ID pattern

Since #2578249: Some e_r fields get the wrong Selection handler, we try to store only selection plugin IDs in the 'handler' setting of entity reference fields, so the real problem is SelectionPluginManager::getInstance() which shouldn't try to "resolve" it again.

And you're right, the second parameter expected by SelectionPluginManager::getPluginId() is actually a selection group.

Let's try and see how much this breaks :)

Moving to right component

I changed the acronym so I can understand it.

Judging by the code, for most custom cases id should be equal to group (e.g. core\modules\views\src\Plugin\EntityReferenceSelection\ViewsSelection.php)

The other case seems to be a way of minimizing boilerplate for DefaultSelection plugin (see core\lib\Drupal\Core\Entity\Plugin\EntityReferenceSelection\DefaultSelection.php) and expects the definition to be derived by core\lib\Drupal\Core\Entity\Plugin\Derivative\DefaultSelectionDeriver.php otherwise it won't have required 'base_plugin_label' key.

This impacts on Workbench Access too

> An ERSP must declare its ID in the form of : or it will not work whatsoever.

I don't think that's the only possible format.

I've got an ERS plugin working with the plugin & the group as the same value, e.g.

 * @EntityReferenceSelection(
 *   id = "my_plugin",
 *   label = @Translation("My plugin label."),
 *   group = "my_plugin",
 *   entity_types = {"node"},
 *   weight = 10,

The crucial code is in fieldSettingsForm():

    foreach (array_keys($selection_plugins) as $selection_group_id) {
      // We only display base plugins (e.g. 'default', 'views', ...) and not
      // entity type specific plugins (e.g. 'default:node', 'default:user',
      // ...).
      if (array_key_exists($selection_group_id, $selection_plugins[$selection_group_id])) {
        $handlers_options[$selection_group_id] = Html::escape($selection_plugins[$selection_group_id][$selection_group_id]['label']);
      }
      elseif (array_key_exists($selection_group_id . ':' . $this->getSetting('target_type'), $selection_plugins[$selection_group_id])) {
        $selection_group_plugin = $selection_group_id . ':' . $this->getSetting('target_type');
        $handlers_options[$selection_group_plugin] = Html::escape($selection_plugins[$selection_group_id][$selection_group_plugin]['base_plugin_label']);
      }
    }

This is basically making a whole bunch of assumptions about core's ERS plugins, which use derivatives, which doesn't make sense for contrib and custom plugins, which will often be one-offs.

To me, that's the job of the plugin manager to give you the right list of plugins. The form element should not have to do this filtering work.

getPluginId() is really weird. I don't understand at all why we need to be doing this:

  /**
   * Gets the plugin ID for a given target entity type and base plugin ID.
   */
  public function getPluginId($target_type, $base_plugin_id);

and why it sorts on weight, and then takes the last item:

    // Sort the selection plugins by weight and select the best match.
    uasort($selection_handler_groups[$base_plugin_id], ['Drupal\Component\Utility\SortArray', 'sortByWeightElement']);
    end($selection_handler_groups[$base_plugin_id]);
    $plugin_id = key($selection_handler_groups[$base_plugin_id]);

If the 'weight' plugin property is a means to determine which one is picked, then it is REALLY badly named. I had assumed it was simply to order the plugin labels in the UI!

As for the group property, I don't understand it at all:

  /**
   * The selection plugin group.
   *
   * This property is used to allow selection plugins to target a specific
   * entity type while also inheriting the code of an existing selection plugin.
   * For example, if we want to override the NodeSelection from the 'default'
   * selection type, we can define the annotation of a new plugin as follows:

If I want to inherit the code of an existing selection plugin... I could just inherit from that class, no?

Just spent a while wondering why my selection plugin didn't work until I realized from the plugin manager code I needed to make the plugin match the name of the group.

The issue summary is wrong as #15 says, but it's certainly not documented clearly.

> Just spent a while wondering why my selection plugin didn't work until I realized from the plugin manager code I needed to make the plugin match the name of the group.

This issue is going to take time to fix. In the meantime, let's stop wasting developer time figuring out how to use these over and over again, and document the quirks: #2945789: Document quirks of Entity reference selection plugins while a fix is figured out.

Now that #2945789: Document quirks of Entity reference selection plugins while a fix is figured out is in, the pattern is documented. But it's really weird.

I ran into this problem recently. I noticed that Drupal\views\Plugin\EntityReferenceSelection\ViewsSelection used the same id and group, so I copied that pattern and decided not to worry about it until I came across this issue.

I am updating the issue summary so that the first few lines describe what does work, based on #2945789: Document quirks of Entity reference selection plugins while a fix is figured out.

Also stumbled upon this issue after debugging for a bit. It seems you need to supply a group that matches the id

I just filed #3270898: Misleading documentation in \Drupal\Core\Entity\Annotation\EntityReferenceSelection because of this wonky issue. The documentation that was added in #2945789: Document quirks of Entity reference selection plugins while a fix is figured out is misleading because the ID can't be prefixed in all the cases that we've tried.

Added reroll of patch #2 on Drupal 9.3.x.

The re-roll was not correct, in unsets a key inside the array and then uses it.
I reworked the patch to fix it differently, the options were combined, causing the array to merge wrong, if we anyhow insert the 'handler' key, we might as well just set it directly.
This allows the code below it to still execute correctly.

Then another issue occurred with the selection_handler being missing. I have to idea why this is not set by default to the value "default", as stated earlier inside EntityAutoComplete.php, but by adding a value when it is missing, it works out great (you might want to reformat this to an empty check if you are using a PHP version lower than 7.4).

Todo:
- Find out why the selection_handler is not set to a value of "default" by default, or where it gets overwritten.

In between time, this patch should help you guys out.

What I'm confused about is, if I want to create a sub-plugin of UserSelection, for example, how do I specify that in the annotation?

This does work as a plugin, however it won't show in the list in the UI, so you have to hardcode it in the config YAML or PHP.

 * @EntityReferenceSelection(
 *   id = "default:user:custom",
 *   label = @Translation("Custom User"),
 *   entity_types = {"user"},
 *   group = "default",
 *   weight = 5
 * )
 */
class CustomUserSelection extends UserSelection {

Same problem, my Selection doesn't appear in the Reference method list in the UI with the code :

namespace Drupal\my_module\Plugin\EntityReferenceSelection;

use Drupal\Core\Entity\Plugin\EntityReferenceSelection\DefaultSelection;
use Drupal\Core\Entity\Query\QueryInterface;

/**
 * Provides entity reference selections to list only the field of the "product" bundle.
 *
 * @EntityReferenceSelection(
 *   id = "custom:my_id",
 *   label = @Translation("My label"),
 *   base_plugin_label = @Translation("My label"),
 *   group = "custom",
 *   weight = 2
 * )
 */
class MyClasseSelection extends DefaultSelection {

   /**
   * {@inheritdoc}
   */
  protected function buildEntityQuery($match = NULL, $match_operator = 'CONTAINS'): QueryInterface {

    $query = parent::buildEntityQuery($match, $match_operator);
    $query->condition('bundle', 'product');

    return $query;
  }

}

It's interpreted well when i put it in the config file :

settings:
  handler: 'custom:my_id'
  handler_settings:
    target_bundles: null
    sort:
      field: weight
      direction: ASC
    auto_create: false

Context : I want to use an entity reference field on my fields but i can't target the bundle in the UI.