Returning Result Objects with Transmission Methods

SMS Gateway plugins must return result objects for their \Drupal\sms\Plugin\SmsGatewayPluginIncomingInterface::incoming and \Drupal\sms\Plugin\SmsGatewayPluginInterface::send methods. For the rest of this article, the term 'operation' refers to these methods.

Create a container result object #

Each operation must return a result object. If for some reason your operation does not return an object, then SMS Framework will interpret your operation as catastrophically failing with an unknown error (See Status interpretation table). Operations should always return a result object, and catch any API related exceptions.

Setting error on result object #

Setting an error is optional. Errors should only be set on the result object if all messages failed to transmit. For example: when the API is offline.

Although you can set the error code to be any string, it is best to set codes SMS Framework recognises so it can apply meaning to the errors. Messages may be handled differently differently depending on the codes set. See the status codes article for SMS Frameworks codes.

Errors are set with \Drupal\sms\Message\SmsMessageResultInterface::setError. See \Drupal\sms\Message\SmsMessageResultError for a list of valid error codes.

Creating a report for each SMS #

For each SMS that was sent during each operation, you must create a report object and add it to the returned Result object. An array of reports are set with \Drupal\sms\Message\SmsMessageResultInterface::setReports. Each report is a created with:

$report = new \Drupal\sms\Message\SmsDeliveryReport();

For each report, set the status and recipient phone number. See the status codes article for SMS Frameworks codes. Unlike the result object, reports must always set a status code.

$report
  ->setStatus(\Drupal\sms\Message\SmsMessageReportStatus::A_STATUS_CODE)
  ->setRecipient('+123123123');

If the status is unique and does not map to any internal error codes, then you should set the status code to generic SmsMessageStatus::ERROR and set a custom status message.

$report
  ->setStatus(\Drupal\sms\Message\SmsMessageStatus::ERROR)
  ->setStatusMessage('A status message unique to this report.');

Gateways sometime assign a unique ID to each message. These ID's should be set on each report:

$report->setMessageId($unique_message_id);

Example: setting reports on result #

send() example:

public function send(SmsMessageInterface $sms_message) {
  $result = new SmsMessageResult();
  $reports = [];
  
  foreach ($sms_message->getRecipients() as $recipient) {
    // ...Send message with API
    $reports[] = (new SmsDeliveryReport())
      ->setRecipient($recipient)
      ->setStatus(SmsMessageReportStatus::SOMESTATUS);
  }
  
  $result->setReports($reports);
  return $result;
}

If 500 message transmissions were attempte during an operation, then you would create 500 reports, etc. A report should be created whether or not the SMS was successfully transmitted.

Status table #

The following table is how SMS Framework interprets results returned by operations.

Legend

• Error set?: is determined by result::getError() !== NULL
• Has reports: is determined by count(reports) > 0