peterkahl/curl-master

Simple cURL wrapper with response caching and cookie storage.

v4.3.1 2019-07-26 17:03 UTC

README

Downloads License If this project has business value for you then don't hesitate to support me with a small donation.

Wrapper for the cURL extension with response caching and cookie storage, with request methods GET, POST, HEAD; with advanced options and debug mode.

Usage example, method GET:

use peterkahl\curlMaster\curlMaster;

$curlm = new curlMaster;

/**
 * Whether to enable debug mode.
 * If so, cURL responses are stored in debug files which may need
 * to be deleted manually.
 * @var boolean
 */
public $EnableDebug = false;
  
/**
 * Set the cache directory
 * @var string
 */
$curlm->CacheDir = '/var/www/cache';

/**
 * If you want to use SSL/TLS, you need to set the location of CA certificate file.
 * You may download and install on your server this Mozilla CA bundle
 * from this page: <https://curl.haxx.se/docs/caextract.html>
 * @var string
 */
$curlm->ca_file = '/srv/certs/ca-bundle.crt';

/**
 * Public Key Pin
 * Use either absolute path to DER certificate or sha256/base64 encoded der.
 * See <https://curl.haxx.se/libcurl/c/CURLOPT_PINNEDPUBLICKEY.html>
 * @var string
 */
public $PublicKeyPin = '';

/**
 * TLS version
 * Best to leave this empty unless you know what you are doing.
 * @var string .... example '1.2'
 *      Permissible values are '1.0', '1.1', '1.2'.
 */
public $tlsver = '';

/**
 * Cipher string
 * Optionally, you may define ciphers for TLS connection.
 * @var string .... example 'EECDH+AESGCM:EDH+AESGCM'
 */
$curlm->CipherString = 'EECDH+AESGCM:EDH+AESGCM';

/**
 * If you need to set User Agent
 * @var string
 */
$curlm->useragent = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:55.0) Gecko/20100101 Firefox/55.0';

/**
 * Caching control & Maximum age of forced cache (in seconds).
 *
 * All responses are cached, but when this value is > 0, caching
 * will be forced regardless of the response headers.
 * Forced caching is useful when you expect the same response for each
 * request or when:
 *   -- debugging
 *   -- you cURL an API with request limit
 *
 * @var integer .... value 0 disables forced caching while header-dependent caching is still on
 *                   value >0 enables forced caching and overrides header-dependent caching
 *                   value <0 disables caching altogether (example -1)
 *
 */
$curlm->ForcedCacheMaxAge = 3600;

/**
 * Enable purging of outdated cache files on each request.
 * Disabled (false) by default.
 * If you don't purge the cache yourself (i.e. using crontab and
 * the method PurgeCache), you should change this to true.
 * @var boolean
 */
$curlm->PurgeEnableOnEachRequest = false;

/**
 * The URL you want to cURL (method GET)
 * @param string
 */
$response = $curlm->Request('https://github.com/');

$url        = $response['url'];
$metod      = $response['method'];
$req_data   = $response['req_data'];
$useragent  = $response['useragent'];
$headers    = $response['headers'];
$body       = $response['body'];
$filename   = $response['filename'];
$cookiefile = $response['cookiefile'];
$exectime   = $response['exectime'];
$status     = $response['status'];
$origin     = $response['origin'];

if ($status != '200') {
  throw new Exception('HTTP request failed with status '.$status);
}

var_dump($response);

