Helios825.org

Some Handy Aggregated Reference Info
for ePN Affiliates and eBay Developers

(Unfortunately, I don't update this website as often as I would like. So, please be prepared for
some of the info below to be outdated. Thanks for your understanding.)

cURLfriend()

Below is wrapper function I wrote to make it easier to make eBay Shopping API, Finding API, and Trading API (and possibly some other XML-based web services) calls. Its purpose is to reduce using cURL for such calls to a mere couple lines. You're welcome to use it.

To use cURLfriend(), you'd build your input parameters, call it, and the response would be an array that includes eBay's XML response along with some cURL call stats such as session duration and size. cURLfriend() does a couple rudimentary data integrity checks and will recall the API a few times if there's no response.

For more information about this, as well as calling examples, or to submit revisions, please visit this eBay Developer forum thread. Also, down below are some additional notes.

Please don't republish this function elsewhere, but feel free to link back to this page, or to the eBay Developer forum thread mentioned above. Thanks.

- helios825

// Copyright © 2009 helios825.org
//
// ---------------------------------------------------------------
// Function: cURLfriend() makes generic eBay API call [POST or GET | XML in, XML out]
// ---------------------------------------------------------------
// $In_URL = endpoint URL to call (or complete request, if using REST / HTTP GET)
// $In_POST = XML POST data to send as request (ignore if using HTTP GET)
// $In_Headers = array of HTTP headers to use (if using HTTP POST)
// $In_RetryCount = number of times to retry API call if cURLfriend detects certain errors (smart cURL!)
// $In_Timeout = while collecting response, number of seconds before cURLfriend bails (from sheer exhaustion)
// ---------------------------------------------------------------

