IncomingRequest Class

The IncomingRequest class provides an object-oriented representation of an HTTP request from a client, like a browser. It extends from, and has access to all the methods of the Request and Message classes, in addition to the methods listed below.

Accessing the Request

An instance of the request class already populated for you if the current class is a descendant of CodeIgniter\Controller and can be accessed as a class property:

<?php

namespace App\Controllers;

use CodeIgniter\Controller;

class UserController extends Controller
{
    public function index()
    {
        if ($this->request->isAJAX()) {
            // ...
        }
    }
}

If you are not within a controller, but still need access to the application’s Request object, you can get a copy of it through the Services class:

<?php

$request = \Config\Services::request();

It’s preferable, though, to pass the request in as a dependency if the class is anything other than the controller, where you can save it as a class property:

<?php

use CodeIgniter\HTTP\RequestInterface;

class SomeClass
{
    protected $request;

    public function __construct(RequestInterface $request)
    {
        $this->request = $request;
    }
}

$someClass = new SomeClass(\Config\Services::request());

Determining Request Type

A request could be of several types, including an AJAX request or a request from the command line. This can be checked with the isAJAX() and isCLI() methods:

<?php

// Check for AJAX request.
if ($request->isAJAX()) {
    // ...
}

// Check for CLI Request
if ($request->isCLI()) {
    // ...
}

Note

The isAJAX() method depends on the X-Requested-With header, which in some cases is not sent by default in XHR requests via JavaScript (i.e., fetch). See the AJAX Requests section on how to avoid this problem.

You can check the HTTP method that this request represents with the method() method:

<?php

// Returns 'post'
$method = $request->getMethod();

By default, the method is returned as a lower-case string (i.e., ‘get’, ‘post’, etc). You can get an uppercase version by wrapping the call in strtoupper():

// Returns 'GET'
$method = strtoupper($request->getMethod());

You can also check if the request was made through and HTTPS connection with the isSecure() method:

<?php

if (! $request->isSecure()) {
    force_https();
}

Retrieving Input

You can retrieve input from $_SERVER, $_GET, $_POST, and $_ENV through the Request object. The data is not automatically filtered and returns the raw input data as passed in the request. The main advantages to using these methods instead of accessing them directly ($_POST[‘something’]), is that they will return null if the item doesn’t exist, and you can have the data filtered. This lets you conveniently use data without having to test whether an item exists first. In other words, normally you might do something like this:

<?php

$something = $_POST['foo'] ?? null;

With CodeIgniter’s built-in methods you can simply do this:

<?php

$something = $request->getVar('foo');

The getVar() method will pull from $_REQUEST, so will return any data from $_GET, $POST, or $_COOKIE. While this is convenient, you will often need to use a more specific method, like:

  • $request->getGet()

  • $request->getPost()

  • $request->getServer()

  • $request->getCookie()

In addition, there are a few utility methods for retrieving information from either $_GET or $_POST, while maintaining the ability to control the order you look for it:

  • $request->getPostGet() - checks $_POST first, then $_GET

  • $request->getGetPost() - checks $_GET first, then $_POST

Getting JSON data

You can grab the contents of php://input as a JSON stream with getJSON().

Note

This has no way of checking if the incoming data is valid JSON or not, you should only use this method if you know that you’re expecting JSON.

<?php

$json = $request->getJSON();

By default, this will return any objects in the JSON data as objects. If you want that converted to associative arrays, pass in true as the first parameter.

The second and third parameters match up to the depth and options arguments of the json_decode PHP function.

If the incoming request has a CONTENT_TYPE header set to “application/json”, you can also use getVar() to get the JSON stream. Using getVar() in this way will always return an object.

Get Specific Data from JSON

You can get a specific piece of data from a JSON stream by passing a variable name into getVar() for the data that you want or you can use “dot” notation to dig into the JSON to get data that is not on the root level.

<?php

/*
 * With a request body of:
 * {
 *     "foo": "bar",
 *     "fizz": {
 *         "buzz": "baz"
 *     }
 * }
 */

$data = $request->getVar('foo');
// $data = "bar"

$data = $request->getVar('fizz.buzz');
// $data = "baz"

