<?php
namespace Config;
use CodeIgniter\Config\BaseConfig;
class CURLRequest extends BaseConfig
// ...
public bool $shareOptions = true;
If you send more than one request with an instance of the class, this behavior
may cause an error request with unnecessary headers and body.
Before v4.2.0, the request body is not reset even if $shareOptions is false due to a bug.
The library can be loaded either manually or through the Services class.
To load with the Services class call the curlrequest() method or global function service():
<?php
$client = service('curlrequest'); // Since v4.5.0, this code is recommended due to performance improvements
// The code above is the same as the code below.
$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:
<?php
$options = [
'baseURI' => 'http://example.com/api/v1/',
'timeout' => 3,
$client = service('curlrequest', $options);
When $shareOptions is false, the default options passed to the class constructor will be used for all requests. Other options will be reset after sending a request.
When creating the class manually, you need to pass a few dependencies in. The first parameter is an
instance of the Config\App class. The second parameter is a URI instance. The third
parameter is a Response object. The fourth parameter is the optional default $options array:
<?php
use Config\App;
$client = new \CodeIgniter\HTTP\CURLRequest(
config(App::class),
new \CodeIgniter\HTTP\URI(),
new \CodeIgniter\HTTP\Response(config(App::class)),
$options,
Working with CURL requests is simply a matter of creating the Request and getting a
Response object back. It is meant to handle the communications. After that
you have complete control over how the information is handled.
Most communication is done through the request() method, which fires off the request, and then returns
a Response instance to you. This takes the HTTP method, the url and an array of options as the parameters.
<?php
$client = service('curlrequest');
$response = $client->request('GET', 'https://api.github.com/user', [
'auth' => ['user', 'pass'],
Important
By default, CURLRequest will throw HTTPException if the HTTP
code returned is greater than or equal to 400. If you want to get the response,
see the http_errors option.
When $shareOptions is false, the options passed to the method will be used for the request. After sending the request, they will be cleared. If you want to use the options to all requests, pass the options in the constructor.
Since the response is an instance of CodeIgniter\HTTP\Response you have all of the normal information
available to you:
<?php
echo $response->getStatusCode();
echo $response->getBody();
echo $response->header('Content-Type');
$language = $response->negotiateLanguage(['en', 'fr']);
While the request() method is the most flexible, you can also use the following shortcut methods. They
each take the URL as the first parameter and an array of options as the second:
<?php
$client->get('http://example.com');
$client->delete('http://example.com');
$client->head('http://example.com');
$client->options('http://example.com');
$client->patch('http://example.com');
$client->put('http://example.com');
$client->post('http://example.com');
Base URI
A baseURI can be set as one of the options during the instantiation of the class. This allows you to
set a base URI, and then make all requests with that client using relative URLs. This is especially handy
when working with APIs:
<?php
$client = service('curlrequest', [
'baseURI' => 'https://example.com/api/v1/',
// GET http:example.com/api/v1/photos
$client->get('photos');
// GET http:example.com/api/v1/photos/13
$client->delete('photos/13');
When a relative URI is provided to the request() method or any of the shortcut methods, it will be combined
with the baseURI according to the rules described by
RFC 2986, section 2. To save you some time, here are some
examples of how the combinations are resolved.
baseURI
Result
http://foo.com
http://foo.com/bar
http://foo.com/foo
http://foo.com/bar
http://foo.com/foo
http://foo.com/bar
http://foo.com/foo/
http://foo.com/foo/bar
http://foo.com
http://baz.com
http://baz.com
http://foo.com/?bar
http://foo.com/bar
Each request() call returns a Response object that contains a lot of useful information and some helpful
methods. The most commonly used methods let you determine the response itself.
You can get the status code and reason phrase of the response:
<?php
$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK
You can retrieve headers from the response:
<?php
// Get a header line
echo
$response->getHeaderLine('Content-Type');
// Get all headers
foreach ($response->headers() as $name => $value) {
echo $name . ': ' . $response->getHeaderLine($name) . "\n";
The body can be retrieved using the getBody() method:
<?php
$body = $response->getBody();
The body is the raw body provided by the remote server. If the content type requires formatting, you will need
to ensure that your script handles that:
<?php
if (str_contains($response->header('content-type'), 'application/json')) {
$body = json_decode($body);
This section describes all of the available options you may pass into the constructor, the request() method,
or any of the shortcut methods.
By default, cURL will not follow any “Location:” headers the remote servers send
back. The allow_redirects option allows you to modify how that works.
If you set the value to true, then it will follow redirects:
<?php
$client->request('GET', 'http://example.com', ['allow_redirects' => true]);
* Sets the following defaults:
* 'max' => 5, // Maximum number of redirects to follow before stopping
* 'strict' => true, // Ensure POST requests stay POST requests through redirects
* 'protocols' => ['http', 'https'] // Restrict redirects to one or more protocols
Warning
Please note that enabling redirects may redirect to a URL that you
do not expect and may enable SSRF attacks.
Setting it to false will apply the default settings to the request:
<?php
$client->request('GET', 'http://example.com', ['allow_redirects' => false]);
You can pass in array as the value of the allow_redirects option to specify new settings in place of the defaults:
<?php
$client->request('GET', 'http://example.com', ['allow_redirects' => [
'max' => 10,
'protocols' => ['https'], // Force HTTPS domains only.
Following redirects does not work when PHP is in safe_mode or open_basedir is enabled.
Allows you to provide Authentication details for HTTP Basic and
Digest and authentication. Your script may have to do extra to support
Digest authentication - this simply passes the username and password along for you. The value must be an
array where the first element is the username, and the second is the password. The third parameter should be
the type of authentication to use, either basic or digest:
<?php
$client->request('GET', 'http://example.com', ['auth' => ['username', 'password', 'digest']]);
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:
<?php
$client->setBody($body)->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:
<?php
$client->request('PUT', 'http://example.com', ['body' => $body]);
To specify the location of a PEM formatted client-side certificate, pass a string with the full path to the
file as the cert option. If a password is required, set the value to an array with the first element
as the path to the certificate, and the second as the password:
<?php
$client->request('GET', '/', ['cert' => ['/path/server.pem', 'password']]);
By default, CodeIgniter does not impose a limit for cURL to attempt to connect to a website. If you need to
modify 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:
<?php
$client->request('GET', 'http://example.com', ['connect_timeout' => 0]);
This specifies the filename that CURL should use to read cookie values from, and
to save cookie values to. This is done using the CURL_COOKIEJAR and CURL_COOKIEFILE options.
An example:
<?php
$client->request('GET', 'http://example.com', ['cookie' => WRITEPATH . 'CookieSaver.txt']);
When debug is passed and set to true, this will enable additional debugging to echo to STDERR during the
script execution.
This is done by passing CURLOPT_VERBOSE and echoing the output. So, when you’re running a built-in
server via spark serve, you will see the output in the console. Otherwise, the output will be written to
the server’s error log.
<?php
$client->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:
<?php
$client->request('GET', 'http://example.com', ['debug' => '/usr/local/curl_log.txt']);
You can send form data in an application/x-www-form-urlencoded POST request by passing an associative array in
the form_params option. This will set the Content-Type header to application/x-www-form-urlencoded
if it’s not already set:
<?php
$client->request('POST', '/post', [
'form_params' => [
'foo' => 'bar',
'baz' => ['hi', 'there'],
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-data
requests.
