IncomingRequest 类

IncomingRequest 类为来自客户端(如浏览器)的 HTTP 请求提供了面向对象的表示。它扩展并可以访问 Request 和 Message 类的所有方法,以及下面列出的方法。

访问请求

如果当前类是 CodeIgniter\Controller 的后代,则已经为你填充了请求类的一个实例,可以将其作为类属性访问:

<?php

namespace App\Controllers;

use CodeIgniter\Controller;

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

如果你不在控制器中,但仍然需要访问应用程序的 Request 对象,你可以通过 Services 类获取它的一个副本:

<?php

$request = service('request');

不过,如果类是控制器之外的任何其他类,最好是将请求作为依赖项传递,以便将其保存为类属性:

<?php

namespace App\Libraries;

use CodeIgniter\HTTP\RequestInterface;

class SomeClass
{
    protected $request;

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

$someClass = new SomeClass(service('request'));

确定请求类型

请求可以是几种类型,包括 AJAX 请求或来自命令行的请求。这可以通过 isAJAX() 和 isCLI() 方法检查:

<?php

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

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

备注

isAJAX() 方法取决于 X-Requested-With 头, 但在通过 JavaScript 发出的 XHR 请求中(即 fetch),该头默认不会发送。请参阅 AJAX 请求部分了解如何避免此问题。

is()

在 4.3.0 版本加入.

自 v4.3.0 起，你可以使用 is() 方法。它接受一个 HTTP 方法、'ajax' 或 'json'，并返回布尔值。

备注

HTTP 方法应该区分大小写，但参数是不区分大小写的。

<?php

// Checks HTTP methods. Returns boolean.
$request->is('get');
$request->is('post');
$request->is('put');
$request->is('delete');
$request->is('head');
$request->is('patch');
$request->is('options');

// Checks if it is an AJAX request. The same as `$request->isAJAX()`.
$request->is('ajax');

// Checks if it is a JSON request.
$request->is('json');

getMethod()

你可以使用 getMethod() 方法检查此请求所代表的 HTTP 方法:

<?php

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

HTTP 方法是区分大小写的，按照惯例，标准化方法是用全大写的 US-ASCII 字母定义的。

备注

在 v4.5.0 之前，默认情况下，该方法会返回小写字符串（即 'get'、'post' 等）。但这是一个 bug。

你可以通过用 strtolower() 包装调用来获取小写版本的字符串:

// 返回 'get'
$method = strtolower($request->getMethod());

你还可以使用 isSecure() 方法检查请求是否通过 HTTPS 连接发出:

<?php

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

检索输入

你可以通过 Request 对象检索来自 $_GET、$_POST、$_COOKIE、$_SERVER 和 $_ENV 的输入。数据不会自动过滤,并以请求中传递的原始输入数据形式返回。

备注

使用全局变量是不好的做法。基本上,应该避免使用它,建议使用 Request 对象的方法。

与直接访问它们($_POST['something'])的主要优点是,如果项不存在,这些方法将返回 null,并且你可以对数据进行过滤。这使你可以方便地使用数据,而无需先测试一个项是否存在。换句话说,通常你可能会做这样的事情:

<?php

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

使用 CodeIgniter 内置的方法,你可以简单地这样做:

<?php

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

获取数据

getGet()

getGet() 方法将从 $_GET 中获取。

$request->getGet()

getPost()

getPost() 方法将从 $_POST 中获取。

$request->getPost()

getCookie()

getCookie() 方法将从 $_COOKIE 中获取。

$request->getCookie()

getServer()

getServer() 方法将从 $_SERVER 中获取。

$request->getServer()

getEnv()

自 4.4.4 版本弃用: 该方法从一开始就不起作用。请使用 env() 替代。

getEnv() 方法将从 $_ENV 中获取。

$request->getEnv()

getPostGet()

此外，还有一些用于从 $_GET 或 $_POST 中检索信息的实用方法，同时保持控制查找的顺序：

$request->getPostGet() - 先检查 $_POST，然后是 $_GET

getGetPost()

$request->getGetPost() - 先检查 $_GET，然后是 $_POST

getVar()

重要

该方法仅存在于向后兼容中。不要在新项目中使用它。即使你已经在使用，我们也建议你使用另一个更合适的方法。

getVar() 方法将从 $_REQUEST 中获取，因此会返回任何来自 $_GET, $POST, 或者 $_COOKIE 的数据（取决于 php.ini request-order）。

警告

如果你只想验证 POST 数据，不要使用 getVar()。新值会覆盖旧值。如果 POST 值和 Cookie 有相同的名字，并且你在 request-order 中先设置 “P” 之后设置 “C”，则 POST 的值可能会被 Cookie 覆盖。

备注

如果传入的请求的 Content-Type 头设置为 application/json，则 getVar() 方法会返回 JSON 数据，而不是 $_REQUEST 数据。

获取 JSON 数据

你可以使用 getJSON() 将 php://input 的内容作为 JSON 流获取。

备注

这无法检查传入的数据是否为有效的 JSON。你只应在知道正在期望 JSON 时使用此方法。

<?php

$json = $request->getJSON();

默认情况下,这将返回 JSON 数据中的任何对象作为对象。如果你想要将其转换为关联数组,请在第一个参数中传递 true。

第二和第三个参数与 json_decode() PHP 函数的 $depth 和 $flags 参数对应。

从 JSON 获取特定数据

你可以通过向 getJsonVar() 传入变量名来从 JSON 流中获取特定的数据片段,用于获取所需的数据,或者可以使用“点”表示法深入到 JSON 中,以获取不在根级别的数据。

<?php

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

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

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

如果你希望结果是关联数组而不是对象，你可以在第二个参数中传入 true：

<?php

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

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

备注

有关“点”表示法的更多信息,请参阅 Array 辅助函数中的 dot_array_search() 文档。

检索原始数据(PUT、PATCH、DELETE)

最后,你可以使用 getRawInput() 将 php://input 的内容作为原始流获取:

<?php

$data = $request->getRawInput();

这将检索数据并将其转换为数组。像这样:

<?php

var_dump($request->getRawInput());

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

你还可以使用 getRawInputVar(),从原始流中获取指定的变量并对其进行过滤。

<?php

// When the request body is 'foo=one&bar=two&baz[]=10&baz[]=20'
var_dump($request->getRawInputVar('bar'));
// Outputs: two

// foo=one&bar=two&baz[]=10&baz[]=20
var_dump($request->getRawInputVar(['foo', 'bar']));
/*
 * Outputs:
 * [
 *      'foo' => 'one',
 *      'bar' => 'two'
 * ]
 */

// foo=one&bar=two&baz[]=10&baz[]=20
var_dump($request->getRawInputVar('baz'));
/*
 * Outputs:
 * [
 *      '10',
 *      '20'
 * ]
 */

// foo=one&bar=two&baz[]=10&baz[]=20
var_dump($request->getRawInputVar('baz.0'));
// Outputs: 10

过滤输入数据

为了保持应用程序的安全,你会想要过滤所有输入。你可以将要使用的过滤器类型作为这些方法的第二个参数传递。使用内置的 filter_var() 函数进行过滤。前往 PHP 手册获取有效过滤器类型列表。

过滤 POST 变量的代码如下:

<?php

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

上面提到的所有方法都支持作为第二个参数传递过滤器类型, getJSON() 和 getRawInput() 除外。

检索标头

你可以通过 headers() 方法访问与请求一起发送的任何标头,它返回一个数组,其中键是标头的名称,值是 CodeIgniter\HTTP\Header 的一个实例:

<?php

var_dump($request->headers());

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

如果你只需要单个标头,可以将名称传递给 header() 方法。这将以不区分大小写的方式获取指定的标头对象(如果存在)。如果不存在,则返回 null:

<?php

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

你可以始终使用 hasHeader() 来查看该请求中是否存在标头:

<?php

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

如果你需要将标头的值作为单行字符串,其中所有值在一行中,可以使用 getHeaderLine() 方法:

<?php

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

如果你需要将标头及其名称和值合并为单个字符串,只需将标头转换为字符串:

<?php

echo (string) $header;

请求 URL

你可以通过 $request->getUri() 方法检索表示当前 URI 的 URI 对象。你可以将此对象转换为字符串以获取当前请求的完整 URL:

<?php

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

该对象使你能够自行获取请求的任何部分:

<?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->getRoutePath();      // path/to/page
echo $uri->getQuery();          // foo=bar&bar=baz
print_r($uri->getSegments());   // Array ( [0] => path [1] => to [2] => page )
echo $uri->getSegment(1);       // path
echo $uri->getTotalSegments();  // 3

你可以使用 getRoutePath() 方法来处理当前 URI 字符串（相对于你的 baseURL 的路径）。

备注

自 v4.4.0 版本开始，可以使用 getRoutePath() 方法。在 v4.4.0 之前，getPath() 方法返回相对于你的 baseURL 的路径。

上传的文件

可以通过 $request->getFiles() 获取有关所有上传文件信息,它返回 CodeIgniter\HTTP\Files\UploadedFile 实例的数组。这有助于减轻使用上传文件时的痛苦,并使用最佳实践来最大程度地减少任何安全风险。

<?php

$files = $request->getFiles();

参见使用上传的文件以获取详细信息。

你可以根据 HTML 文件输入中给出的文件名检索单独上传的文件:

<?php

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

你可以检索作为多文件上传一部分上传的同名文件数组,基于 HTML 文件输入中给出的文件名:

<?php

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

备注

这里的文件对应于 $_FILES。即使用户仅点击表单的提交按钮而不上传任何文件,文件也会存在。你可以通过 UploadedFile 中的 isValid() 方法检查文件是否实际被上传。有关详细信息,请参阅验证文件。

内容协商

你可以通过 negotiate() 方法轻松地与请求协商内容类型:

<?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']);

有关更多详细信息,请参阅内容协商页面。

类参考

备注

除了这里列出的方法之外,此类还继承了请求类和消息类的方法。

父类提供的可用方法有:

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()

class CodeIgniter\HTTP\IncomingRequest

isCLI()

返回:: 如果请求是从命令行发起的,则为 True,否则为 False
返回类型:: bool

isAJAX()

返回:: 如果请求是 AJAX 请求,则为 True,否则为 False
返回类型:: bool

isSecure()

返回:: 如果请求是 HTTPS 请求,则为 True,否则为 False
返回类型:: bool

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

参数:

$index (string) – 要查找的变量/键的名称。
$filter (int) – 要应用的过滤器类型。过滤器列表可在过滤器类型中找到。
$flags (int) – 要应用的标志。标志列表可在过滤器 flag 中找到。

返回:

如果没有提供参数,则返回 $_REQUEST,否则如果找到则返回 REQUEST 值,如果没找到则为 null

返回类型:

重要

该方法仅存在于向后兼容中。不要在新项目中使用它。即使你已经在使用，我们也建议你使用另一个更合适的方法。

这个方法与 getGet() 相同，只是它获取的是 REQUEST 数据。

getGet([$index = null[, $filter = null[, $flags = null]]])

参数:

$index (string) – 要查找的变量/键的名称。
$filter (int) – 要应用的过滤类型。过滤器类型列表可以在过滤器类型中找到。
$flags (int) – 要应用的标记。标记列表可以在过滤器 flag 中找到。

返回:

如果没有提供参数，则为 $_GET，否则如果找到 GET 值则为 GET 值，如果未找到则为 null

返回类型:

第一个参数将包含你正在查找的 GET 项的名称：

<?php

$request->getGet('some_data');

如果尝试检索的项目不存在,该方法将返回 null。

第二个可选参数允许你通过 PHP 的过滤器运行数据。将所需的过滤器类型作为第二个参数传递:

<?php

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

若要返回所有 GET 项,请不带任何参数调用。

要返回所有 GET 项并通过过滤器传递它们,请将第一个参数设置为 null,同时将第二个参数设置为要使用的过滤器:

<?php

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

要返回多个 GET 参数的数组,请传递所有所需键的数组:

<?php

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

这里也应用了相同的规则,要使用过滤检索参数,请将第二个参数设置为要应用的过滤器类型:

<?php

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

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

参数:

$index (string) – 要查找的变量/键的名称。
$filter (int) – 要应用的过滤器类型。过滤器列表可在这里找到。
$flags (int) – 要应用的标志。标志列表可在这里找到。

返回:

如果没有提供参数,则返回 $_POST,否则如果找到则返回 POST 值,如果没找到则为 null

返回类型:

此方法与 getGet() 相同,只是它获取 POST 数据。

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

参数:

$index (string) – 要查找的变量/键的名称。
$filter (int) – 要应用的过滤器类型。过滤器列表可在过滤器类型中找到。
$flags (int) – 要应用的标志。标志列表可在过滤器 flag 中找到。

返回:

如果没有指定参数,则返回 $_POST 和 $_GET 组合(冲突时优先 POST 值), 否则首先查找 POST 值,找不到则查找 GET 值,如果没找到则返回 null

返回类型:

这个方法的工作原理与 getPost() 和 getGet() 基本相同,只是结合了两者。它将在 POST 和 GET 流中搜索数据,先在 POST 中查找,然后在 GET 中查找:

<?php

$request->getPostGet('field1');

如果没有指定索引,它将返回 POST 和 GET 流组合。如果名称冲突,将优先 POST 数据。

getGetPost([$index = null[, $filter = null[, $flags = null]]])

参数:

$index (string) – 要查找的变量/键的名称。
$filter (int) – 要应用的过滤器类型。过滤器列表可在过滤器类型中找到。
$flags (int) – 要应用的标志。标志列表可在过滤器 flag 中找到。

返回:

如果没有指定参数,则返回 $_GET 和 $_POST 组合(冲突时优先 GET 值), 否则首先查找 GET 值,找不到则查找 POST 值,如果没找到则返回 null

返回类型:

这个方法的工作原理与 getPost() 和 getGet() 基本相同,只是结合了两者。它将在 GET 和 POST 流中搜索数据,先在 GET 中查找,然后在 POST 中查找:

<?php

$request->getGetPost('field1');

如果没有指定索引,它将返回 GET 和 POST 流组合。如果名称冲突,将优先 GET 数据。

getCookie([$index = null[, $filter = null[, $flags = null]]])

参数:

$index (array|string|null) – COOKIE 名称
$filter (int) – 要应用的过滤器类型。过滤器列表可在过滤器类型中找到。
$flags (int) – 要应用的标志。标志列表可在过滤器 flag 中找到。

返回:

如果没有提供参数,则返回 $_COOKIE,否则如果找到则返回 COOKIE 值,如果没有找到则为 null

返回类型:

此方法与 getPost() 和 getGet() 相同,只是它获取 cookie 数据:

<?php

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

要返回多个 cookie 值的数组,请传递所有所需键的数组:

<?php

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

备注

与 Cookie 辅助函数函数 get_cookie() 不同,此方法不会在配置的 Config\Cookie::$prefix 值前加上前缀。

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

参数:

$index (array|string|null) – 值名称
$filter (int) – 要应用的过滤器类型。过滤器列表可在过滤器类型中找到。
$flags (int) – 要应用的标志。标志列表可在过滤器 flag 中找到。

返回:

如果找到则返回 $_SERVER 项的值,否则为 null

返回类型:

此方法与 getPost()、getGet() 和 getCookie() 方法相同,只是它获取 Server 数据($_SERVER):

<?php

$request->getServer('some_data');

要返回多个 $_SERVER 值的数组,请传递所有所需键的数组。

<?php

$request->getServer(['SERVER_PROTOCOL', 'REQUEST_URI']);

getUserAgent()

返回:: 在 SERVER 数据中找到的用户代理字符串,如果没有找到则为 null。
返回类型:: CodeIgniter\HTTP\UserAgent

此方法返回来自 SERVER 数据的用户代理实例:

<?php

$request->getUserAgent();

getPath()

返回:: 相对于 baseURL 的当前 URI 路径
返回类型:: string

该方法返回相对于 baseURL 的当前 URI 路径。

备注

在 v4.4.0 之前，这是确定“当前 URI”的最安全的方法，因为 IncomingRequest::$uri 可能不知道完整的 App 配置的 base URL。

setPath($path)

自 4.4.0 版本弃用.

参数:

$path (string) – 用作当前 URI 的相对路径

返回:

此传入请求

返回类型:

IncomingRequest

备注

在 v4.4.0 之前，主要用于测试目的，这允许你设置当前请求的相对路径值，而不是依赖于 URI 检测。这也会更新底层的 URI 实例的新路径。