Which message should be passed to `SubscribersInterface::getSubscribers()`?

[pfrenssen]

I'm looking at using Message Subscribe for subscribing users to forum discussions.

I'm confused about the following method that is included in SubscribersInterface:

  /**
   * Retrieve a list of subscribers for a given entity.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   The entity to retrieve subscribers for.
   * @param \Drupal\message\MessageInterface $message
   *   The message entity.
   * @param array $options
   *   (optional) An array of options with the same elements as the
   *   `$subscribe_options` array for `self::sendMessage()`.
   * @param array $context
   *   (optional) The context array, passed by reference. This has the same
   *   elements as the `$context` paramater for `self::sendMessage()`.
   *
   * @return \Drupal\message_subscribe\Subscribers\DeliveryCandidateInterface[]
   *   Array of delivery candidate objects keyed with the user IDs to send
   *   notifications to.
   */
  public function getSubscribers(EntityInterface $entity, MessageInterface $message, array $options = [], array &$context = []);

If we call this method we are required to pass in a Message entity. Which message should this be? Is this solely intended to retrieve the list of subscribers when we are already about to send a message?

What are we supposed to do if we want to get a list of subscribers to show in the admin UI?

Looking at the current implementation it even seems that this $message is unneeded. It gets passed on to the message_subscribe_message_subscribe_get_subscribers() hook implementation but there it is unused.

[jhedstrom]

Sorry for the really late reply, I'd somehow missed this.

The message entity should be (usually) an unsaved entity, with whichever message template ID you want to use (example below.)

You can generally skip the getSubscribers call, and just send the message, something like this:

      /** @var \Drupal\message\MessageInterface $message */
      $message = $this->entityTypeManager->getStorage('message')->create([
        'uid' => $node->getOwnerId(),
        'template' => 'my_message_template_id,
      ]);

      $context = [
        'node' => [$node->id()],
      ];
      /** @var \Drupal\message_subscribe\SubscribersInterface */
      $this->subscribers->sendMessage($node, $message, [], [], $context);

you can add other entity types to the $context array and that way folks subscribed to multiple things on a node (eg, the author, or some terms for instance) won't receive duplicate notifications.

[jhedstrom]

Also, you are correct it isn't used by that hook implementation, but I think its made available there if other hooks want to react to the type of message, etc. It is then used by the sendMessage method too.