/source/ws/TextMarksV2APIClient.php
PHP | 284 lines | 116 code | 41 blank | 127 comment | 14 complexity | 27db8d1a6fa6d1ce2d734aacd557eb93 MD5 | raw file
Possible License(s): LGPL-2.1
- <?php
- /**
- * TextMarks V2 API Client Library (PHP). v2.60d.
- * ---------------------------------------------------------------------------
- *
- * TextMarks provides a text-messaging platform you can integrate into
- * your own applications to send and receive text messages to individual
- * users or groups of users.
- *
- * For full online documentation, visit:
- * http://www.textmarks.com/dev/docs/api2/
- * http://www.textmarks.com/dev/
- * http://www.textmarks.com/
- *
- * The HTTP API that this library integrates with is NOT REQUIRED.
- * You can do all kinds of wonderful things without this API and without
- * writing any code at all. However if you wish to automate and integrate
- * TextMarks more deeply into your applications, this API may be useful.
- *
- * This optional PHP client library provides one way to integrate with
- * the platform's HTTP API from your PHP applications.
- *
- * This library requires:
- * - PHP 5.1 or greater.
- * - libCURL (normally included with PHP).
- *
- * ---------------------------------------------------------------------------
- * @author Dan Kamins [d k a m i n s A.T t e x t m a r k s D.O.T c o m]
- * @package tmAPIClient
- * ---------------------------------------------------------------------------
- * Copyright (c) 2009, TextMarks Inc. All rights reserved.
- * ---------------------------------------------------------------------------
- *
- * THIS PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR
- * CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT
- * LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT,
- * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
- *
- * RECIPIENT IS SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS
- * OF USING AND DISTRIBUTING THE PROGRAM AND ASSUMES ALL RISKS ASSOCIATED
- * WITH ITS EXERCISE OF RIGHTS UNDER THIS AGREEMENT, INCLUDING BUT NOT
- * LIMITED TO THE RISKS AND COSTS OF PROGRAM ERRORS, COMPLIANCE WITH
- * APPLICABLE LAWS, DAMAGE TO OR LOSS OF DATA, PROGRAMS OR EQUIPMENT,
- * AND UNAVAILABILITY OR INTERRUPTION OF OPERATIONS.
- *
- * NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR
- * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- * DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR
- * DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED
- * HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
- */
- /** */
- // ---------------------------------------------------------------------------
- /*
- * For PHP prior to 5.2 (which introduced native JSON support),
- * we include a free JSON library and bind it to json_decode.
- */
- if (!function_exists('json_decode')) {
- require_once('JSON.php');
- function json_decode($json) {
- $svc = new Services_JSON(SERVICES_JSON_LOOSE_TYPE);
- return $svc->decode($json);
- }
- }
- // ---------------------------------------------------------------------------
- /**
- * Exception subclass used by TextMarksAPIClient.
- */
- class TextMarksV2APIClientException extends Exception
- {
- }
- /**
- * Exception subclass used by TextMarksV2APIClient for transport-level errors.
- */
- class TextMarksV2APIClientTransportException extends TextMarksV2APIClientException
- {
- }
- // ---------------------------------------------------------------------------
- /**
- * TextMarksV2APIClient - construct and call().
- */
- class TextMarksV2APIClient
- {
- public $db_sms = null;
- public $error_code = '';
- public $error_code_info = '';
-
- // Public constants:
- const HTTP_GET = 'GET';
- const HTTP_POST = 'POST';
-
- // -----------------------------------------------------------------------
-
- // Configuration:
- const API_URL_BASE = 'http://php1.api2.textmarks.com';
- // -----------------------------------------------------------------------
- /**
- * Create TextMarksV2APIClient around indicated authentication info (optional).
- *
- * @param string $sApiKey API Key ( register at http://www.textmarks.com/dev/api/reg/ ). (NULL for none).
- * @param string $sAuthUser Phone# or TextMarks username to authenticate to API with. (NULL for none).
- * @param string $sAuthPass TextMarks Password associated with sAuthUser. (NULL for none).
- */
- public function TextMarksV2APIClient( $sApiKey = NULL, $sAuthUser = NULL, $sAuthPass = NULL )
- {
- $this->m_sApiKey = $sApiKey;
- $this->m_sAuthUser = $sAuthUser;
- $this->m_sAuthPass = $sAuthPass;
- }
- // Initialize database connections
- function connectDB()
- {
- // x. Create a connection to the front database
- if (!$this->db_sms = @mysql_connect(SMS_SERVER, SMS_USER, SMS_PASSWORD, true))
- {
- // Logging
- writeLog(ERROR_CODE_INFO. ": Couldn't connect to database");
- return false;
- }
- if (!@mysql_select_db(SMS_DATABASE, $this->db_sms)) {
- // Logging
- writeLog(ERROR_CODE_INFO. ": Couldn't connect to database");
- return false;
- }
-
- mysql_query("SET NAMES 'utf8'", $this->db_sms);
- return true;
- }
-
- function closeConnections(){
- mysql_close($this->db_sms);
- }
-
- function outputXML ($code,$description,$result=''){
- $description = htmlspecialchars($description,ENT_NOQUOTES,"UTF-8");
- $xml = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n";
- $xml .= "<result>\n";
- $xml .= "<status>\n";
- $xml .= "<code>$code</code>\n";
- $xml .= "<description>".htmlspecialchars($description,ENT_NOQUOTES,"UTF-8")."</description>\n";
- $xml .= "</status>\n";
- $xml .= $result;
- $xml .= "</result>";
- return $xml;
- }
- /**
- * Public method to call API.
- *
- * The API Key and auth params are automatically added if present.
- *
- * @param string $sPackageName Package name.
- * @param string $sMethodName Method name.
- * @param map(string,string) $mssParams Params for method.
- * @param string $sHttpMethod 'GET' or 'POST'.
- * @return Decoded (from JSON) response.
- * @throws Exception on error.
- */
- public function call( $sPackageName, $sMethodName, $mssParams, $sHttpMethod = self::HTTP_POST )
- {
- return $this->_callJsonApiMethod($sPackageName, $sMethodName, $mssParams, $sHttpMethod);
- }
- // -----------------------------------------------------------------------
-
- /**
- * Execute HTTP request (post params to API endpoint) and return string response.
- *
- * @param string $sUrl URL to request (method endpoint).
- * @param map(string,string) $mssParams Request params.
- * @param string $sHttpMethod 'GET' or 'POST'.
- * @return string Response (usually JSON string).
- * @throws TextMarksV2APIClientTransportException on error.
- */
- protected function _rawHttpCall( $sUrl, $mssParams, $sHttpMethod = self::HTTP_POST )
- {
- // Convert param map to encoded form (to post):
- $sPostData = "";
- foreach ($mssParams as $sK => $sV) {
- $sPostData .= "&" . urlencode($sK) . "=" . urlencode($sV);
- }
- // Prep curl:
- $ch = curl_init();
- $arsHeaders = array();
-
- if ($sHttpMethod == 'POST') {
- curl_setopt($ch, CURLOPT_POST, 1);
- curl_setopt($ch, CURLOPT_URL, $sUrl);
- $arsHeaders[] = "Content-Type: application/x-www-form-urlencoded";
- curl_setopt($ch, CURLOPT_POSTFIELDS, $sPostData);
- } else {
- curl_setopt($ch, CURLOPT_HTTPGET, 1);
- curl_setopt($ch, CURLOPT_URL, $sUrl . "?" . $sPostData);
- }
- curl_setopt($ch, CURLOPT_HTTPHEADER, $arsHeaders);
- curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // (response as string, not output)
- // Make request (synchronous):
- $sResponse = curl_exec($ch);
- // Check for transport-level errors:
- $iCurlErrNo = curl_errno($ch);
- $iHttpRespCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
- if ($iCurlErrNo != 0) {
- curl_close($ch);
- throw new TextMarksV2APIClientTransportException("TextMarksV2APIClient ($sUrl) saw CURL error #$iCurlErrNo: " . curl_error($ch), curl_error($ch));
- }
- if ($iHttpRespCode != 200) {
- curl_close($ch);
- throw new TextMarksV2APIClientTransportException("TextMarksV2APIClient ($sUrl) saw non-200 HTTP response #$iHttpRespCode.", -1);
- }
- // No obvious transport-level errors. Return response:
- return $sResponse;
- }
- /**
- * Execute API call and return decoded JSON response.
- *
- * The API Key and auth params are automatically added.
- *
- * @param string $sPackageName Package name.
- * @param string $sMethodName Method name.
- * @param map(string,string) $mssParams Params for method.
- * @param string $sHttpMethod 'GET' or 'POST'.
- * @return Decoded (from JSON) response.
- * @throws Exception on error.
- */
- protected function _callJsonApiMethod( $sPackageName, $sMethodName, $mssParams, $sHttpMethod = self::HTTP_POST )
- {
- // Prep:
- $mssParamsFull = $mssParams; // (copy array to keep original clean)
- if ($this->m_sApiKey !== NULL) { $mssParamsFull['api_key'] = $this->m_sApiKey; }
- if ($this->m_sAuthUser !== NULL) { $mssParamsFull['auth_user'] = $this->m_sAuthUser; }
- if ($this->m_sAuthPass !== NULL) { $mssParamsFull['auth_pass'] = $this->m_sAuthPass; }
- $sUrl = self::API_URL_BASE . '/' . $sPackageName . '/' . $sMethodName . '/';
- // Make actual HTTP call:
- $sResp = $this->_rawHttpCall( $sUrl, $mssParamsFull, $sHttpMethod );
- // Parse JSON response:
- $oDecoded = json_decode($sResp, TRUE);
- // Check API response code:
- $iResCode = (int) $oDecoded['head']['rescode'];
- $sResMsg = $oDecoded['head']['resmsg'];
- if ($iResCode != 0) {
- throw new TextMarksV2APIClientException("TextMarksV2APIClient.call($sPackageName.$sMethodName) got API error #$iResCode: $sResMsg", $iResCode);
- }
-
- return $oDecoded;
- }
- // -----------------------------------------------------------------------
- protected $m_sApiKey;
- protected $m_sAuthUser;
- protected $m_sAuthPass;
- }
- ?>