/*
array(14) {
  ["url"]=>
  string(19) "https://github.com/"
  ["method"]=>
  string(3) "GET"
  ["req_data"]=>
  string(0) ""
  ["useragent"]=>
  string(82) "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:55.0) Gecko/20100101 Firefox/55.0"
  ["details"]=>
  array(54) {
    [0]=>
    string(28) "*   Trying 13.250.177.223..."
    [1]=>
    string(17) "* TCP_NODELAY set"
    [2]=>
    string(56) "* Connected to github.com (13.250.177.223) port 443 (#0)"
    [3]=>
    string(25) "* ALPN, offering http/1.1"
    [4]=>
    string(43) "* Cipher selection: EECDH+AESGCM:EDH+AESGCM"
    [5]=>
    string(48) "* successfully set certificate verify locations:"
    [6]=>
    string(35) "*   CAfile: /srv/cert-ca/cacert.pem"
    [7]=>
    string(14) "  CApath: none"
    [8]=>
    string(55) "* SSL connection using unknown / TLS_AES_128_GCM_SHA256"
    [9]=>
    string(39) "* ALPN, server accepted to use http/1.1"
    [10]=>
    string(21) "* Server certificate:"
    [11]=>
    string(183) "*  subject: businessCategory=Private Organization; jurisdictionC=US; jurisdictionST=Delaware; serialNumber=5157550; C=US; ST=California; L=San Francisco; O=GitHub, Inc.; CN=github.com"
    [12]=>
    string(39) "*  start date: May  8 00:00:00 2018 GMT"
    [13]=>
    string(40) "*  expire date: Jun  3 12:00:00 2020 GMT"
    [14]=>
    string(64) "*  subjectAltName: host "github.com" matched cert's "github.com""
    [15]=>
    string(100) "*  issuer: C=US; O=DigiCert Inc; OU=www.digicert.com; CN=DigiCert SHA2 Extended Validation Server CA"
    [16]=>
    string(29) "*  SSL certificate verify ok."
    [17]=>
    string(16) "> GET / HTTP/1.1"
    [18]=>
    string(16) "Host: github.com"
    [19]=>
    string(94) "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:55.0) Gecko/20100101 Firefox/55.0"
    [20]=>
    string(11) "Accept: */*"
    [21]=>
    string(30) "Accept-Encoding: deflate, gzip"
    [22]=>
    string(0) ""
    [23]=>
    string(17) "< HTTP/1.1 200 OK"
    [24]=>
    string(37) "< Date: Fri, 26 Jul 2019 16:33:55 GMT"
    [25]=>
    string(40) "< Content-Type: text/html; charset=utf-8"
    [26]=>
    string(28) "< Transfer-Encoding: chunked"
    [27]=>
    string(20) "< Server: GitHub.com"
    [28]=>
    string(16) "< Status: 200 OK"
    [29]=>
    string(14) "< Vary: X-PJAX"
    [30]=>
    string(44) "< ETag: W/"ab4b07edf16748069f525775d2919a29""
    [31]=>
    string(52) "< Cache-Control: max-age=0, private, must-revalidate"
    [32]=>
    string(87) "* Added cookie has_recent_activity="1" for domain github.com, path /, expire 1564162435"
    [33]=>
    string(84) "< Set-Cookie: has_recent_activity=1; path=/; expires=Fri, 26 Jul 2019 17:33:55 -0000"
    [34]=>
    string(99) "* Added cookie _octo="GH1.1.1799252109.1564158835" for domain github.com, path /, expire 1627317235"
    [35]=>
    string(116) "< Set-Cookie: _octo=GH1.1.1799252109.1564158835; domain=.github.com; path=/; expires=Mon, 26 Jul 2021 16:33:55 -0000"
    [36]=>
    string(78) "* Added cookie logged_in="no" for domain github.com, path /, expire 2195310835"
    [37]=>
    string(113) "< Set-Cookie: logged_in=no; domain=.github.com; path=/; expires=Tue, 26 Jul 2039 16:33:55 -0000; secure; HttpOnly"
    [38]=>
    string(434) "* Added cookie _gh_sess="QTg3VmphOFVxWWJCWjRVUjU5TVlvZi8yblhOdXRHeDZzb2txbkFEWDNGZEU1bHZta0pxZFBhd3FxS0hac0NzaXY1UkJTcmNpTUJLTWVXTVNQWW9GYlFNcmtuOTMxOVQrOGFDdEtKOUhodjdDaTdkVHF6dHp5VGt1OVJaL1A3MWJMenNKYU5NcU1yYStteXRIQmlOUEMzc2UxODRGRkhXenlaRUhFdVFuS0ZOSWR5T3RRbmtxeU1tTE0vbnduZ0Q0YWxhbHdRVWExMDdRLzczTDdiYjUwQT09LS1qaWtoRGZIdlRUektBWVoyc0hiTWl3PT0%3D--e815929179ac67ce3af8f3f89bdd1086fbadc8ad" for domain github.com, path /, expire 0"
    [39]=>
    string(417) "< Set-Cookie: _gh_sess=QTg3VmphOFVxWWJCWjRVUjU5TVlvZi8yblhOdXRHeDZzb2txbkFEWDNGZEU1bHZta0pxZFBhd3FxS0hac0NzaXY1UkJTcmNpTUJLTWVXTVNQWW9GYlFNcmtuOTMxOVQrOGFDdEtKOUhodjdDaTdkVHF6dHp5VGt1OVJaL1A3MWJMenNKYU5NcU1yYStteXRIQmlOUEMzc2UxODRGRkhXenlaRUhFdVFuS0ZOSWR5T3RRbmtxeU1tTE0vbnduZ0Q0YWxhbHdRVWExMDdRLzczTDdiYjUwQT09LS1qaWtoRGZIdlRUektBWVoyc0hiTWl3PT0%3D--e815929179ac67ce3af8f3f89bdd1086fbadc8ad; path=/; secure; HttpOnly"
    [40]=>
    string(52) "< X-Request-Id: 7f9d8967-cf19-40e4-b74b-a11b3f4f8dfa"
    [41]=>
    string(73) "< Strict-Transport-Security: max-age=31536000; includeSubdomains; preload"
    [42]=>
    string(23) "< X-Frame-Options: deny"
    [43]=>
    string(33) "< X-Content-Type-Options: nosniff"
    [44]=>
    string(33) "< X-XSS-Protection: 1; mode=block"
    [45]=>
    string(76) "< Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin"
    [46]=>
    string(89) "< Expect-CT: max-age=2592000, report-uri="https://api.github.com/_private/browser/errors""
    [47]=>
    string(887) "< Content-Security-Policy: default-src 'none'; base-uri 'self'; block-all-mixed-content; connect-src 'self' uploads.github.com www.githubstatus.com collector.githubapp.com api.github.com www.google-analytics.com github-cloud.s3.amazonaws.com github-production-repository-file-5c1aeb.s3.amazonaws.com github-production-upload-manifest-file-7fdce7.s3.amazonaws.com github-production-user-asset-6210df.s3.amazonaws.com wss://live.github.com; font-src github.githubassets.com; form-action 'self' github.com gist.github.com; frame-ancestors 'none'; frame-src render.githubusercontent.com; img-src 'self' data: github.githubassets.com identicons.github.com collector.githubapp.com github-cloud.s3.amazonaws.com *.githubusercontent.com customer-stories-feed.github.com; manifest-src 'self'; media-src 'none'; script-src github.githubassets.com; style-src 'unsafe-inline' github.githubassets.com"
    [48]=>
    string(24) "< Content-Encoding: gzip"
    [49]=>
    string(23) "< Vary: Accept-Encoding"
    [50]=>
    string(55) "< X-GitHub-Request-Id: C7C8:2F49:48C926:657A61:5D3B2B73"
    [51]=>
    string(2) "< "
    [52]=>
    string(22) "* Closing connection 0"
    [53]=>
    string(0) ""
  }
  ["headers"]=>
  array(24) {
    ["status"]=>
    string(15) "HTTP/1.1 200 OK"
    ["date"]=>
    string(29) "Fri, 26 Jul 2019 16:33:55 GMT"
    ["content-type"]=>
    string(24) "text/html; charset=utf-8"
    ["transfer-encoding"]=>
    string(7) "chunked"
    ["server"]=>
    string(10) "GitHub.com"
    ["status-1"]=>
    string(6) "200 OK"
    ["vary"]=>
    string(6) "X-PJAX"
    ["etag"]=>
    string(36) "W/"ab4b07edf16748069f525775d2919a29""
    ["cache-control"]=>
    string(35) "max-age=0, private, must-revalidate"
    ["set-cookie"]=>
    string(70) "has_recent_activity=1; path=/; expires=Fri, 26 Jul 2019 17:33:55 -0000"
    ["set-cookie-2"]=>
    string(102) "_octo=GH1.1.1799252109.1564158835; domain=.github.com; path=/; expires=Mon, 26 Jul 2021 16:33:55 -0000"
    ["set-cookie-3"]=>
    string(99) "logged_in=no; domain=.github.com; path=/; expires=Tue, 26 Jul 2039 16:33:55 -0000; secure; HttpOnly"
    ["set-cookie-4"]=>
    string(403) "_gh_sess=QTg3VmphOFVxWWJCWjRVUjU5TVlvZi8yblhOdXRHeDZzb2txbkFEWDNGZEU1bHZta0pxZFBhd3FxS0hac0NzaXY1UkJTcmNpTUJLTWVXTVNQWW9GYlFNcmtuOTMxOVQrOGFDdEtKOUhodjdDaTdkVHF6dHp5VGt1OVJaL1A3MWJMenNKYU5NcU1yYStteXRIQmlOUEMzc2UxODRGRkhXenlaRUhFdVFuS0ZOSWR5T3RRbmtxeU1tTE0vbnduZ0Q0YWxhbHdRVWExMDdRLzczTDdiYjUwQT09LS1qaWtoRGZIdlRUektBWVoyc0hiTWl3PT0%3D--e815929179ac67ce3af8f3f89bdd1086fbadc8ad; path=/; secure; HttpOnly"
    ["x-request-id"]=>
    string(36) "7f9d8967-cf19-40e4-b74b-a11b3f4f8dfa"
    ["strict-transport-security"]=>
    string(44) "max-age=31536000; includeSubdomains; preload"
    ["x-frame-options"]=>
    string(4) "deny"
    ["x-content-type-options"]=>
    string(7) "nosniff"
    ["x-xss-protection"]=>
    string(13) "1; mode=block"
    ["referrer-policy"]=>
    string(57) "origin-when-cross-origin, strict-origin-when-cross-origin"
    ["expect-ct"]=>
    string(76) "max-age=2592000, report-uri="https://api.github.com/_private/browser/errors""
    ["content-security-policy"]=>
    string(860) "default-src 'none'; base-uri 'self'; block-all-mixed-content; connect-src 'self' uploads.github.com www.githubstatus.com collector.githubapp.com api.github.com www.google-analytics.com github-cloud.s3.amazonaws.com github-production-repository-file-5c1aeb.s3.amazonaws.com github-production-upload-manifest-file-7fdce7.s3.amazonaws.com github-production-user-asset-6210df.s3.amazonaws.com wss://live.github.com; font-src github.githubassets.com; form-action 'self' github.com gist.github.com; frame-ancestors 'none'; frame-src render.githubusercontent.com; img-src 'self' data: github.githubassets.com identicons.github.com collector.githubapp.com github-cloud.s3.amazonaws.com *.githubusercontent.com customer-stories-feed.github.com; manifest-src 'self'; media-src 'none'; script-src github.githubassets.com; style-src 'unsafe-inline' github.githubassets.com"
    ["content-encoding"]=>
    string(4) "gzip"
    ["vary-5"]=>
    string(15) "Accept-Encoding"
    ["x-github-request-id"]=>
    string(32) "C7C8:2F49:48C926:657A61:5D3B2B73"
  }
  ["body"]=>
  string(87703) "<!DOCTYPE html>
