CURLRequest Class

The CURLRequest class is a lightweight HTTP client based on CURL that allows you to talk to otherweb sites and servers. It can be used to get the contents of a Google search, retrieve a web page or image,or communicate with an API, among many other things.

This class is modeled after the Guzzle HTTP Client library sinceit is one of the more widely used libraries. Where possible, the syntax has been kept the same so that ifyour application needs something a little more powerful than what this library provides, you will haveto change very little to move over to use Guzzle.

Note

This class requires the cURL Library to be installedin your version of PHP. This is a very common library that is typically available but not all hostswill provide it, so please check with your host to verify if you run into problems.

Loading the Library

The library can be loaded either manually or through the Services class.

To load with the Services class call the curlrequest() method:

  1. $client = \Config\Services::curlrequest();

You can pass in an array of default options as the first parameter to modify how cURL will handle the request.The options are described later in this document:

  1. $options = [
  2.         'base_uri' => 'http://example.com/api/v1/',
  3.         'timeout'  => 3
  4. ];
  5. $client = \Config\Services::curlrequest($options);

When creating the class manually, you need to pass a few dependencies in. The first parameter is aninstance of the Config\App class. The second parameter is a URI instance. The thirdparameter is a Response object. The fourth parameter is the optional $options array:

  1. $client = new \CodeIgniter\HTTP\CURLRequest(
  2.         new \Config\App(),
  3.         new \CodeIgniter\HTTP\URI(),
  4.         new \CodeIgniter\HTTP\Response(new \Config\App()),
  5.         $options
  6. );

Working with the Library

Working with CURL requests is simply a matter of creating the Request and getting aResponse object back. It is meant to handle the communications. After thatyou have complete control over how the information is handled.

Making Requests

Most communication is done through the request() method, which fires off the request, and then returnsa Response instance to you. This takes the HTTP method, the url and an array of options as the parameters.

  1. $client = \Config\Services::curlrequest();
  2.  
  3. $response = $client->request('GET', 'https://api.github.com/user', [
  4.         'auth' => ['user', 'pass']
  5. ]);

Since the response is an instance of CodeIgniter\HTTP\Response you have all of the normal informationavailable to you:

  1. echo $response->getStatusCode();
  2. echo $response->getBody();
  3. echo $response->getHeader('Content-Type');
  4. $language = $response->negotiateLanguage(['en', 'fr']);

While the request() method is the most flexible, you can also use the following shortcut methods. Theyeach take the URL as the first parameter and an array of options as the second:

  1. * $client->get('http://example.com');
  2. * $client->delete('http://example.com');
  3. * $client->head('http://example.com');
  4. * $client->options('http://example.com');
  5. * $client->patch('http://example.com');
  6. * $client->put('http://example.com');
  7. * $client->post('http://example.com');

Base URI

A base_uri can be set as one of the options during the instantiation of the class. This allows you toset a base URI, and then make all requests with that client using relative URLs. This is especially handywhen working with APIs:

  1. $client = \Config\Services::curlrequest([
  2.         'base_uri' => 'https://example.com/api/v1/'
  3. ]);
  4.  
  5. // GET http:example.com/api/v1/photos
  6. $client->get('photos');
  7.  
  8. // GET http:example.com/api/v1/photos/13
  9. $client->delete('photos/13');

When a relative URI is provided to the request() method or any of the shortcut methods, it will be combinedwith the base_uri according to the rules described byRFC 2986, section 2. To save you some time, here are someexamples of how the combinations are resolved.

Using Responses

Each request() call returns a Response object that contains a lot of useful information and some helpfulmethods. The most commonly used methods let you determine the response itself.

You can get the status code and reason phrase of the response:

  1. $code   = $response->getStatusCode();    // 200
  2. $reason = $response->getReason();      // OK

You can retrieve headers from the response:

  1. // Get a header line
  2. echo $response->getHeaderLine('Content-Type');
  3.  
  4. // Get all headers
  5. foreach ($response->getHeaders() as $name => $value)
  6. {
  7.         echo $name .': '. $response->getHeaderLine($name) ."\n";
  8. }