function cURLfriend($In_URL="", $In_POST="", $In_Headers=array(), $In_RetryCount=2, $In_Timeout=10) {


   // -----------------------------------
   // Initialize Internal Variables
   // -----------------------------------
   $Out = array() ;
   $StatusCode = "x" ;
   $cURLresponse_data = "" ;
   $cURLresponse_errorNumber = 0 ;
   $cURLresponse_errorString = "" ;
   $cURLresponse_info = array() ;
   $cURLresponse_info_HTTPcode = "" ;
   $cURLresponse_info_TotalTime = "" ;
   $cURLresponse_info_DLsize = "" ;
   $f_DoPOST = FALSE ;
   $cURLcall_LoopsMax = 0 ;
   $cURLcall_LoopCounter = 0 ;
   $cURLcall_Loops = 0 ;
   $cURLcall_f_LoopAbort = FALSE ;


   // -----------------------------------
   // Constants
   // -----------------------------------
   $c_cURLopt_MaxPersConn = 12 ;   // maximum simultaneous persistent connections (may not apply)
   $c_cURLopt_MaxRedirs = 6 ;   // maximum number of chained 301/2 redirects to follow before cURLfriend (rightfully) gets fed up with incessant excuses
   $c_cURLopt_ConnectTimeout = 2 ;   // while attempting to connect, number of seconds before cURLfriend gives up (short attention span, or excellent time management skills?)
   $c_RetryCount_HardMax = 7 ;   // hard internal maximum on retries to eBay API (be nice to eBay's servers and they'll be nice to my cURLfriend)
   $c_cURLopt_UserAgent = "cURLfriend() eBay API Calling Script | You@YourDomain.com" ;   // cURLfriend has a full name, just like the rest of us


   // -----------------------------------
   // Prep/Clean
   // -----------------------------------
   $f_DoPOST = (!(empty($In_POST))) ;   // make call as HTTP POST?
   $In_Headers = ((empty($In_Headers)) ? (array()) : ($In_Headers)) ;   // $In_Headers needs to be an array, whether present or not
   $In_RetryCount = (($In_RetryCount < 0) ? (0) : ($In_RetryCount)) ;   // $In_RetryCount needs to be >=0
   $In_Timeout = (($In_Timeout < 0) ? (0) : ($In_Timeout)) ;   // $In_Timeout needs to be >=0


   // -----------------------------------
   // A Few Simple Checks on Input Parameters
   // -----------------------------------
   // * endpoint URL must start with 'http' ('https' OK)
   // * if using POST, request must start with required XML declaration
   // * HTTP headers, if used, must be an array
   // -----------------------------------
   if ( (stripos($In_URL,"http") === 0) &&
       (($f_DoPOST) ? (stripos($In_POST,"<?xml") === 0) : (TRUE)) &&
       (is_array($In_Headers)) ) {
      $StatusCode = "v" ;   // none of the above checks failed [valid]
   }

   else {
      $StatusCode = "i" ;   // one of the above checks failed [invalid]
   }


   // -----------------------------------
   // Proceed With cURL Call
   // -----------------------------------
   if ($StatusCode == "v") {

      // -----------------------------------
      // Setup cURL Session
      // -----------------------------------
      $cURLhandle = curl_init() ;
      curl_setopt($cURLhandle, CURLOPT_URL, $In_URL) ;
      curl_setopt($cURLhandle, CURLOPT_FOLLOWLOCATION, TRUE) ;
      curl_setopt($cURLhandle, CURLOPT_MAXREDIRS, $c_cURLopt_MaxRedirs) ;
//    curl_setopt($cURLhandle, CURLOPT_USERAGENT, $c_cURLopt_UserAgent) ;
      curl_setopt($cURLhandle, CURLOPT_NOBODY, FALSE) ;
      curl_setopt($cURLhandle, CURLOPT_POST, $f_DoPOST) ;
      curl_setopt($cURLhandle, CURLOPT_SSL_VERIFYPEER, FALSE) ;
      curl_setopt($cURLhandle, CURLOPT_SSL_VERIFYHOST, 0) ;
      curl_setopt($cURLhandle, CURLOPT_MAXCONNECTS, $c_cURLopt_MaxPersConn) ;
      curl_setopt($cURLhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1) ;
      curl_setopt($cURLhandle, CURLOPT_CLOSEPOLICY, CURLCLOSEPOLICY_LEAST_RECENTLY_USED) ;
      curl_setopt($cURLhandle, CURLOPT_TIMEOUT, $In_Timeout) ;
      curl_setopt($cURLhandle, CURLOPT_CONNECTTIMEOUT, $c_cURLopt_ConnectTimeout) ;
      curl_setopt($cURLhandle, CURLOPT_FAILONERROR, TRUE) ;
      curl_setopt($cURLhandle, CURLOPT_HTTPHEADER, $In_Headers) ;
      if ($f_DoPOST) {
         curl_setopt($cURLhandle, CURLOPT_POSTFIELDS, $In_POST) ;
      }
      curl_setopt($cURLhandle, CURLOPT_HEADER, FALSE) ;
      curl_setopt($cURLhandle, CURLOPT_VERBOSE, FALSE) ;
      curl_setopt($cURLhandle, CURLOPT_RETURNTRANSFER, TRUE) ;


      // -----------------------------------
      // Make cURL Call With Retries
      // -----------------------------------
      $cURLcall_LoopsMax = ((($c_RetryCount_HardMax > $In_RetryCount) ? ($In_RetryCount) : ($c_RetryCount_HardMax)) + 1) ;
      $cURLcall_LoopCounter = $cURLcall_LoopsMax ;
      $cURLcall_f_LoopAbort = FALSE ;

      while (($cURLcall_LoopCounter) && (!($cURLcall_f_LoopAbort))) {

         $cURLresponse_data = curl_exec($cURLhandle) ;
         $cURLresponse_errorNumber = curl_errno($cURLhandle) ;

         // in case XML response has leading junk characters, or no XML declaration...
         $cURLresponse_data = stristr($cURLresponse_data,"<?xml") ;

         if ( (empty($cURLresponse_data)) ||
             ($cURLresponse_errorNumber != 0) ||
             (stripos($cURLresponse_data,"<?xml") !== 0) ) {
            $StatusCode = "r" ;
            $cURLresponse_data = "" ;
            $cURLcall_f_LoopAbort = FALSE ;
         } // some problem acquiring proper response [no response | cURL error | a non-XML response]

         else {
            $StatusCode = "n" ;
            $cURLcall_f_LoopAbort = TRUE ;
         } // response probably acquired OK

         $cURLcall_LoopCounter-- ;

      } // while-looper making cURL calls

      $cURLcall_Loops = ($cURLcall_LoopsMax - $cURLcall_LoopCounter) ;


      // -----------------------------------
      // Acquire More Info About Last cURL Call
      // -----------------------------------
      $cURLresponse_errorString = curl_error($cURLhandle) ;
      $cURLresponse_info = curl_getinfo($cURLhandle) ;
      $cURLresponse_info_HTTPcode = (string) ((isset($cURLresponse_info["http_code"])) ? ($cURLresponse_info["http_code"]) : ("")) ;
      $cURLresponse_info_TotalTime = (string) ((isset($cURLresponse_info["total_time"])) ? ($cURLresponse_info["total_time"]) : ("")) ;
      $cURLresponse_info_DLsize = (string) ((isset($cURLresponse_info["size_download"])) ? ($cURLresponse_info["size_download"]) : ("")) ;


      // -----------------------------------
      // Close cURL Session
      // -----------------------------------
      curl_close($cURLhandle) ;


   } // end: cURL call was made

   else {
      // [nothing here]
   } // end: cURL call was not made


   // -----------------------------------
   // Build Returned Array
   // -----------------------------------
   $Out[0] = $cURLresponse_data ;
   $Out[1] = $StatusCode ;
   $Out[2] = $cURLresponse_errorNumber ;
   $Out[3] = $cURLresponse_errorString ;
   $Out[4] = $cURLresponse_info_HTTPcode ;
   $Out[5] = $cURLresponse_info_TotalTime ;
   $Out[6] = $cURLresponse_info_DLsize ;
   $Out[7] = $f_DoPOST ;
   $Out[8] = $cURLcall_Loops ;

   return($Out) ;


   // -----------------------------------
   // Returned Array
   // -----------------------------------
   // [0] = cURL response from API in XML (from last attempt)
   // [1] = cURLfriend Status Code
   // [2] = cURL error number (of last attempt) [ see: http://curl.haxx.se/libcurl/c/libcurl-errors.html ]
   // [3] = cURL error string (of last attempt)
   // [4] = cURL call info: last received HTTP code (of last attempt)
   // [5] = cURL call info: total time (of last attempt)
   // [6] = cURL call info: size of download/response (of last attempt)
   // [7] = cURL call (if made) was done via HTTP POST ('false' means via HTTP GET)
   // [8] = number of cURL call tries
   //
   // -----------------------------------
   // cURLfriend Status Codes
   // -----------------------------------
   // x = initial status [intermediary code] [fail]
   // v = initial checks passed [intermediary code]
   // i = initial check(s) failed, cURL call not made [fail]
   // r = cURL call failed (in some way) on last attempt [fail]
   // n = normal (cURL call made; no problems identified) [pass]
   //


} // end function: Thanks, cURLfriend()!!

