[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * Net_SMS_clickatell_http Class implements the HTTP API for accessing the
   4   * Clickatell (www.clickatell.com) SMS gateway.
   5   *
   6   * Copyright 2003-2006 Marko Djukic <marko@oblo.com>
   7   *
   8   * See the enclosed file COPYING for license information (LGPL). If you did
   9   * not receive this file, see http://www.fsf.org/copyleft/lgpl.html.
  10   *
  11   * $Horde: framework/Net_SMS/SMS/clickatell_http.php,v 1.13.10.9 2006/08/07 00:42:30 chuck Exp $
  12   *
  13   * @author Marko Djukic <marko@oblo.com>
  14   * @package Net_SMS
  15   */
  16  class Net_SMS_clickatell_http extends Net_SMS {
  17  
  18      var $_session_id = null;
  19      var $_base_url = 'http://api.clickatell.com/http/';
  20  
  21      /**
  22       * An array of capabilities, so that the driver can report which operations
  23       * it supports and which it doesn't. Possible values are:<pre>
  24       *   auth        - The gateway require authentication before sending;
  25       *   batch       - Batch sending is supported;
  26       *   multi       - Sending of messages to multiple recipients is supported;
  27       *   receive     - Whether this driver is capable of receiving SMS;
  28       *   credit      - Is use of the gateway based on credits;
  29       *   addressbook - Are gateway addressbooks supported;
  30       *   lists       - Gateway support for distribution lists.
  31       * </pre>
  32       *
  33       * @var array
  34       */
  35      var $capabilities = array('auth'        => true,
  36                                'batch'       => 100,
  37                                'multi'       => true,
  38                                'receive'     => false,
  39                                'credit'      => true,
  40                                'addressbook' => false,
  41                                'lists'       => false);
  42  
  43      /**
  44       * Authenticate at the gateway and set a session id if successful. Caching
  45       * is used to minimise the http calls for subsequent messages.
  46       *
  47       * @access private
  48       *
  49       * @return mixed  True on success or PEAR Error on failure.
  50       */
  51      function _authenticate()
  52      {
  53          /* We have already authenticated so return true. */
  54          if (!empty($this->_session_id)) {
  55              return true;
  56          }
  57  
  58          /* Set up the http authentication url. */
  59          $url = sprintf('auth?user=%s&password=%s&api_id=%s',
  60                         urlencode($this->_params['user']),
  61                         urlencode($this->_params['password']),
  62                         $this->_params['api_id']);
  63  
  64          /* Do the HTTP authentication and get the response. */
  65          $response = Net_SMS_clickatell_http::_callURL($url);
  66          if (is_a($response, 'PEAR_Error')) {
  67              return PEAR::raiseError(sprintf(_("Authentication failed. %s"), $response->getMessage()));
  68          }
  69  
  70          /* Split up the response. */
  71          $response = explode(':', $response);
  72          if ($response[0] == 'OK') {
  73              $this->_session_id = trim($response[1]);
  74              return true;
  75          } else {
  76              return $this->getError($response[1], _("Authentication failed. %s"));
  77          }
  78      }
  79  
  80      /**
  81       * This function does the actual sending of the message.
  82       *
  83       * @access private
  84       *
  85       * @param array $message  The array containing the message and its send
  86       *                        parameters.
  87       * @param string $to      The destination string.
  88       *
  89       * @return array  An array with the success status and additional
  90       *                information.
  91       */
  92      function _send(&$message, $to)
  93      {
  94          /* Set up the http sending url. */
  95          $url = sprintf('sendmsg?session_id=%s&text=%s',
  96                         $this->_session_id,
  97                         urlencode($message['text']));
  98  
  99          $req_feat = 0;
 100          if (!empty($message['send_params']['from'])) {
 101              /* If source from is set, require it for transit gateways and append
 102                 to url. */
 103              $req_feat =+ 16;
 104              $url .= '&from=' . urlencode($message['send_params']['from']);
 105          }
 106          if (!empty($message['send_params']['msg_type']) &&
 107              $message['send_params']['msg_type'] == 'SMS_FLASH') {
 108              /* If message type is flash, require it for transit gateways. */
 109              $req_feat =+ 512;
 110              $url .= '&msg_type=' . $message['send_params']['msg_type'];
 111          }
 112          if (!empty($req_feat)) {
 113              /* If features have been required, add to url. */
 114              $url .= '&req_feat=' . $req_feat;
 115          }
 116  
 117          /* Append the recipients of this message and call the url. */
 118          foreach ($to as $key => $val) {
 119              if (preg_match('/^.*?<?\+?(\d{7,})(>|$)/', $val, $matches)) {
 120                  $to[$key] = $matches[1];
 121              } else {
 122                  /* FIXME: Silently drop bad recipients. This should be logged
 123                   * and/or reported. */
 124                  unset($to[$key]);
 125              }
 126          }
 127          $to = implode(',', $to);
 128          $url .= '&to=' . $to;
 129          $response = trim($this->_callURL($url));
 130  
 131          /* Ugly parsing of the response, but that's how it comes back. */
 132          $lines = explode("\n", $response);
 133          $response = array();
 134  
 135          if (count($lines) > 1) {
 136              foreach ($lines as $line) {
 137                  $parts = explode('To:', $line);
 138                  $recipient = trim($parts[1]);
 139                  $outcome = explode(':', $parts[0]);
 140                  $response[$recipient] = array(($outcome[0] == 'ID' ? 1 : 0), $outcome[1]);
 141              }
 142          } else {
 143              /* Single recipient. */
 144              $outcome = explode(':', $lines[0]);
 145              $response[$to] = array(($outcome[0] == 'ID' ? 1 : 0), $outcome[1]);
 146          }
 147  
 148          return $response;
 149      }
 150  
 151      /**
 152       * Returns the current credit balance on the gateway.
 153       *
 154       * @access private
 155       *
 156       * @return integer  The credit balance available on the gateway.
 157       */
 158      function _getBalance()
 159      {
 160          /* Set up the url and call it. */
 161          $url = sprintf('getbalance?session_id=%s',
 162                         $this->_session_id);
 163          $response = trim($this->_callURL($url));
 164  
 165          /* Try splitting up the response. */
 166          $lines = explode('=', $response);
 167  
 168          /* Split up the response. */
 169          $response = explode(':', $response);
 170          if ($response[0] == 'Credit') {
 171              return trim($response[1]);
 172          } else {
 173              return $this->getError($response[1], _("Could not check balance. %s"));
 174          }
 175      }
 176  
 177      /**
 178       * Identifies this gateway driver and returns a brief description.
 179       *
 180       * @return array  Array of driver info.
 181       */
 182      function getInfo()
 183      {
 184          $info['name'] = _("Clickatell via HTTP");
 185          $info['desc'] = _("This driver allows sending of messages through the Clickatell (http://clickatell.com) gateway, using the HTTP API");
 186  
 187          return $info;
 188      }
 189  
 190      /**
 191       * Returns the required parameters for this gateway driver.
 192       *
 193       * @return array  Array of required parameters.
 194       */
 195      function getParams()
 196      {
 197          $params = array();
 198          $params['user']     = array('label' => _("Username"), 'type' => 'text');
 199          $params['password'] = array('label' => _("Password"), 'type' => 'text');
 200          $params['api_id']   = array('label' => _("API ID"), 'type' => 'text');
 201  
 202          return $params;
 203      }
 204  
 205      /**
 206       * Returns the parameters that can be set as default for sending messages
 207       * using this gateway driver and displayed when sending messages.
 208       *
 209       * @return array  Array of parameters that can be set as default.
 210       * @todo  Set up batch fields/params, would be nice to have ringtone/logo
 211       *        support too, queue choice, unicode choice.
 212       */
 213      function getDefaultSendParams()
 214      {
 215          $params = array();
 216          $params['from'] = array(
 217              'label' => _("Source address"),
 218              'type' => 'text');
 219  
 220          $params['deliv_time'] = array(
 221              'label' => _("Delivery time"),
 222              'type' => 'enum',
 223              'params' => array(array('now' => _("immediate"), 'user' => _("user select"))));
 224  
 225          $types = array('SMS_TEXT' => 'SMS_TEXT', 'SMS_FLASH' => 'SMS_FLASH');
 226          $params['msg_type'] = array(
 227              'label' => _("Message type"),
 228              'type' => 'multienum',
 229              'params' => array($types));
 230  
 231          return $params;
 232      }
 233  
 234      /**
 235       * Returns the parameters for sending messages using this gateway driver,
 236       * displayed when sending messages. These are filtered out using the
 237       * default values set for the gateway.
 238       *
 239       * @return array  Array of required parameters.
 240       * @todo  Would be nice to use a time/date setup rather than minutes from
 241       *        now for the delivery time. Upload field for ringtones/logos?
 242       */
 243      function getSendParams($params)
 244      {
 245          if (empty($params['from'])) {
 246              $params['from'] = array(
 247                  'label' => _("Source address"),
 248                  'type' => 'text');
 249          }
 250  
 251          if ($params['deliv_time'] == 'user') {
 252              $params['deliv_time'] = array(
 253                  'label' => _("Delivery time"),
 254                  'type' => 'int',
 255                  'desc' => _("Value in minutes from now."));
 256          }
 257  
 258          if (count($params['msg_type']) > 1) {
 259              $params['msg_type'] = array(
 260                  'label' => _("Message type"),
 261                  'type' => 'enum',
 262                  'params' => array($params['msg_type']));
 263          } else {
 264              $params['msg_type'] = $params['msg_type'][0];
 265          }
 266  
 267          return $params;
 268      }
 269  
 270      /**
 271       * Returns a string representation of an error code.
 272       *
 273       * @param integer $error  The error code to look up.
 274       * @param string $text    An existing error text to use to raise a
 275       *                        PEAR Error.
 276       *
 277       * @return mixed  A textual message corresponding to the error code or a
 278       *                PEAR Error if passed an existing error text.
 279       *
 280       * @todo  Check which of these are actually required and trim down the
 281       *        list.
 282       */
 283      function getError($error, $error_text = '')
 284      {
 285          /* Make sure we get only the number at the start of an error. */
 286          list($error) = explode(',', $error);
 287          $error = trim($error);
 288  
 289          /* An array of error codes returned by the gateway. */
 290          $errors = array('001' => _("Authentication failed"),
 291                          '002' => _("Unknown username or password."),
 292                          '003' => _("Session ID expired."),
 293                          '004' => _("Account frozen."),
 294                          '005' => _("Missing session ID."),
 295                          '007' => _("IP lockdown violation."),
 296                          '101' => _("Invalid or missing parameters."),
 297                          '102' => _("Invalid UDH. (User Data Header)."),
 298                          '103' => _("Unknown apimsgid (API Message ID)."),
 299                          '104' => _("Unknown climsgid (Client Message ID)."),
 300                          '105' => _("Invalid destination address."),
 301                          '106' => _("Invalid source address."),
 302                          '107' => _("Empty message."),
 303                          '108' => _("Invalid or missing api_id."),
 304                          '109' => _("Missing message ID."),
 305                          '110' => _("Error with email message."),
 306                          '111' => _("Invalid protocol."),
 307                          '112' => _("Invalid msg_type."),
 308                          '113' => _("Max message parts exceeded."),
 309                          '114' => _("Cannot route message to specified number."),
 310                          '115' => _("Message expired."),
 311                          '116' => _("Invalid unicode data."),
 312                          '201' => _("Invalid batch ID."),
 313                          '202' => _("No batch template."),
 314                          '301' => _("No credit left."),
 315                          '302' => _("Max allowed credit."));
 316  
 317          if (empty($error_text)) {
 318              return $errors[$error];
 319          } else {
 320              return PEAR::raiseError(sprintf($error_text, $errors[$error]));
 321          }
 322      }
 323  
 324      /**
 325       * Do the http call using a url passed to the function.
 326       *
 327       * @access private
 328       *
 329       * @param string $url  The url to call.
 330       *
 331       * @return mixed  The response on success or PEAR Error on failure.
 332       */
 333      function _callURL($url)
 334      {
 335          $options['method'] = 'GET';
 336          $options['timeout'] = 5;
 337          $options['allowRedirects'] = true;
 338  
 339          if (!@include_once 'HTTP/Request.php') {
 340              return PEAR::raiseError(_("Missing PEAR package HTTP_Request."));
 341          }
 342          $http = &new HTTP_Request($this->_base_url . $url, $options);
 343          @$http->sendRequest();
 344          if ($http->getResponseCode() != 200) {
 345              return PEAR::raiseError(sprintf(_("Could not open %s."), $url));
 346          }
 347  
 348          return $http->getResponseBody();
 349      }
 350  
 351  }