If you want the result to be an associative array instead of an object, you can use getJsonVar() instead and pass true in the second parameter. This function can also be used if you can’t guarantee that the incoming request will have the correct CONTENT_TYPE header.

<?php

// With the same request as above
$data = $request->getJsonVar('fizz');
// $data->buzz = "baz"

$data = $request->getJsonVar('fizz', true);
// $data = ["buzz" => "baz"]

Note

See the documentation for dot_array_search() in the Array helper for more information on “dot” notation.

Retrieving Raw data (PUT, PATCH, DELETE)

Finally, you can grab the contents of php://input as a raw stream with getRawInput():

<?php

$data = $request->getRawInput();

This will retrieve data and convert it to an array. Like this:

<?php

var_dump($request->getRawInput());

/*
 * Outputs:
 * [
 *     'Param1' => 'Value1',
 *     'Param2' => 'Value2',
 * ]
 */

Filtering Input Data

To maintain security of your application, you will want to filter all input as you access it. You can pass the type of filter to use as the second parameter of any of these methods. The native filter_var() function is used for the filtering. Head over to the PHP manual for a list of valid filter types.

Filtering a POST variable would look like this:

<?php

$email = $request->getVar('email', FILTER_SANITIZE_EMAIL);

All of the methods mentioned above support the filter type passed in as the second parameter, with the exception of getJSON().

Retrieving Headers

You can get access to any header that was sent with the request with the headers() method, which returns an array of all headers, with the key as the name of the header, and the value is an instance of CodeIgniter\HTTP\Header:

<?php

var_dump($request->headers());

/*
 * Outputs:
 * [
 *     'Host'          => CodeIgniter\HTTP\Header,
 *     'Cache-Control' => CodeIgniter\HTTP\Header,
 *     'Accept'        => CodeIgniter\HTTP\Header,
 * ]
 */

If you only need a single header, you can pass the name into the header() method. This will grab the specified header object in a case-insensitive manner if it exists. If not, then it will return null:

<?php

// these are all equivalent
$host = $request->header('host');
$host = $request->header('Host');
$host = $request->header('HOST');

You can always use hasHeader() to see if the header existed in this request:

<?php

if ($request->hasHeader('DNT')) {
    // Don't track something...
}

If you need the value of header as a string with all values on one line, you can use the getHeaderLine() method:

<?php

// Accept-Encoding: gzip, deflate, sdch
echo 'Accept-Encoding: ' . $request->getHeaderLine('accept-encoding');

If you need the entire header, with the name and values in a single string, simply cast the header as a string:

<?php

echo (string) $header;

The Request URL

You can retrieve a URI object that represents the current URI for this request through the $request->getUri() method. You can cast this object as a string to get a full URL for the current request:

<?php

$uri = (string) $request->getUri();

The object gives you full abilities to grab any part of the request on it’s own:

<?php

$uri = $request->getUri();

echo $uri->getScheme();         // http
echo $uri->getAuthority();      // snoopy:password@example.com:88
echo $uri->getUserInfo();       // snoopy:password
echo $uri->getHost();           // example.com
echo $uri->getPort();           // 88
echo $uri->getPath();           // /path/to/page
echo $uri->getQuery();          // foo=bar&bar=baz
echo $uri->getSegments();       // ['path', 'to', 'page']
echo $uri->getSegment(1);       // 'path'
echo $uri->getTotalSegments();  // 3

You can work with the current URI string (the path relative to your baseURL) using the getPath() and setPath() methods. Note that this relative path on the shared instance of IncomingRequest is what the URL Helper functions use, so this is a helpful way to “spoof” an incoming request for testing:

<?php

use CodeIgniter\Test\CIUnitTestCase;

final class MyMenuTest extends CIUnitTestCase
{
    public function testActiveLinkUsesCurrentUrl()
    {
        service('request')->setPath('users/list');
        $menu = new MyMenu();
        $this->assertTrue('users/list', $menu->getActiveLink());
    }
}

Uploaded Files

Information about all uploaded files can be retrieved through $request->getFiles(), which returns an array of CodeIgniter\HTTP\Files\UploadedFile instance. This helps to ease the pain of working with uploaded files, and uses best practices to minimize any security risks.