The body can be retrieved using the getBody() method:

  1. $body = $response->getBody();

The body is the raw body provided by the remote getServer. If the content type requires formatting, you will needto ensure that your script handles that:

  1. if (strpos($response->getHeader('content-type'), 'application/json') !== false)
  2. {
  3.         $body = json_decode($body);
  4. }

Request Options

This section describes all of the available options you may pass into the constructor, the request() method,or any of the shortcut methods.

allow_redirects

By default, cURL will follow all “Location:” headers the remote servers send back. The allow_redirects optionallows you to modify how that works.

If you set the value to false, then it will not follow any redirects at all:

  1. $client->request('GET', 'http://example.com', ['allow_redirects' => false]);

Setting it to true will apply the default settings to the request:

  1. $client->request('GET', 'http://example.com', ['allow_redirects' => true]);
  2.  
  3. // Sets the following defaults:
  4. 'max'       => 5, // Maximum number of redirects to follow before stopping
  5. 'strict'    => true, // Ensure POST requests stay POST requests through redirects
  6. 'protocols' => ['http', 'https'] // Restrict redirects to one or more protocols

You can pass in array as the value of the allow_redirects option to specify new settings in place of the defaults:

  1. $client->request('GET', 'http://example.com', ['allow_redirects' => [
  2.         'max'       => 10,
  3.         'protocols' => ['https'] // Force HTTPS domains only.
  4. ]]);

Note

Following redirects does not work when PHP is in safe_mode or open_basedir is enabled.

auth

Allows you to provide Authentication details for HTTP Basic andDigest and authentication. Your script may have to do extra to supportDigest authentication - this simply passes the username and password along for you. The value must be anarray where the first element is the username, and the second is the password. The third parameter should bethe type of authentication to use, either basic or digest:

  1. $client->request('GET', 'http://example.com', ['auth' => ['username', 'password', 'digest']]);

body

There are two ways to set the body of the request for request types that support them, like PUT, OR POST.The first way is to use the setBody() method:

  1. $client->setBody($body)
  2.        ->request('put', 'http://example.com');

The second method is by passing a body option in. This is provided to maintain Guzzle API compatibility,and functions the exact same way as the previous example. The value must be a string:

  1. $client->request('put', 'http://example.com', ['body' => $body]);

cert