<html lang="en">
  ... TRUNCATED ...
</html>"
  ["filename"]=>
  string(58) "/CURL_RESPON-7925bc3882e4878bf575d5f4db65c310613edb99.3600"
  ["exectime"]=>
  string(11) "900.98 msec"
  ["cookiefile"]=>
  string(70) "/srv/cache/CURL_COOKIE-c2208abde9668e8e9815c3690855edd1e63abeac.604800"
  ["status"]=>
  string(3) "200"
  ["origin"]=>
  string(3) "new"
  ["error_num"]=>
  int(0)
  ["error"]=>
  string(8) "CURLE_OK"
}
*/

Usage example, method POST:

use peterkahl\curlMaster\curlMaster;

$curlm = new curlMaster;

/**
 * Set the cache directory
 * @var string
 */
$curlm->CacheDir = '/var/www/cache';

/**
 * If you want to use SSL/TLS, you need to set the location of CA certificate file.
 * You may download and install on your server this Mozilla CA bundle
 * from this page: <https://curl.haxx.se/docs/caextract.html>
 * @var string
 */
$curlm->ca_file = '/srv/certs/ca-bundle.crt';

/**
 * Cipher string
 * Optionally, you may define ciphers for TLS connection.
 * @var string .... example 'AESGCM:!PSK'
 */