Notes

cURL : Your PHP server probably needs to have cURL installed/enabled. I don't know much about such matters, but I presume that the newer your version of PHP is, the more likely cURL is automatically available to you. If it's not installed already, you or your sysadmin might need to take a stab at running something like EasyApache to rebuild your Apache installation accordingly.

User Agent : You may choose to enter a string that would be used to casually identify you as the API caller. To do so, set the constant above $c_cURLopt_UserAgent and uncomment the related curl_setopt() line. Keep in mind that doing so will override any user agent set in php.ini.

REST/GET vs. POST : If you're calling the eBay Shopping API (or other REST-based web services call), you can use simply the first parameter $In_URL and ignore the others. If you do want to use some of the latter parameters (like $In_RetryCount) without using the intermediary ones, you'd need to insert NULL for ones you want to skip over. Exception: If you do want to specify $In_Timeout, you will need to enter a number (not NULL) for $In_RetryCount. For example:  $call = cURLfriend($ShoppingAPIcall, NULL, NULL, 3, 15)





Comments/Questions/Suggestions/Additions/Corrections => Support |at| Helios825 |dot| org

The information provided on this website is offered on an as-is basis without any guarantee to its accuracy, or continued existence, and with no warranty granted or liability assumed by the owners of this website. We expressly disclaim all liability, whether direct or indirect, consequential or incidental, obvious or implied, for any damages, should the information provided, or not provided, on our website be inaccurate, incomplete, out of date, or otherwise not ideal, or for any other reason.