<?php

$files = $request->getFiles();

See Working with Uploaded Files for the details.

You can retrieve a single file uploaded on its own, based on the filename given in the HTML file input:

<?php

$file = $request->getFile('userfile');

You can retrieve an array of same-named files uploaded as part of a multi-file upload, based on the filename given in the HTML file input:

<?php

$files = $request->getFileMultiple('userfile');

Note

The files here correspond to $_FILES. Even if a user just clicks submit button of a form and does not upload any file, the file will still exist. You can check that the file was actually uploaded by the isValid() method in UploadedFile. See Verify a File for more details.

Content Negotiation

You can easily negotiate content types with the request through the negotiate() method:

<?php

$language    = $request->negotiate('language', ['en-US', 'en-GB', 'fr', 'es-mx']);
$imageType   = $request->negotiate('media', ['image/png', 'image/jpg']);
$charset     = $request->negotiate('charset', ['UTF-8', 'UTF-16']);
$contentType = $request->negotiate('media', ['text/html', 'text/xml']);
$encoding    = $request->negotiate('encoding', ['gzip', 'compress']);

See the Content Negotiation page for more details.

Class Reference

Note

In addition to the methods listed here, this class inherits the methods from the Request Class and the Message Class.

The methods provided by the parent classes that are available are:

  • CodeIgniter\HTTP\Request::getIPAddress()

  • CodeIgniter\HTTP\Request::isValidIP()

  • CodeIgniter\HTTP\Request::getMethod()

  • CodeIgniter\HTTP\Request::setMethod()

  • CodeIgniter\HTTP\Request::getServer()

  • CodeIgniter\HTTP\Request::getEnv()

  • CodeIgniter\HTTP\Request::setGlobal()

  • CodeIgniter\HTTP\Request::fetchGlobal()

  • CodeIgniter\HTTP\Message::getBody()

  • CodeIgniter\HTTP\Message::setBody()

  • CodeIgniter\HTTP\Message::appendBody()

  • CodeIgniter\HTTP\Message::populateHeaders()

  • CodeIgniter\HTTP\Message::headers()

  • CodeIgniter\HTTP\Message::header()

  • CodeIgniter\HTTP\Message::hasHeader()

  • CodeIgniter\HTTP\Message::getHeaderLine()

  • CodeIgniter\HTTP\Message::setHeader()

  • CodeIgniter\HTTP\Message::removeHeader()

  • CodeIgniter\HTTP\Message::appendHeader()

  • CodeIgniter\HTTP\Message::prependHeader()

  • CodeIgniter\HTTP\Message::getProtocolVersion()

  • CodeIgniter\HTTP\Message::setProtocolVersion()

CodeIgniter\\HTTP\\IncomingRequest
isCLI()
Returns

True if the request was initiated from the command line, otherwise false.

Return type

bool

isAJAX()
Returns

True if the request is an AJAX request, otherwise false.

Return type

bool

isSecure()
Returns

True if the request is an HTTPS request, otherwise false.

Return type

bool

getVar([$index = null[, $filter = null[, $flags = null]]])
Parameters

  • $index (string) – The name of the variable/key to look for.

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

  • $flags (int) – Flags to apply. A list of flags can be found here.

Returns

$_REQUEST if no parameters supplied, otherwise the REQUEST value if found, or null if not

Return type

mixed|null

The first parameter will contain the name of the REQUEST item you are looking for:

<?php

$request->getVar('some_data');

The method returns null if the item you are attempting to retrieve does not exist.

The second optional parameter lets you run the data through the PHP’s filters. Pass in the desired filter type as the second parameter:

<?php

$request->getVar('some_data', FILTER_SANITIZE_FULL_SPECIAL_CHARS);

To return an array of all POST items call without any parameters.

To return all POST items and pass them through the filter, set the first parameter to null while setting the second parameter to the filter you want to use:

<?php

$request->getVar(null, FILTER_SANITIZE_FULL_SPECIAL_CHARS);
// returns all POST items with string sanitation

To return an array of multiple POST parameters, pass all the required keys as an array:

<?php

$request->getVar(['field1', 'field2']);

