Skip to content

Latest commit

 

History

History
139 lines (99 loc) · 6.58 KB

runtime-requests.md

File metadata and controls

139 lines (99 loc) · 6.58 KB
Raw

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 [[yii\web\Request::get()|get()]] and [[yii\web\Request::post()|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 are 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:

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

HTTP Headers

You can get the HTTP header information through the [[yii\web\HeaderCollection|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:

  • [[yii\web\Request::userAgent|userAgent]]: returns the value of the User-Agent header.
  • [[yii\web\Request::contentType|contentType]]: returns the value of the Content-Type header which indicates the MIME type of the data in the request body.
  • [[yii\web\Request::acceptableContentTypes|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.
  • [[yii\web\Request::acceptableLanguages|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 [[yii\web\Request::acceptableLanguages|acceptableLanguages]], and returns the most appropriate language.

Tip: You may also use the [[yii\filters\ContentNegotiator|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 [[yii\web\Request::userHost|userHost]] and [[yii\web\Request::userIP|userIP]], respectively. For example,

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