$curlm->CipherString = 'AESGCM:!PSK';

/**
 * If you need to set User Agent
 * @var string
 */
$curlm->useragent = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:55.0) Gecko/20100101 Firefox/55.0';

/**
 * Caching control & Maximum age of forced cache (in seconds).
 *
 * All responses are cached, but when this value is > 0, caching
 * will be forced regardless of the response headers.
 * Forced caching is useful when you expect the same response for each
 * request or when:
 *   -- debugging
 *   -- you cURL an API with request limit
 *
 * @var integer .... value 0 disables forced caching while header-dependent caching is still on
 *                   value >0 enables forced caching and overrides header-dependent caching
 *                   value <0 disables caching altogether (example -1)
 *
 */
$curlm->ForcedCacheMaxAge = 3600;

$data = array(
  'user' => 'admin',
  'pwd'  => 'oracle',
);

/**
 * The URL you want to cURL
 */
$response = $curlm->Request('https://whatever.anything/login', 'POST', $data);

Cache Purging:

Although the cache is being purged automatically on each request (GET, POST, HEAD), an alternative is to purge the cache yourself, e.g. as crontab job using the available method PurgeCache().

use peterkahl\curlMaster\curlMaster;

$curlm = new curlMaster;

/**
 * Set the cache directory
 * @var string
 */
$curlm->CacheDir = '/mycachedirectory';

$curlm->PurgeCache();