To specify the location of a PEM formatted client-side certificate, pass a string with the full path to thefile as the cert option. If a password is required, set the value to an array with the first elementas the path to the certificate, and the second as the password:

  1. $client->request('get', '/', ['cert' => ['/path/getServer.pem', 'password']);

connect_timeout

By default, CodeIgniter does not impose a limit for cURL to attempt to connect to a website. If you need tomodify this value, you can do so by passing the amount of time in seconds with the connect_timeout option.You can pass 0 to wait indefinitely:

  1. $response->request('GET', 'http://example.com', ['connect_timeout' => 0]);

This specifies the filename that CURL should use to read cookie values from, andto save cookie values to. This is done using the CURL_COOKIEJAR and CURL_COOKIEFILE options.An example:

  1. $response->request('GET', 'http://example.com', ['cookie' => WRITEPATH . 'CookieSaver.txt']);

debug

When debug is passed and set to true, this will enable additional debugging to echo to STDERR during thescript execution. This is done by passing CURLOPT_VERBOSE and echoing the output. So, when you’re running a built-inserver via spark serve you will see the output in the console. Otherwise, the output will be written tothe server’s error log.

$response->request(‘GET’, ‘http://example.com’, [‘debug’ => true]);

You can pass a filename as the value for debug to have the output written to a file:

  1. $response->request('GET', 'http://example.com', ['debug' => '/usr/local/curl_log.txt']);

delay

Allows you to pause a number of milliseconds before sending the request:

  1. // Delay for 2 seconds
  2. $response->request('GET', 'http://example.com', ['delay' => 2000]);

form_params

You can send form data in an application/x-www-form-urlencoded POST request by passing an associative array inthe form_params option. This will set the Content-Type header to application/x-www-form-urlencodedif it’s not already set:

  1. $client->request('POST', '/post', [
  2.         'form_params' => [
  3.                 'foo' => 'bar',
  4.                 'baz' => ['hi', 'there']
  5.         ]
  6. ]);

Note

form_params cannot be used with the multipart option. You will need to use one or the other.Use form_params for application/x-www-form-urlencoded request, and multipart for multipart/form-datarequests.

headers

While you can set any headers this request needs by using the setHeader() method, you can also pass an associativearray of headers in as an option. Each key is the name of a header, and each value is a string or array of stringsrepresenting the header field values:

  1. $client->request('get', '/', [
  2.         'headers' => [
  3.                 'User-Agent' => 'testing/1.0',
  4.                 'Accept'     => 'application/json',
  5.                 'X-Foo'      => ['Bar', 'Baz']
  6.         ]
  7. ]);

If headers are passed into the constructor they are treated as default values that will be overridden later by anyfurther headers arrays or calls to setHeader().

http_errors

By default, CURLRequest will fail if the HTTP code returned is greater than or equal to 400. You can sethttp_errors to false to return the content instead:

  1. $client->request('GET', '/status/500');
  2. // Will fail verbosely
  3.  
  4. $res = $client->request('GET', '/status/500', ['http_errors' => false]);
  5. echo $res->getStatusCode();
  6. // 500

json

The json option is used to easily upload JSON encoded data as the body of a request. A Content-Type headerof application/json is added, overwriting any Content-Type that might be already set. The data provided tothis option can be any value that json_encode() accepts:

  1. $response = $client->request('PUT', '/put', ['json' => ['foo' => 'bar']]);

Note

This option does not allow for any customization of the json_encode() function, or the Content-Typeheader. If you need that ability, you will need to encode the data manually, passing it through the setBody()method of CURLRequest, and set the Content-Type header with the setHeader() method.

multipart

When you need to send files and other data via a POST request, you can use the multipart option, along withthe CURLFile Class. The values should be an associative arrayof POST data to send. For safer usage, the legacy method of uploading files by prefixing their name with an _@_has been disabled. Any files that you want to send must be passed as instances of CURLFile:

  1. $post_data = [
  2.         'foo'      => 'bar',
  3.         'userfile' => new \CURLFile('/path/to/file.txt')
  4. ];

Note

multipart cannot be used with the form_params option. You can only use one or the other. Useform_params for application/x-www-form-urlencoded requests, and multipart for multipart/form-datarequests.

query

You can pass along data to send as query string variables by passing an associative array as the query option:

  1. // Send a GET request to /get?foo=bar
  2. $client->request('GET', '/get', ['query' => ['foo' => 'bar']]);

timeout

By default, cURL functions are allowed to run as long as they take, with no time limit. You can modify this with the timeoutoption. The value should be the number of seconds you want the functions to execute for. Use 0 to wait indefinitely:

  1. $response->request('GET', 'http://example.com', ['timeout' => 5]);

verify

This option describes the SSL certificate verification behavior. If the verify option is true, it enables theSSL certificate verification and uses the default CA bundle provided by the operating system. If set to false itwill disable the certificate verification (this is insecure, and allows man-in-the-middle attacks!). You can set itto a string that contains the path to a CA bundle to enable verification with a custom certificate. The default valueis true:

  1. // Use the system's CA bundle (this is the default setting)
  2. $client->request('GET', '/', ['verify' => true]);
  3.  
  4. // Use a custom SSL certificate on disk.
  5. $client->request('GET', '/', ['verify' => '/path/to/cert.pem']);
  6.  
  7. // Disable validation entirely. (Insecure!)
  8. $client->request('GET', '/', ['verify' => false]);

version

To set the HTTP protocol to use, you can pass a string or float with the version number (typically either 1.0or 1.1, 2.0 is currently unsupported.):

  1. // Force HTTP/1.0
  2. $client->request('GET', '/', ['version' => 1.0]);