vendor/drewm/mailchimp-api/src/MailChimp.php line 48

Open in your IDE?
  1. <?php
  3. namespace DrewM\MailChimp;
  5. /**
  6.  * Super-simple, minimum abstraction MailChimp API v3 wrapper
  7.  * MailChimp API v3: http://developer.mailchimp.com
  8.  * This wrapper: https://github.com/drewm/mailchimp-api
  9.  *
  10.  * @author  Drew McLellan <drew.mclellan@gmail.com>
  11.  * @version 2.5
  12.  */
  13. class MailChimp {
  15.     private $api_key;
  16.     private $api_endpoint = 'https://<dc>.api.mailchimp.com/3.0';
  18.     const TIMEOUT = 10;
  20.     /*  SSL Verification
  21.       Read before disabling:
  22.       http://snippets.webaware.com.au/howto/stop-turning-off-curlopt_ssl_verifypeer-and-fix-your-php-config/
  23.      */
  25.     public $verify_ssl = false;
  26.     private $request_successful = false;
  27.     private $last_error = '';
  28.     private $last_response = array();
  29.     private $last_request = array();
  31.     /**
  32.      * Create a new instance
  33.      *
  34.      * @param string $api_key      Your MailChimp API key
  35.      * @param string $api_endpoint Optional custom API endpoint
  36.      *
  37.      * @throws \Exception
  38.      */
  39.     public function __construct($api_key, $api_endpoint = null) {
  40.         if (!function_exists('curl_init') || !function_exists('curl_setopt')) {
  41.             throw new \Exception("cURL support is required, but can't be found.");
  42.         }
  44.         $this->api_key = $api_key;
  46.         if ($api_endpoint === null) {
  47.             if (strpos($this->api_key, '-') === false) {
  48.                 throw new \Exception("Invalid MailChimp API key supplied.");
  49.             }
  50.             list(, $data_center) = explode('-', $this->api_key);
  51.             $this->api_endpoint = str_replace('<dc>', $data_center, $this->api_endpoint);
  52.         } else {
  53.             $this->api_endpoint = $api_endpoint;
  54.         }
  56.         $this->last_response = array('headers' => null, 'body' => null);
  57.     }
  59.     /**
  60.      * Create a new instance of a Batch request. Optionally with the ID of an existing batch.
  61.      *
  62.      * @param string $batch_id Optional ID of an existing batch, if you need to check its status for example.
  63.      *
  64.      * @return Batch            New Batch object.
  65.      */
  66.     public function new_batch($batch_id = null) {
  67.         return new Batch($this, $batch_id);
  68.     }
  70.     /**
  71.      * @return string The url to the API endpoint
  72.      */
  73.     public function getApiEndpoint() {
  74.         return $this->api_endpoint;
  75.     }
  77.     /**
  78.      * Convert an email address into a 'subscriber hash' for identifying the subscriber in a method URL
  79.      *
  80.      * @param   string $email The subscriber's email address
  81.      *
  82.      * @return  string          Hashed version of the input
  83.      */
  84.     public static function subscriberHash($email) {
  85.         return md5(strtolower($email));
  86.     }
  88.     /**
  89.      * Was the last request successful?
  90.      *
  91.      * @return bool  True for success, false for failure
  92.      */
  93.     public function success() {
  94.         return $this->request_successful;
  95.     }
  97.     /**
  98.      * Get the last error returned by either the network transport, or by the API.
  99.      * If something didn't work, this should contain the string describing the problem.
  100.      *
  101.      * @return  string|false  describing the error
  102.      */
  103.     public function getLastError() {
  104.         return $this->last_error ?: false;
  105.     }
  107.     /**
  108.      * Get an array containing the HTTP headers and the body of the API response.
  109.      *
  110.      * @return array  Assoc array with keys 'headers' and 'body'
  111.      */
  112.     public function getLastResponse() {
  113.         return $this->last_response;
  114.     }
  116.     /**
  117.      * Get an array containing the HTTP headers and the body of the API request.
  118.      *
  119.      * @return array  Assoc array
  120.      */
  121.     public function getLastRequest() {
  122.         return $this->last_request;
  123.     }
  125.     /**
  126.      * Make an HTTP DELETE request - for deleting data
  127.      *
  128.      * @param   string $method  URL of the API request method
  129.      * @param   array  $args    Assoc array of arguments (if any)
  130.      * @param   int    $timeout Timeout limit for request in seconds
  131.      *
  132.      * @return  array|false   Assoc array of API response, decoded from JSON
  133.      */
  134.     public function delete($method, $args = array(), $timeout = self::TIMEOUT) {
  135.         return $this->makeRequest('delete', $method, $args, $timeout);
  136.     }
  138.     /**
  139.      * Make an HTTP GET request - for retrieving data
  140.      *
  141.      * @param   string $method  URL of the API request method
  142.      * @param   array  $args    Assoc array of arguments (usually your data)
  143.      * @param   int    $timeout Timeout limit for request in seconds
  144.      *
  145.      * @return  array|false   Assoc array of API response, decoded from JSON
  146.      */
  147.     public function get($method, $args = array(), $timeout = self::TIMEOUT) {
  148.         return $this->makeRequest('get', $method, $args, $timeout);
  149.     }
  151.     /**
  152.      * Make an HTTP PATCH request - for performing partial updates
  153.      *
  154.      * @param   string $method  URL of the API request method
  155.      * @param   array  $args    Assoc array of arguments (usually your data)
  156.      * @param   int    $timeout Timeout limit for request in seconds
  157.      *
  158.      * @return  array|false   Assoc array of API response, decoded from JSON
  159.      */
  160.     public function patch($method, $args = array(), $timeout = self::TIMEOUT) {
  161.         return $this->makeRequest('patch', $method, $args, $timeout);
  162.     }
  164.     /**
  165.      * Make an HTTP POST request - for creating and updating items
  166.      *
  167.      * @param   string $method  URL of the API request method
  168.      * @param   array  $args    Assoc array of arguments (usually your data)
  169.      * @param   int    $timeout Timeout limit for request in seconds
  170.      *
  171.      * @return  array|false   Assoc array of API response, decoded from JSON
  172.      */
  173.     public function post($method, $args = array(), $timeout = self::TIMEOUT) {
  174.         return $this->makeRequest('post', $method, $args, $timeout);
  175.     }
  177.     /**
  178.      * Make an HTTP PUT request - for creating new items
  179.      *
  180.      * @param   string $method  URL of the API request method
  181.      * @param   array  $args    Assoc array of arguments (usually your data)
  182.      * @param   int    $timeout Timeout limit for request in seconds
  183.      *
  184.      * @return  array|false   Assoc array of API response, decoded from JSON
  185.      */
  186.     public function put($method, $args = array(), $timeout = self::TIMEOUT) {
  187.         return $this->makeRequest('put', $method, $args, $timeout);
  188.     }
  190.     /**
  191.      * Performs the underlying HTTP request. Not very exciting.
  192.      *
  193.      * @param  string $http_verb The HTTP verb to use: get, post, put, patch, delete
  194.      * @param  string $method    The API method to be called
  195.      * @param  array  $args      Assoc array of parameters to be passed
  196.      * @param int     $timeout
  197.      *
  198.      * @return array|false Assoc array of decoded result
  199.      */
  200.     private function makeRequest($http_verb, $method, $args = array(), $timeout = self::TIMEOUT) {
  201.         $url = $this->api_endpoint . '/' . $method;
  203.         $response = $this->prepareStateForRequest($http_verb, $method, $url, $timeout);
  205.         $httpHeader = array(
  206.             'Accept: application/vnd.api+json',
  207.             'Content-Type: application/vnd.api+json',
  208.             'Authorization: apikey ' . $this->api_key
  209.         );
  211.         if (isset($args["language"])) {
  212.             $httpHeader[] = "Accept-Language: " . $args["language"];
  213.         }
  215.         if ($http_verb === 'put') {
  216.             $httpHeader[] = 'Allow: PUT, PATCH, POST';
  217.         }
  219.         $ch = curl_init();
  220.         curl_setopt($ch, CURLOPT_URL, $url);
  221.         curl_setopt($ch, CURLOPT_HTTPHEADER, $httpHeader);
  222.         curl_setopt($ch, CURLOPT_USERAGENT, 'DrewM/MailChimp-API/3.0 (github.com/drewm/mailchimp-api)');
  223.         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  224.         curl_setopt($ch, CURLOPT_VERBOSE, true);
  225.         curl_setopt($ch, CURLOPT_HEADER, true);
  226.         curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
  227.         curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, $this->verify_ssl);
  228.         curl_setopt($ch, CURLOPT_ENCODING, '');
  229.         curl_setopt($ch, CURLINFO_HEADER_OUT, true);
  231.         switch ($http_verb) {
  232.             case 'post':
  233.                 curl_setopt($ch, CURLOPT_POST, true);
  234.                 $this->attachRequestPayload($ch, $args);
  235.                 break;
  237.             case 'get':
  238.                 $query = http_build_query($args, '', '&');
  239.                 curl_setopt($ch, CURLOPT_URL, $url . '?' . $query);
  240.                 break;
  242.             case 'delete':
  243.                 curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  244.                 break;
  246.             case 'patch':
  247.                 curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
  248.                 $this->attachRequestPayload($ch, $args);
  249.                 break;
  251.             case 'put':
  252.                 curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
  253.                 $this->attachRequestPayload($ch, $args);
  254.                 break;
  255.         }
  257.         $responseContent = curl_exec($ch);
  258.         $response['headers'] = curl_getinfo($ch);
  259.         $response = $this->setResponseState($response, $responseContent, $ch);
  260.         $formattedResponse = $this->formatResponse($response);
  262.         curl_close($ch);
  264.         $isSuccess = $this->determineSuccess($response, $formattedResponse, $timeout);
  266.         return is_array($formattedResponse) ? $formattedResponse : $isSuccess;
  267.     }
  269.     /**
  270.      * @param string  $http_verb
  271.      * @param string  $method
  272.      * @param string  $url
  273.      * @param integer $timeout
  274.      *
  275.      * @return array
  276.      */
  277.     private function prepareStateForRequest($http_verb, $method, $url, $timeout) {
  278.         $this->last_error = '';
  280.         $this->request_successful = false;
  282.         $this->last_response = array(
  283.             'headers' => null, // array of details from curl_getinfo()
  284.             'httpHeaders' => null, // array of HTTP headers
  285.             'body' => null // content of the response
  286.         );
  288.         $this->last_request = array(
  289.             'method' => $http_verb,
  290.             'path' => $method,
  291.             'url' => $url,
  292.             'body' => '',
  293.             'timeout' => $timeout,
  294.         );
  296.         return $this->last_response;
  297.     }
  299.     /**
  300.      * Get the HTTP headers as an array of header-name => header-value pairs.
  301.      *
  302.      * The "Link" header is parsed into an associative array based on the
  303.      * rel names it contains. The original value is available under
  304.      * the "_raw" key.
  305.      *
  306.      * @param string $headersAsString
  307.      *
  308.      * @return array
  309.      */
  310.     private function getHeadersAsArray($headersAsString) {
  311.         $headers = array();
  313.         foreach (explode("\r\n", $headersAsString) as $i => $line) {
  314.             if (preg_match('/HTTP\/[1-2]/', substr($line, 0, 7)) === 1) { // http code
  315.                 continue;
  316.             }
  318.             $line = trim($line);
  319.             if (empty($line)) {
  320.                 continue;
  321.             }
  323.             list($key, $value) = explode(': ', $line);
  325.             if ($key == 'Link') {
  326.                 $value = array_merge(
  327.                         array('_raw' => $value), $this->getLinkHeaderAsArray($value)
  328.                 );
  329.             }
  331.             $headers[$key] = $value;
  332.         }
  334.         return $headers;
  335.     }
  337.     /**
  338.      * Extract all rel => URL pairs from the provided Link header value
  339.      *
  340.      * Mailchimp only implements the URI reference and relation type from
  341.      * RFC 5988, so the value of the header is something like this:
  342.      *
  343.      * 'https://us13.api.mailchimp.com/schema/3.0/Lists/Instance.json; rel="describedBy",
  344.      * <https://us13.admin.mailchimp.com/lists/members/?id=XXXX>; rel="dashboard"'
  345.      *
  346.      * @param string $linkHeaderAsString
  347.      *
  348.      * @return array
  349.      */
  350.     private function getLinkHeaderAsArray($linkHeaderAsString) {
  351.         $urls = array();
  353.         if (preg_match_all('/<(.*?)>\s*;\s*rel="(.*?)"\s*/', $linkHeaderAsString, $matches)) {
  354.             foreach ($matches[2] as $i => $relName) {
  355.                 $urls[$relName] = $matches[1][$i];
  356.             }
  357.         }
  359.         return $urls;
  360.     }
  362.     /**
  363.      * Encode the data and attach it to the request
  364.      *
  365.      * @param   resource $ch   cURL session handle, used by reference
  366.      * @param   array    $data Assoc array of data to attach
  367.      */
  368.     private function attachRequestPayload(&$ch, $data) {
  369.         $encoded = json_encode($data);
  370.         $this->last_request['body'] = $encoded;
  371.         curl_setopt($ch, CURLOPT_POSTFIELDS, $encoded);
  372.     }
  374.     /**
  375.      * Decode the response and format any error messages for debugging
  376.      *
  377.      * @param array $response The response from the curl request
  378.      *
  379.      * @return array|false    The JSON decoded into an array
  380.      */
  381.     private function formatResponse($response) {
  382.         $this->last_response = $response;
  384.         if (!empty($response['body'])) {
  385.             return json_decode($response['body'], true);
  386.         }
  388.         return false;
  389.     }
  391.     /**
  392.      * Do post-request formatting and setting state from the response
  393.      *
  394.      * @param array    $response        The response from the curl request
  395.      * @param string   $responseContent The body of the response from the curl request
  396.      * @param resource $ch              The curl resource
  397.      *
  398.      * @return array    The modified response
  399.      */
  400.     private function setResponseState($response, $responseContent, $ch) {
  401.         if ($responseContent === false) {
  402.             $this->last_error = curl_error($ch);
  403.         } else {
  405.             $headerSize = $response['headers']['header_size'];
  407.             $response['httpHeaders'] = $this->getHeadersAsArray(substr($responseContent, 0, $headerSize));
  408.             $response['body'] = substr($responseContent, $headerSize);
  410.             if (isset($response['headers']['request_header'])) {
  411.                 $this->last_request['headers'] = $response['headers']['request_header'];
  412.             }
  413.         }
  415.         return $response;
  416.     }
  418.     /**
  419.      * Check if the response was successful or a failure. If it failed, store the error.
  420.      *
  421.      * @param array       $response          The response from the curl request
  422.      * @param array|false $formattedResponse The response body payload from the curl request
  423.      * @param int         $timeout           The timeout supplied to the curl request.
  424.      *
  425.      * @return bool     If the request was successful
  426.      */
  427.     private function determineSuccess($response, $formattedResponse, $timeout) {
  428.         $status = $this->findHTTPStatus($response, $formattedResponse);
  430.         if ($status >= 200 && $status <= 299) {
  431.             $this->request_successful = true;
  432.             return true;
  433.         }
  435.         if (isset($formattedResponse['detail'])) {
  436.             $this->last_error = sprintf('%d: %s', $formattedResponse['status'], $formattedResponse['detail']);
  437.             return false;
  438.         }
  440.         if ($timeout > 0 && $response['headers'] && $response['headers']['total_time'] >= $timeout) {
  441.             $this->last_error = sprintf('Request timed out after %f seconds.', $response['headers']['total_time']);
  442.             return false;
  443.         }
  445.         $this->last_error = 'Unknown error, call getLastResponse() to find out what happened.';
  446.         return false;
  447.     }
  449.     /**
  450.      * Find the HTTP status code from the headers or API response body
  451.      *
  452.      * @param array       $response          The response from the curl request
  453.      * @param array|false $formattedResponse The response body payload from the curl request
  454.      *
  455.      * @return int  HTTP status code
  456.      */
  457.     private function findHTTPStatus($response, $formattedResponse) {
  458.         if (!empty($response['headers']) && isset($response['headers']['http_code'])) {
  459.             return (int) $response['headers']['http_code'];
  460.         }
  462.         if (!empty($response['body']) && isset($formattedResponse['status'])) {
  463.             return (int) $formattedResponse['status'];
  464.         }
  466.         return 418;
  467.     }
  469. }