Crumbs MultiPlugin

As mentioned on the previous page:

The findTitle() or findParent() method of a MonoPlugin returns only ONE candidate, or NULL to let other plugins decide, or FALSE to terminate the title- or parent-finding with no result.

The findTitle() or findParent() method of a MultiPlugin returns an associative array of candidates, where each candidate can be a string or FALSE.
The keys of this array of candidates become part of the candidate keys.

A MultiPlugin may look like this:

namespace Drupal\MYMODULE;
class MyCrumbsMultiPlugin implements crumbs_MultiPlugin_FindParentInterface {
  /**
   * Find candidates for the parent path.
   *
   * @param string $path
   *   The path that we want to find a parent for.
   * @param array $item
   *   Item as returned from crumbs_get_router_item()
   *
   * @return array
   *   Parent path candidates
   */
  function findParent($path, $item) {
    // We know that node/5 is both a bar and a restaurant, so it fits into both categories.
    // We allow the user to prioritize on admin/structure/crumbs/weights.
    if ($path === 'node/5') {
      return array(
        'bars' => 'gastro/bars',
        'restaurants' => 'gastro/restaurants',
      );
    }
  }
}

and registered like this:

/**
 * Implements hook_crumbs_plugins()
 *
 * @param crumbs_InjectedAPI_hookCrumbsPlugins $api
 */
function MYMODULE_crumbs_plugins($api) {
  $plugin = new \Drupal\MYMODULE\MyCrumbsMultiPlugin();
  $api->multiPlugin('myMultiPlugin', $plugin);
}

Plugin keys and candidate keys (MultiPlugin)

As on the previous page, each plugin is identified by a plugin key. The plugin key is built from the module name and the key that was used to register the plugin. In the example, this is "MYMODULE.myMultiPlugin".

Each candidate returned by a plugin also gets a key, the "candidate key", which is used to assign a priority / weight to the candidate.
The candidate key for a MonoPlugin candidate is the same as the plugin key.
The candidate key for a MultiPlugin candidate is the plugin key, plus the key from the associative array that was returned by the MultiPlugin.

The example MultiPlugin above returns two candidates for the parent path.
With the complete candidate keys, these are:
MYMODULE.myPlugin.bars => gastro/bars
MYMODULE.myPlugin.restaurants => gastro/restaurants

This means, the admin can configure on admin/structure/crumbs/weights, which of these two candidates should have priority.
Wait, not so fast.
You need a describe() method to let Crumbs know about the possible candidate keys.

The describe() method (MultiPlugin)

The describe() method is used to register the all possible candidate keys of a plugin's findTitle() or findParent() method, so they can be prioritized on the admin/structure/crumbs/weights form.

(Documentation to come..)

When to use MultiPlugin

The main use case of multi plugins is if fetching all candidates at once is cheaper than fetching each candidate with a separate plugin.

This is because the plugin does not know the priorities that the user configured for each candidate key.

Even though only one candidate wins, it can happen that a number of plugins are asked to return a candidate, but return nothing, before the successful plugin is triggered.

E.g. the menu.hierarchy plugin is implemented as a MultiPlugin. It looks for a parent path in all menus at once, and then returns the candidate as an array, keyed by menu name.

If it were implemented as MonoPlugin (one per menu), it could easily happen that 5 of these plugins are triggered with no result, because the path is in none of these menus.