smsplatform-1.0.x-dev/src/Provider/SmsProviderInterface.php

<?php

declare(strict_types=1);

namespace Drupal\smsplatform\Provider;

use Drupal\smsplatform\Entity\SmsGatewayInterface;
use Drupal\smsplatform\Message\SmsMessageInterface;
use Symfony\Component\HttpFoundation\Request;

/**
 * Provides an interface for sending messages.
 */
interface SmsProviderInterface {

  /**
   * Queue a SMS message for sending or receiving.
   *
   * @param \Drupal\smsplatform\Message\SmsMessageInterface $sms_message
   *   A SMS message.
   *
   * @return \Drupal\smsplatform\Entity\SmsMessageInterface[]
   *   The queued messages. A single message may be transformed into many.
   *
   * @throws \Drupal\smsplatform\Exception\SmsDirectionException
   *   Thrown if no direction is set for the message.
   * @throws \Drupal\smsplatform\Exception\RecipientRouteException
   *   Thrown if no gateway could be determined for the message.
   */
  public function queue(SmsMessageInterface $sms_message);

  /**
   * Sends an SMS using the active gateway.
   *
   * It is preferred to use queue method over directly invoking send().
   *
   * @param \Drupal\smsplatform\Message\SmsMessageInterface $sms
   *   The message to be sent.
   *
   * @return \Drupal\smsplatform\Message\SmsMessageInterface[]
   *   The messages sent in this sending operation. The message sent can be
   *   transformed into multiple messages depending on gateway and event
   *   subscribers. Therefore, this function can return multiple messages.
   *
   * @throws \Drupal\smsplatform\Exception\RecipientRouteException
   *   Thrown if no gateway could be determined for the message.
   */
  public function send(SmsMessageInterface $sms);

  /**
   * Handles a message sent from the gateway to the site.
   *
   * @param \Drupal\smsplatform\Message\SmsMessageInterface $sms_message
   *   The incoming message to process.
   *
   * @return \Drupal\smsplatform\Message\SmsMessageInterface[]
   *   The messages received in an incoming operation.
   */
  public function incoming(SmsMessageInterface $sms_message);

  /**
   * Handles delivery reports pushed to the site.
   *
   * @param \Symfony\Component\HttpFoundation\Request $request
   *   The HTTP request that contains the delivery report.
   * @param \Drupal\smsplatform\Entity\SmsGatewayInterface $gateway
   *   The gateway designated to process the delivery report.
   */
  public function processDeliveryReport(Request $request, SmsGatewayInterface $gateway);

}