Same rule applied here, to retrieve the parameters with filtering, set the second parameter to the filter type to apply:

<?php

$request->getVar(['field1', 'field2'], FILTER_SANITIZE_FULL_SPECIAL_CHARS);
getGet([$index = null[, $filter = null[, $flags = null]]])
Parameters

  • $index (string) – The name of the variable/key to look for.

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

  • $flags (int) – Flags to apply. A list of flags can be found here.

Returns

$_GET if no parameters supplied, otherwise the GET value if found, or null if not

Return type

mixed|null

This method is identical to getVar(), only it fetches GET data.

getPost([$index = null[, $filter = null[, $flags = null]]])
Parameters

  • $index (string) – The name of the variable/key to look for.

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

  • $flags (int) – Flags to apply. A list of flags can be found here.

Returns

$_POST if no parameters supplied, otherwise the POST value if found, or null if not

Return type

mixed|null

This method is identical to getVar(), only it fetches POST data.

getPostGet([$index = null[, $filter = null[, $flags = null]]])
Parameters

  • $index (string) – The name of the variable/key to look for.

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

  • $flags (int) – Flags to apply. A list of flags can be found here.

Returns

$_POST if no parameters supplied, otherwise the POST value if found, or null if not

Return type

mixed|null

This method works pretty much the same way as getPost() and getGet(), only combined. It will search through both POST and GET streams for data, looking first in POST, and then in GET:

<?php

$request->getPostGet('field1');
getGetPost([$index = null[, $filter = null[, $flags = null]]])
Parameters

  • $index (string) – The name of the variable/key to look for.

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

  • $flags (int) – Flags to apply. A list of flags can be found here.

Returns

$_POST if no parameters supplied, otherwise the POST value if found, or null if not

Return type

mixed|null

This method works pretty much the same way as getPost() and getGet(), only combined. It will search through both POST and GET streams for data, looking first in GET, and then in POST:

<?php

$request->getGetPost('field1');
getCookie([$index = null[, $filter = null[, $flags = null]]])
Parameters

  • $index (mixed) – COOKIE name

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

  • $flags (int) – Flags to apply. A list of flags can be found here.

Returns

$_COOKIE if no parameters supplied, otherwise the COOKIE value if found or null if not

Return type

mixed

This method is identical to getPost() and getGet(), only it fetches cookie data:

<?php

$request->getCookie('some_cookie');
$request->getCookie('some_cookie', FILTER_SANITIZE_FULL_SPECIAL_CHARS); // with filter

To return an array of multiple cookie values, pass all the required keys as an array:

<?php

$request->getCookie(['some_cookie', 'some_cookie2']);

Note

Unlike the Cookie Helper function get_cookie(), this method does NOT prepend your configured Config\Cookie::$prefix value.

getServer([$index = null[, $filter = null[, $flags = null]]])
Parameters

  • $index (mixed) – Value name

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

  • $flags (int) – Flags to apply. A list of flags can be found here.

Returns

$_SERVER item value if found, null if not

Return type

mixed

This method is identical to the getPost(), getGet() and getCookie() methods, only it fetches getServer data ($_SERVER):

<?php

$request->getServer('some_data');

To return an array of multiple $_SERVER values, pass all the required keys as an array.

<?php

$request->getServer(['SERVER_PROTOCOL', 'REQUEST_URI']);
getUserAgent([$filter = null])
Parameters

  • $filter (int) – The type of filter to apply. A list of filters can be found here.

Returns

The User Agent string, as found in the SERVER data, or null if not found.

Return type

mixed

This method returns the User Agent string from the SERVER data:

<?php

$request->getUserAgent();
getPath()
Returns

The current URI path relative to $_SERVER['SCRIPT_NAME']

Return type

string

This is the safest method to determine the “current URI”, since IncomingRequest::$uri may not be aware of the complete App configuration for base URLs.

setPath($path)
Parameters

  • $path (string) – The relative path to use as the current URI

Returns

This Incoming Request

Return type

IncomingRequest

Used mostly just for testing purposes, this allows you to set the relative path value for the current request instead of relying on URI detection. This will also update the underlying URI instance with the new path.