File: README.md

Recommend this page to a friend!
  Classes of Peter Kahl  >  curl Master  >  README.md  >  Download  
File: README.md
Role: Documentation
Content type: text/markdown
Description: Documentation
Class: curl Master
Send HTTP requests using the curl extension
Author: By
Last change: Improved cookie storage management

Cookies are maintained in cache for as long as they are unexpired. Cookie files are deleted as soon as all cookies within a cookie file become expired.
Custom user agent string is now validated for ASCII characters.
Date: 2 months ago
Size: 12,869 bytes
 

Contents

Class file image Download

curlMaster

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 compressed 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;

/
 * 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';

/
 * 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;

/
 * HTTP request headers (optional)
 * @var array
 * Example ... array('Connection: Close', 'X-API-Key: 7KgvBPUXh_XKQAMG');
 */
$curlm->headers = array('accept: text/html');

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


if ($answer['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(72) "Mozilla/5.0 (curlMaster/5.0.2; +https://github.com/peterkahl/curlMaster)"
  ["details"]=>
  array(51) {
    [0]=>
    string(27) "*   Trying 13.229.188.59..."
    [1]=>
    string(17) "* TCP_NODELAY set"
    [2]=>
    string(55) "* Connected to github.com (13.229.188.59) 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(84) "User-Agent: Mozilla/5.0 (curlMaster/5.0.2; +https://github.com/peterkahl/curlMaster)"
    [20]=>
    string(30) "Accept-Encoding: deflate, gzip"
    [21]=>
    string(375) "Cookie: _gh_sess=NkxJNnJLaFFMZHIzWUkvRkpDVG96MlJKcTdrZlF5bVVDOFVXUFU4Z21rNDQ5cnFPTHRlRmRlYVU5VXg1bjQ5YmFNWExlSEpraG5TTENSOGczRlM1L0FCaDRUMTVSTXY2ZVNYRkhKenNSUFYrMklrczNwMEU3S1ptbXJRME9jejJPV2E2ZHkrcUpQVlg4NTFsQ2tzZkJRPT0tLXdvK2t6RVZjQ1dZdXZ5ME9MQmFZSHc9PQ%3D%3D--e78c86cd8a6380a5a3ad37189fb05f32f4d3fd4c; _octo=GH1.1.1361283935.1569219950; has_recent_activity=1; logged_in=no"
    [22]=>
    string(17) "accept: text/html"
    [23]=>
    string(0) ""
    [24]=>
    string(17) "< HTTP/1.1 200 OK"
    [25]=>
    string(37) "< Date: Mon, 23 Sep 2019 06:28:48 GMT"
    [26]=>
    string(40) "< Content-Type: text/html; charset=utf-8"
    [27]=>
    string(28) "< Transfer-Encoding: chunked"
    [28]=>
    string(20) "< Server: GitHub.com"
    [29]=>
    string(16) "< Status: 200 OK"
    [30]=>
    string(14) "< Vary: X-PJAX"
    [31]=>
    string(44) "< ETag: W/"8c61e18566f5b2f4f759798587ed45b8""
    [32]=>
    string(52) "< Cache-Control: max-age=0, private, must-revalidate"
    [33]=>
    string(90) "* Replaced cookie has_recent_activity="1" for domain github.com, path /, expire 1569223728"
    [34]=>
    string(84) "< Set-Cookie: has_recent_activity=1; path=/; expires=Mon, 23 Sep 2019 07:28:48 -0000"
    [35]=>
    string(355) "* Replaced cookie _gh_sess="S2hONGpxOXhwL0J5eENXTHhIRGgzWThwdGZkUEJUa3pDdFYvQitQSUdaVFllODZRWU9naWZiRWJ2VmNhQ0tBampVcUVQYmhLTlphendTR291ZTh6Tm82bWo1V2ZIUUhBbDhOMnN0NEVwL2psd1hZdHozaUhiSkJmbkpLcDZ0d0xoaUFKSE4xb2RmQXhxTi9tR0UxcjhnPT0tLW1DUEc4d0Y1R3l2R1ZtY2dSQ0xUQWc9PQ%3D%3D--05a500acc832a1595f80a40d5c484358e8d14fee" for domain github.com, path /, expire 0"
    [36]=>
    string(335) "< Set-Cookie: _gh_sess=S2hONGpxOXhwL0J5eENXTHhIRGgzWThwdGZkUEJUa3pDdFYvQitQSUdaVFllODZRWU9naWZiRWJ2VmNhQ0tBampVcUVQYmhLTlphendTR291ZTh6Tm82bWo1V2ZIUUhBbDhOMnN0NEVwL2psd1hZdHozaUhiSkJmbkpLcDZ0d0xoaUFKSE4xb2RmQXhxTi9tR0UxcjhnPT0tLW1DUEc4d0Y1R3l2R1ZtY2dSQ0xUQWc9PQ%3D%3D--05a500acc832a1595f80a40d5c484358e8d14fee; path=/; secure; HttpOnly"
    [37]=>
    string(52) "< X-Request-Id: 78b92acb-e6ec-4112-89c1-f22529236b61"
    [38]=>
    string(73) "< Strict-Transport-Security: max-age=31536000; includeSubdomains; preload"
    [39]=>
    string(23) "< X-Frame-Options: deny"
    [40]=>
    string(33) "< X-Content-Type-Options: nosniff"
    [41]=>
    string(33) "< X-XSS-Protection: 1; mode=block"
    [42]=>
    string(76) "< Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin"
    [43]=>
    string(89) "< Expect-CT: max-age=2592000, report-uri="https://api.github.com/_private/browser/errors""
    [44]=>
    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"
    [45]=>
    string(24) "< Content-Encoding: gzip"
    [46]=>
    string(23) "< Vary: Accept-Encoding"
    [47]=>
    string(57) "< X-GitHub-Request-Id: 2F2C:28B7:1D0D283:2945FE9:5D88661F"
    [48]=>
    string(2) "< "
    [49]=>
    string(22) "* Closing connection 0"
    [50]=>
    string(0) ""
  }
  ["headers"]=>
  array(22) {
    ["status"]=>
    string(15) "HTTP/1.1 200 OK"
    ["date"]=>
    string(29) "Mon, 23 Sep 2019 06:28:48 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/"8c61e18566f5b2f4f759798587ed45b8""
    ["cache-control"]=>
    string(35) "max-age=0, private, must-revalidate"
    ["set-cookie"]=>
    string(70) "has_recent_activity=1; path=/; expires=Mon, 23 Sep 2019 07:28:48 -0000"
    ["set-cookie-2"]=>
    string(321) "_gh_sess=S2hONGpxOXhwL0J5eENXTHhIRGgzWThwdGZkUEJUa3pDdFYvQitQSUdaVFllODZRWU9naWZiRWJ2VmNhQ0tBampVcUVQYmhLTlphendTR291ZTh6Tm82bWo1V2ZIUUhBbDhOMnN0NEVwL2psd1hZdHozaUhiSkJmbkpLcDZ0d0xoaUFKSE4xb2RmQXhxTi9tR0UxcjhnPT0tLW1DUEc4d0Y1R3l2R1ZtY2dSQ0xUQWc9PQ%3D%3D--05a500acc832a1595f80a40d5c484358e8d14fee; path=/; secure; HttpOnly"
    ["x-request-id"]=>
    string(36) "78b92acb-e6ec-4112-89c1-f22529236b61"
    ["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-3"]=>
    string(15) "Accept-Encoding"
    ["x-github-request-id"]=>
    string(34) "2F2C:28B7:1D0D283:2945FE9:5D88661F"
  }
  ["body"]=>
  string(134561) "<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">

  [truncated]

  </body>
</html>"
  ["filename"]=>
  string(70) "/var/www/cache/CURL_RESPON-GZcdc639cd64b5cabb600bf5d5c219cf3f5b618100.3600"
  ["exectime"]=>
  string(11) "345.14 msec"
  ["cookiefile"]=>
  string(70) "/var/www/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';

/
 * 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 can be 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();

For more information send a message to info at phpclasses dot org.