# Requests ¶

Requests made to an application are represented in terms of yii\web\Request objects which provide information such as request parameters, HTTP headers, cookies, etc. For a given request, you can get access to the corresponding request object via the `request` application component which is an instance of yii\web\Request, by default. In this section, we will describe how you can make use of this component in your applications.

## Request Parameters ¶

To get request parameters, you can call get() and post() methods of the `request` component. They return the values of `$_GET` and `$_POST`, respectively. For example,

    $request = Yii::$app->request;

    $get = $request->get();
    // equivalent to: $get = $_GET;

    $id = $request->get('id');
    // equivalent to: $id = isset($_GET['id']) ? $_GET['id'] : null;

    $id = $request->get('id', 1);
    // equivalent to: $id = isset($_GET['id']) ? $_GET['id'] : 1;

    $post = $request->post();
    // equivalent to: $post = $_POST;

    $name = $request->post('name');
    // equivalent to: $name = isset($_POST['name']) ? $_POST['name'] : null;

    $name = $request->post('name', '');
    // equivalent to: $name = isset($_POST['name']) ? $_POST['name'] : '';

> Info: Instead of directly accessing `$_GET` and `$_POST` to retrieve the request parameters, it is recommended that you get them via the `request` component as shown above. This will make writing tests easier because you can create a mock request component with faked request data.

When implementing RESTful APIs, you often need to retrieve parameters that are submitted via PUT, PATCH or other request methods. You can get these parameters by calling the yii\web\Request::getBodyParam() methods. For example,

    $request = Yii::$app->request;

    // returns all parameters
    $params = $request->bodyParams;

    // returns the parameter "id"
    $param = $request->getBodyParam('id');

> Info: Unlike `GET` parameters, parameters submitted via `POST`, `PUT`, `PATCH` etc. are sent in the request body. The `request` component will parse these parameters when you access them through the methods described above. You can customize the way how these parameters are parsed by configuring the yii\web\Request::$parsers property.

## Request Methods ¶

You can get the HTTP method used by the current request via the expression `Yii::$app->request->method`. A whole set of boolean properties is also provided for you to check if the current method is of certain type. For example,

    $request = Yii::$app->request;

    if ($request->isAjax) { /* the request is an AJAX request */ }
    if ($request->isGet)  { /* the request method is GET */ }
    if ($request->isPost) { /* the request method is POST */ }
    if ($request->isPut)  { /* the request method is PUT */ }

## Request URLs ¶

The `request` component provides many ways of inspecting the currently requested URL.

Assuming the URL being requested is `http://example.com/admin/index.php/product?id=100`, you can get various parts of this URL as summarized in the following:

- url: returns `/admin/index.php/product?id=100`, which is the URL without the host info part.
- absoluteUrl: returns `http://example.com/admin/index.php/product?id=100`, which is the whole URL including the host info part.
- hostInfo: returns `http://example.com`, which is the host info part of the URL.
- pathInfo: returns `/product`, which is the part after the entry script and before the question mark (query string).
- queryString: returns `id=100`, which is the part after the question mark.
- baseUrl: returns `/admin`, which is the part after the host info and before the entry script name.
- scriptUrl: returns `/admin/index.php`, which is the URL without path info and query string.
- serverName: returns `example.com`, which is the host name in the URL.
- serverPort: returns 80, which is the port used by the Web server.

## HTTP Headers ¶

You can get the HTTP header information through the header collection returned by the yii\web\Request::$headers property. For example,

    // $headers is an object of yii\web\HeaderCollection
    $headers = Yii::$app->request->headers;

    // returns the Accept header value
    $accept = $headers->get('Accept');

    if ($headers->has('User-Agent')) { /* there is User-Agent header */ }

The `request` component also provides support for quickly accessing some commonly used headers, including:

- userAgent: returns the value of the `User-Agent` header.
- contentType: returns the value of the `Content-Type` header which indicates the MIME type of the data in the request body.
- acceptableContentTypes: returns the content MIME types acceptable by users. The returned types are ordered by their quality score. Types with the highest scores will be returned first.
- acceptableLanguages: returns the languages acceptable by users. The returned languages are ordered by their preference level. The first element represents the most preferred language.

If your application supports multiple languages and you want to display pages in the language that is the most preferred by the end user, you may use the language negotiation method yii\web\Request::getPreferredLanguage(). This method takes a list of languages supported by your application, compares them with acceptableLanguages, and returns the most appropriate language.

> Tip: You may also use the ContentNegotiator filter to dynamically determine what content type and language should be used in the response. The filter implements the content negotiation on top of the properties and methods described above.

## Client Information ¶

You can get the host name and IP address of the client machine through userHost and userIP, respectively. For example,

    $userHost = Yii::$app->request->userHost;
    $userIP = Yii::$app->request->userIP;

## Trusted proxies and headers ¶

In the previous section you have seen how to get user information like host and IP address. This will work out of the box in a normal setup where a single webserver is used to serve the website. If your Yii application however runs behind a reverse proxy, you need to add additional configuration to retrieve this information as the direct client is now the proxy and the user IP address is passed to the Yii application by a header set by the proxy.

You should not blindly trust headers provided by proxies unless you explicitly trust the proxy. Since 2.0.13 Yii supports configuring trusted proxies via the trustedHosts, secureHeaders, ipHeaders and secureProtocolHeaders properties of the `request` component.

The following is a request config for an application that runs behind an array of reverse proxies, which are located in the `10.0.2.0/24` IP network:

    'request' => [
        // ...
        'trustedHosts' => [
            '10.0.2.0/24',
        ],
    ],

The IP is sent by the proxy in the `X-Forwarded-For` header by default, and the protocol (`http` or `https`) is sent in `X-Forwarded-Proto`.

In case your proxies are using different headers you can use the request configuration to adjust these, e.g.:

    'request' => [
        // ...
        'trustedHosts' => [
            '10.0.2.0/24' => [
                'X-ProxyUser-Ip',
                'Front-End-Https',
            ],
        ],
        'secureHeaders' => [
            'X-Forwarded-For',
            'X-Forwarded-Host',
            'X-Forwarded-Proto',
            'X-Proxy-User-Ip',
            'Front-End-Https',
        ],
        'ipHeaders' => [
            'X-Proxy-User-Ip',
        ],
        'secureProtocolHeaders' => [
            'Front-End-Https' => ['on']
        ],
    ],

With the above configuration, all headers listed in `secureHeaders` are filtered from the request, except the `X-ProxyUser-Ip` and `Front-End-Https` headers in case the request is made by the proxy. In that case the former is used to retrieve the user IP as configured in `ipHeaders` and the latter will be used to determine the result of yii\web\Request::getIsSecureConnection().

Since 2.0.31 RFC 7239 `Forwarded` header is supported. In order to enable it you need to add header name to `secureHeaders`. Make sure your proxy is setting it, otherwise end user would be able to spoof IP and protocol.

### Already resolved user IP ¶

If the user's IP address is resolved before the Yii application (e.g. `ngx_http_realip_module` or similar), the `request` component will work correctly with the following configuration:

    'request' => [
        // ...
        'trustedHosts' => [
            '0.0.0.0/0',
        ],
        'ipHeaders' => [],
    ],

In this case, the value of userIP will be equal to `$_SERVER['REMOTE_ADDR']`. Also, properties that are resolved from HTTP headers will work correctly (e.g. yii\web\Request::getIsSecureConnection()).

> Warning: The `trustedHosts=['0.0.0.0/0']` setting assumes that all IPs are trusted.