From e3117ce1de36d48976708879cab053dfc71889d1 Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Fri, 21 Nov 2014 08:06:49 +0900 Subject: [PATCH 1/5] docs/guide-ja/runtime-responses.md - prepared for translation [ci skip] --- docs/guide-ja/runtime-responses.md | 260 +++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 docs/guide-ja/runtime-responses.md diff --git a/docs/guide-ja/runtime-responses.md b/docs/guide-ja/runtime-responses.md new file mode 100644 index 0000000000..ab0b2727a4 --- /dev/null +++ b/docs/guide-ja/runtime-responses.md @@ -0,0 +1,260 @@ +Responses +========= + +When an application finishes handling a [request](runtime-requests.md), it generates a [[yii\web\Response|response]] object +and sends it to the end user. The response object contains information such as the HTTP status code, HTTP headers and body. +The ultimate goal of Web application development is essentially to build such response objects upon various requests. + +In most cases you should mainly deal with the `response` [application component](structure-application-components.md) +which is an instance of [[yii\web\Response]], by default. However, Yii also allows you to create your own response +objects and send them to end users as we will explain in the following. + +In this section, we will describe how to compose and send responses to end users. + + +## Status Code + +One of the first things you would do when building a response is to state whether the request is successfully handled. +This is done by setting the [[yii\web\Response::statusCode]] property which can take one of the valid +[HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). For example, to indicate the request +is successfully handled, you may set the status code to be 200, like the following: + +```php +Yii::$app->response->statusCode = 200; +``` + +However, in most cases you do not need to explicitly set the status code. This is because the default value +of [[yii\web\Response::statusCode]] is 200. And if you want to indicate the request is unsuccessful, you may +throw an appropriate HTTP exception like the following: + +```php +throw new \yii\web\NotFoundHttpException; +``` + +When the [error handler](runtime-handling-errors.md) catches an exception, it will extract the status code +from the exception and assign it to the response. For the [[yii\web\NotFoundHttpException]] above, it is +associated with the HTTP status 404. The following HTTP exceptions are predefined in Yii: + +* [[yii\web\BadRequestHttpException]]: status code 400. +* [[yii\web\ConflictHttpException]]: status code 409. +* [[yii\web\ForbiddenHttpException]]: status code 403. +* [[yii\web\GoneHttpException]]: status code 410. +* [[yii\web\MethodNotAllowedHttpException]]: status code 405. +* [[yii\web\NotAcceptableHttpException]]: status code 406. +* [[yii\web\NotFoundHttpException]]: status code 404. +* [[yii\web\ServerErrorHttpException]]: status code 500. +* [[yii\web\TooManyRequestsHttpException]]: status code 429. +* [[yii\web\UnauthorizedHttpException]]: status code 401. +* [[yii\web\UnsupportedMediaTypeHttpException]]: status code 415. + +If the exception that you want to throw is not among the above list, you may create one by extending +from [[yii\web\HttpException]], or directly throw it with a status code, for example, + +```php +throw new \yii\web\HttpException(402); +``` + + +## HTTP Headers + +You can send HTTP headers by manipulating the [[yii\web\Response::headers|header collection]] in the `response` component. +For example, + +```php +$headers = Yii::$app->response->headers; + +// add a Pragma header. Existing Pragma headers will NOT be overwritten. +$headers->add('Pragma', 'no-cache'); + +// set a Pragma header. Any existing Pragma headers will be discarded. +$headers->set('Pragma', 'no-cache'); + +// remove Pragma header(s) and return the removed Pragma header values in an array +$values = $headers->remove('Pragma'); +``` + +> Info: Header names are case insensitive. And the newly registered headers are not sent to the user until + the [[yii\web\Response::send()]] method is called. + + +## Response Body + +Most responses should have a body which gives the content that you want to show to end users. + +If you already have a formatted body string, you may assign it to the [[yii\web\Response::content]] property +of the response. For example, + +```php +Yii::$app->response->content = 'hello world!'; +``` + +If your data needs to be formatted before sending it to end users, you should set both of the +[[yii\web\Response::format|format]] and [[yii\web\Response::data|data]] properties. The [[yii\web\Response::format|format]] +property specifies in which format the [[yii\web\Response::data|data]] should be formatted. For example, + +```php +$response = Yii::$app->response; +$response->format = \yii\web\Response::FORMAT_JSON; +$response->data = ['message' => 'hello world']; +``` + +Yii supports the following formats out of the box, each implemented by a [[yii\web\ResponseFormatterInterface|formatter]] class. +You can customize these formatters or add new ones by configuring the [[yii\web\Response::formatters]] property. + +* [[yii\web\Response::FORMAT_HTML|HTML]]: implemented by [[yii\web\HtmlResponseFormatter]]. +* [[yii\web\Response::FORMAT_XML|XML]]: implemented by [[yii\web\XmlResponseFormatter]]. +* [[yii\web\Response::FORMAT_JSON|JSON]]: implemented by [[yii\web\JsonResponseFormatter]]. +* [[yii\web\Response::FORMAT_JSONP|JSONP]]: implemented by [[yii\web\JsonResponseFormatter]]. +* [[yii\web\Response::FORMAT_RAW|RAW]]: use this format if you want to send the response directly without applying any formatting. + +While the response body can be set explicitly as shown above, in most cases you may set it implicitly by the return value +of [action](structure-controllers.md) methods. A common use case is like the following: + +```php +public function actionIndex() +{ + return $this->render('index'); +} +``` + +The `index` action above returns the rendering result of the `index` view. The return value will be taken +by the `response` component, formatted and then sent to end users. + +Because by default the response format is [[yii\web\Response::FORMAT_HTML|HTML]], you should only return a string +in an action method. If you want to use a different response format, you should set it first before returning the data. +For example, + +```php +public function actionInfo() +{ + \Yii::$app->response->format = \yii\web\Response::FORMAT_JSON; + return [ + 'message' => 'hello world', + 'code' => 100, + ]; +} +``` + +As aforementioned, besides using the default `response` application component, you can also create your own +response objects and send them to end users. You can do so by returning such object in an action method, like the following, + +```php +public function actionInfo() +{ + return \Yii::createObject([ + 'class' => 'yii\web\Response', + 'format' => \yii\web\Response::FORMAT_JSON, + 'data' => [ + 'message' => 'hello world', + 'code' => 100, + ], + ]); +} +``` + +> Note: If you are creating your own response objects, you will not be able to take advantage of the configurations + that you set for the `response` component in the application configuration. You can, however, use + [dependency injection](concept-di-container.md) to apply a common configuration to your new response objects. + + +## Browser Redirection + +Browser redirection relies on sending a `Location` HTTP header. Because this feature is commonly used, Yii provides +some special support for it. + +You can redirect the user browser to a URL by calling the [[yii\web\Response::redirect()]] method. The method +sets the appropriate `Location` header with the given URL and returns the response object itself. In an action method, +you can call its shortcut version [[yii\web\Controller::redirect()]]. For example, + +```php +public function actionOld() +{ + return $this->redirect('http://example.com/new', 301); +} +``` + +In the above code, the action method returns the result of the `redirect()` method. As explained before, the response +object returned by an action method will be used as the response sending to end users. + +In places other than an action method, you should call [[yii\web\Response::redirect()]] directly followed by +a chained call to the [[yii\web\Response::send()]] method to ensure no extra content will be appended to the response. + +```php +\Yii::$app->response->redirect('http://example.com/new', 301)->send(); +``` + +> Info: By default, the [[yii\web\Response::redirect()]] method sets the response status code to be 302 which instructs + the browser that the resource being requested is *temporarily* located in a different URI. You can pass in a status + code 301 to tell the browser that the resource has been *permanently* relocated. + +When the current request is an AJAX request, sending a `Location` header will not automatically cause the browser +to redirect. To solve this problem, the [[yii\web\Response::redirect()]] method sets an `X-Redirect` header with +the redirection URL as its value. On the client side, you may write JavaScript code to read this header value and +redirect the browser accordingly. + +> Info: Yii comes with a `yii.js` JavaScript file which provides a set of commonly used JavaScript utilities, + including browser redirection based on the `X-Redirect` header. Therefore, if you are using this JavaScript file + (by registering the [[yii\web\YiiAsset]] asset bundle), you do not need to write anything to support AJAX redirection. + + +## Sending Files + +Like browser redirection, file sending is another feature that relies on specific HTTP headers. Yii provides +a set of methods to support various file sending needs. They all have built-in support for the HTTP range header. + +* [[yii\web\Response::sendFile()]]: sends an existing file to a client. +* [[yii\web\Response::sendContentAsFile()]]: sends a text string as a file to a client. +* [[yii\web\Response::sendStreamAsFile()]]: sends an existing file stream as a file to a client. + +These methods have the same method signature with the response object as the return value. If the file +to be sent is very big, you should consider using [[yii\web\Response::sendStreamAsFile()]] because it is more +memory efficient. The following example shows how to send a file in a controller action: + +```php +public function actionDownload() +{ + return \Yii::$app->response->sendFile('path/to/file.txt'); +} +``` + +If you are calling the file sending method in places other than an action method, you should also call +the [[yii\web\Response::send()]] method afterwards to ensure no extra content will be appended to the response. + +```php +\Yii::$app->response->sendFile('path/to/file.txt')->send(); +``` + +Some Web servers have a special file sending support called *X-Sendfile*. The idea is to redirect the +request for a file to the Web server which will directly serve the file. As a result, the Web application +can terminate earlier while the Web server is sending the file. To use this feature, you may call +the [[yii\web\Response::xSendFile()]]. The following list summarizes how to enable the `X-Sendfile` feature +for some popular Web servers: + +- Apache: [X-Sendfile](http://tn123.org/mod_xsendfile) +- Lighttpd v1.4: [X-LIGHTTPD-send-file](http://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file) +- Lighttpd v1.5: [X-Sendfile](http://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file) +- Nginx: [X-Accel-Redirect](http://wiki.nginx.org/XSendfile) +- Cherokee: [X-Sendfile and X-Accel-Redirect](http://www.cherokee-project.com/doc/other_goodies.html#x-sendfile) + + +## Sending Response + +The content in a response is not sent to the user until the [[yii\web\Response::send()]] method is called. +By default, this method will be called automatically at the end of [[yii\base\Application::run()]]. You can, however, +explicitly call this method to force sending out the response immediately. + +The [[yii\web\Response::send()]] method takes the following steps to send out a response: + +1. Trigger the [[yii\web\Response::EVENT_BEFORE_SEND]] event. +2. Call [[yii\web\Response::prepare()]] to format [[yii\web\Response::data|response data]] into + [[yii\web\Response::content|response content]]. +3. Trigger the [[yii\web\Response::EVENT_AFTER_PREPARE]] event. +4. Call [[yii\web\Response::sendHeaders()]] to send out the registered HTTP headers. +5. Call [[yii\web\Response::sendContent()]] to send out the response body content. +6. Trigger the [[yii\web\Response::EVENT_AFTER_SEND]] event. + +After the [[yii\web\Response::send()]] method is called once, any further call to this method will be ignored. +This means once the response is sent out, you will not be able to append more content to it. + +As you can see, the [[yii\web\Response::send()]] method triggers several useful events. By responding to +these events, it is possible to adjust or decorate the response. From 9f09bb76d4b2298e9ec0ea09adb8b01be9aca194 Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Fri, 21 Nov 2014 08:51:44 +0900 Subject: [PATCH 2/5] docs/guide-ja/runtime-responses.md - WIP [ci skip] --- docs/guide-ja/runtime-responses.md | 67 +++++++++++++++--------------- 1 file changed, 33 insertions(+), 34 deletions(-) diff --git a/docs/guide-ja/runtime-responses.md b/docs/guide-ja/runtime-responses.md index ab0b2727a4..aa51b66f31 100644 --- a/docs/guide-ja/runtime-responses.md +++ b/docs/guide-ja/runtime-responses.md @@ -1,61 +1,60 @@ -Responses -========= +レスポンス +========== -When an application finishes handling a [request](runtime-requests.md), it generates a [[yii\web\Response|response]] object -and sends it to the end user. The response object contains information such as the HTTP status code, HTTP headers and body. -The ultimate goal of Web application development is essentially to build such response objects upon various requests. +アプリケーションは [リクエスト](runtime-requests.md) の処理を完了すると、[[yii\web\Response|レスポンス]] オブジェクトを生成して、 +エンドユーザに送信します。レスポンスオブジェクトは、HTTP ステータスコード、HTTP ヘッダ、HTTP ボディなどの情報を含みます。 +ウェブアプリケーション開発の最終的な目的は、本質的には、さまざまなリクエストに対してそのようなレスポンスオブジェクトを +作成することにあります。 -In most cases you should mainly deal with the `response` [application component](structure-application-components.md) -which is an instance of [[yii\web\Response]], by default. However, Yii also allows you to create your own response -objects and send them to end users as we will explain in the following. +ほとんどの場合は、主として `response` [アプリケーションコンポーネント](structure-application-components.md) を使用すべきです。 +このコンポーネントは、既定では、[[yii\web\Response]] のインスタンスです。しかしながら、Yii は、以下で説明するように、 +あなた自身のレスポンスオブジェクトを作成してエンドユーザに送信することも許容しています。 -In this section, we will describe how to compose and send responses to end users. +この節では、レスポンスを構成してエンドユーザに送信する方法を説明します。 -## Status Code +## ステータスコード -One of the first things you would do when building a response is to state whether the request is successfully handled. -This is done by setting the [[yii\web\Response::statusCode]] property which can take one of the valid -[HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). For example, to indicate the request -is successfully handled, you may set the status code to be 200, like the following: +レスポンスを作成するときに最初にすることの一つは、リクエストが成功裏に処理されたかどうかを記述することです。そのためには、 +[[yii\web\Response::statusCode]] プロパティに有効な [HTTP ステータスコード](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) +の一つを設定します。例えば、下記のように、リクエストの処理が成功したことを示すために、ステータスコードを 200 に設定します。 ```php Yii::$app->response->statusCode = 200; ``` -However, in most cases you do not need to explicitly set the status code. This is because the default value -of [[yii\web\Response::statusCode]] is 200. And if you want to indicate the request is unsuccessful, you may -throw an appropriate HTTP exception like the following: +しかしながら、たいていの場合、ステータスコードを明示的に設定する必要はありません。これは、[[yii\web\Response::statusCode]] +の既定値が 200 であるからです。そして、リクエストが失敗したことを示したいときは、下記のように、適切な HTTP 例外を投げることが出来ます。 ```php throw new \yii\web\NotFoundHttpException; ``` -When the [error handler](runtime-handling-errors.md) catches an exception, it will extract the status code -from the exception and assign it to the response. For the [[yii\web\NotFoundHttpException]] above, it is -associated with the HTTP status 404. The following HTTP exceptions are predefined in Yii: +[エラーハンドラ](runtime-handling-errors.md) は、例外をキャッチすると、例外からステータスコードを抽出してレスポンスに割り当てます。 +上記の [[yii\web\NotFoundHttpException]] の場合は、HTTP ステータス 404 と関連付けられています。 +次の HTTP 例外が Yii によって事前定義されています。 -* [[yii\web\BadRequestHttpException]]: status code 400. -* [[yii\web\ConflictHttpException]]: status code 409. -* [[yii\web\ForbiddenHttpException]]: status code 403. -* [[yii\web\GoneHttpException]]: status code 410. -* [[yii\web\MethodNotAllowedHttpException]]: status code 405. -* [[yii\web\NotAcceptableHttpException]]: status code 406. -* [[yii\web\NotFoundHttpException]]: status code 404. -* [[yii\web\ServerErrorHttpException]]: status code 500. -* [[yii\web\TooManyRequestsHttpException]]: status code 429. -* [[yii\web\UnauthorizedHttpException]]: status code 401. -* [[yii\web\UnsupportedMediaTypeHttpException]]: status code 415. +* [[yii\web\BadRequestHttpException]]: ステータスコード 400 +* [[yii\web\ConflictHttpException]]: ステータスコード 409 +* [[yii\web\ForbiddenHttpException]]: ステータスコード 403 +* [[yii\web\GoneHttpException]]: ステータスコード 410 +* [[yii\web\MethodNotAllowedHttpException]]: ステータスコード 405 +* [[yii\web\NotAcceptableHttpException]]: ステータスコード 406 +* [[yii\web\NotFoundHttpException]]: ステータスコード 404 +* [[yii\web\ServerErrorHttpException]]: ステータスコード 500 +* [[yii\web\TooManyRequestsHttpException]]: ステータスコード 429 +* [[yii\web\UnauthorizedHttpException]]: ステータスコード 401 +* [[yii\web\UnsupportedMediaTypeHttpException]]: ステータスコード 415 -If the exception that you want to throw is not among the above list, you may create one by extending -from [[yii\web\HttpException]], or directly throw it with a status code, for example, +投げたい例外が上記のリストに無い場合は、[[yii\web\HttpException]] から拡張したものを作成することが出来ます。 +あるいは、ステータスコードを指定して [[yii\web\HttpException]] を直接に投げることも出来ます。例えば、 ```php throw new \yii\web\HttpException(402); ``` -## HTTP Headers +## HTTP ヘッダ You can send HTTP headers by manipulating the [[yii\web\Response::headers|header collection]] in the `response` component. For example, From b95798d081f473484ebde01255c4df7d2d34784c Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Fri, 21 Nov 2014 10:00:49 +0900 Subject: [PATCH 3/5] docs/guide-ja/runtime-responses.md - WIP [ci skip] --- docs/guide-ja/runtime-responses.md | 70 +++++++++++++++--------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/docs/guide-ja/runtime-responses.md b/docs/guide-ja/runtime-responses.md index aa51b66f31..878097e2fc 100644 --- a/docs/guide-ja/runtime-responses.md +++ b/docs/guide-ja/runtime-responses.md @@ -56,40 +56,41 @@ throw new \yii\web\HttpException(402); ## HTTP ヘッダ -You can send HTTP headers by manipulating the [[yii\web\Response::headers|header collection]] in the `response` component. -For example, +`response` コンポーネントの [[yii\web\Response::headers|ヘッダコレクション]] を操作することによって、 +HTTP ヘッダを送信することが出来ます。例えば、 ```php $headers = Yii::$app->response->headers; -// add a Pragma header. Existing Pragma headers will NOT be overwritten. +// Pragma ヘッダを追加する。既存の Pragma ヘッダは上書きされない。 $headers->add('Pragma', 'no-cache'); -// set a Pragma header. Any existing Pragma headers will be discarded. +// Pragma ヘッダを設定する。既存の Pragma ヘッダは全て破棄される。 $headers->set('Pragma', 'no-cache'); -// remove Pragma header(s) and return the removed Pragma header values in an array +// Pragma ヘッダを削除して、削除された Pragma ヘッダの値を配列に返す。 $values = $headers->remove('Pragma'); ``` -> Info: Header names are case insensitive. And the newly registered headers are not sent to the user until - the [[yii\web\Response::send()]] method is called. +> Info|情報: ヘッダ名は大文字小文字を区別しません。そして、新しく登録されたヘッダは、 + [[yii\web\Response::send()]] メソッドが呼ばれるまで送信されません。 -## Response Body +## レスポンスボディ -Most responses should have a body which gives the content that you want to show to end users. +ほとんどのレスポンスは、エンドユーザに対して表示したい内容を示すボディを持っていなければなりません。 -If you already have a formatted body string, you may assign it to the [[yii\web\Response::content]] property -of the response. For example, +既にフォーマットされたボディの文字列を持っている場合は、それをレスポンスの [[yii\web\Response::content]] +プロパティに割り付けることが出来ます。例えば、 ```php Yii::$app->response->content = 'hello world!'; ``` -If your data needs to be formatted before sending it to end users, you should set both of the -[[yii\web\Response::format|format]] and [[yii\web\Response::data|data]] properties. The [[yii\web\Response::format|format]] -property specifies in which format the [[yii\web\Response::data|data]] should be formatted. For example, +データをエンドユーザに送信する前にフォーマットする必要がある場合は、[[yii\web\Response::format|format]] と [[yii\web\Response::data|data]] +の両方のプロパティをセットしなければなりません。[[yii\web\Response::format|format]] +プロパティは [[yii\web\Response::data|data]] がどの形式でフォーマットされるべきかを指定するものです。 +例えば、 ```php $response = Yii::$app->response; @@ -97,18 +98,19 @@ $response->format = \yii\web\Response::FORMAT_JSON; $response->data = ['message' => 'hello world']; ``` -Yii supports the following formats out of the box, each implemented by a [[yii\web\ResponseFormatterInterface|formatter]] class. -You can customize these formatters or add new ones by configuring the [[yii\web\Response::formatters]] property. +Yii は下記の形式を初めからサポートしています。それぞれ、[[yii\web\ResponseFormatterInterface|フォーマッタ]] クラスとして実装されています。 +[[yii\web\Response::formatters]] プロパティを構成することで、これらのフォーマッタをカスタマイズしたり、 +または、新しいフォーマッタを追加することが出来ます。 -* [[yii\web\Response::FORMAT_HTML|HTML]]: implemented by [[yii\web\HtmlResponseFormatter]]. -* [[yii\web\Response::FORMAT_XML|XML]]: implemented by [[yii\web\XmlResponseFormatter]]. -* [[yii\web\Response::FORMAT_JSON|JSON]]: implemented by [[yii\web\JsonResponseFormatter]]. -* [[yii\web\Response::FORMAT_JSONP|JSONP]]: implemented by [[yii\web\JsonResponseFormatter]]. -* [[yii\web\Response::FORMAT_RAW|RAW]]: use this format if you want to send the response directly without applying any formatting. +* [[yii\web\Response::FORMAT_HTML|HTML]]: [[yii\web\HtmlResponseFormatter]] によって実装 +* [[yii\web\Response::FORMAT_XML|XML]]: [[yii\web\XmlResponseFormatter]] によって実装 +* [[yii\web\Response::FORMAT_JSON|JSON]]: [[yii\web\JsonResponseFormatter]] によって実装 +* [[yii\web\Response::FORMAT_JSONP|JSONP]]: [[yii\web\JsonResponseFormatter]] によって実装 +* [[yii\web\Response::FORMAT_RAW|RAW]]: 書式を何も適用せずにレスポンスを送信したいときは、このフォーマットを使用 + +レスポンスボディは、上記のように、明示的に設定することも出来ますが、たいていの場合は、[アクション](structure-controllers.md) +メソッドの返り値によって暗黙のうちに設定することが出来ます。よくあるユースケースは下記のようなものになります。 -While the response body can be set explicitly as shown above, in most cases you may set it implicitly by the return value -of [action](structure-controllers.md) methods. A common use case is like the following: - ```php public function actionIndex() { @@ -116,12 +118,11 @@ public function actionIndex() } ``` -The `index` action above returns the rendering result of the `index` view. The return value will be taken -by the `response` component, formatted and then sent to end users. +上記の `index` アクションは、`index` ビューのレンダリング結果を返しています。返された値は `response` +コンポーネントによって受け取られ、フォーマットされてエンドユーザに送信されます。 -Because by default the response format is [[yii\web\Response::FORMAT_HTML|HTML]], you should only return a string -in an action method. If you want to use a different response format, you should set it first before returning the data. -For example, +デフォルトのレスポンス形式が [[yii\web\Response::FORMAT_HTML|HTML]] であるため、アクションメソッドの中では文字列を返すだけにすべきです。 +別のレスポンス形式を使いたい場合は、データを返す前にレスポンス形式を設定しなければなりません。例えば、 ```php public function actionInfo() @@ -134,8 +135,9 @@ public function actionInfo() } ``` -As aforementioned, besides using the default `response` application component, you can also create your own -response objects and send them to end users. You can do so by returning such object in an action method, like the following, +既に述べたように、デフォルトの `response` アプリケーションコンポーネントを使う代りに、 +自分自身のレスポンスオブジェクトを作成してエンドユーザに送信することも出来ます。そうするためには、次のように、 +アクションメソッドの中でそのようなオブジェクトを返します。 ```php public function actionInfo() @@ -151,9 +153,9 @@ public function actionInfo() } ``` -> Note: If you are creating your own response objects, you will not be able to take advantage of the configurations - that you set for the `response` component in the application configuration. You can, however, use - [dependency injection](concept-di-container.md) to apply a common configuration to your new response objects. +> Note|注意: 自分自身のレスポンスオブジェクトを作成しようとする場合は、アプリケーションのコンフィギュレーションで `response` + コンポーネントのために設定したコンフィギュレーションを利用することは出来ません。しかしながら、 [依存の注入](concept-di-container.md) を使って、 + 共通のコンフィギュレーションをあなたの新しいレスポンスオブジェクトに適用することは出来ます。 ## Browser Redirection From 771235bc9d44671017b3bcaa6da9e1e1c9d4210b Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Fri, 21 Nov 2014 12:07:19 +0900 Subject: [PATCH 4/5] docs/guide-ja/runtime-responses.md - WIP [ci skip] --- docs/guide-ja/runtime-responses.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/guide-ja/runtime-responses.md b/docs/guide-ja/runtime-responses.md index 878097e2fc..5375a6e255 100644 --- a/docs/guide-ja/runtime-responses.md +++ b/docs/guide-ja/runtime-responses.md @@ -15,7 +15,7 @@ ## ステータスコード -レスポンスを作成するときに最初にすることの一つは、リクエストが成功裏に処理されたかどうかを記述することです。そのためには、 +レスポンスを作成するときに最初にすることの一つは、リクエストが成功裡に処理されたかどうかを記述することです。そのためには、 [[yii\web\Response::statusCode]] プロパティに有効な [HTTP ステータスコード](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) の一つを設定します。例えば、下記のように、リクエストの処理が成功したことを示すために、ステータスコードを 200 に設定します。 @@ -23,7 +23,7 @@ Yii::$app->response->statusCode = 200; ``` -しかしながら、たいていの場合、ステータスコードを明示的に設定する必要はありません。これは、[[yii\web\Response::statusCode]] +けれども、たいていの場合、ステータスコードを明示的に設定する必要はありません。これは、[[yii\web\Response::statusCode]] の既定値が 200 であるからです。そして、リクエストが失敗したことを示したいときは、下記のように、適切な HTTP 例外を投げることが出来ます。 ```php @@ -154,18 +154,18 @@ public function actionInfo() ``` > Note|注意: 自分自身のレスポンスオブジェクトを作成しようとする場合は、アプリケーションのコンフィギュレーションで `response` - コンポーネントのために設定したコンフィギュレーションを利用することは出来ません。しかしながら、 [依存の注入](concept-di-container.md) を使って、 - 共通のコンフィギュレーションをあなたの新しいレスポンスオブジェクトに適用することは出来ます。 + コンポーネントのために設定したコンフィギュレーションを利用することは出来ません。しかし、 [依存の注入](concept-di-container.md) を使えば、 + 共通のコンフィギュレーションをあなたの新しいレスポンスオブジェクトに適用することが出来ます。 -## Browser Redirection +## ブラウザのリダイレクト -Browser redirection relies on sending a `Location` HTTP header. Because this feature is commonly used, Yii provides -some special support for it. +ブラウザのリダイレクトは `Location` HTTP ヘッダの送信に依存しています。この機能は通常よく使われるものであるため、 +Yii はこれについて特別のサポートを提供しています。 -You can redirect the user browser to a URL by calling the [[yii\web\Response::redirect()]] method. The method -sets the appropriate `Location` header with the given URL and returns the response object itself. In an action method, -you can call its shortcut version [[yii\web\Controller::redirect()]]. For example, +[[yii\web\Response::redirect()]] メソッドを呼ぶことによって、ユーザのブラウザをある URL にリダイレクトすることが出来ます。 +このメソッドは与えられた URL を持つ適切な `Location` ヘッダを設定して、レスポンスオブジェクトそのものを返します。 +アクションメソッドの中では、そのショートカット版である [[yii\web\Controller::redirect()]] を呼ぶことが出来ます。例えば、 ```php public function actionOld() @@ -174,11 +174,11 @@ public function actionOld() } ``` -In the above code, the action method returns the result of the `redirect()` method. As explained before, the response -object returned by an action method will be used as the response sending to end users. +上記のコードでは、アクションメソッドが `redirect()` メソッドの結果を返しています。前に説明したように、 +アクションメソッドによって返されるレスポンスオブジェクトは、エンドユーザに送信されるレスポンスとして使用されることになります。 -In places other than an action method, you should call [[yii\web\Response::redirect()]] directly followed by -a chained call to the [[yii\web\Response::send()]] method to ensure no extra content will be appended to the response. +アクションメソッド以外の場所では、[[yii\web\Response::redirect()]] を直接に呼び出し、メソッドチェーンで +[[yii\web\Response::send()]] メソッドを呼んで、レスポンスに余計なコンテンツが追加されないことを保証すべきです。 ```php \Yii::$app->response->redirect('http://example.com/new', 301)->send(); From 079eb3334b952067fac82666fc3af5f6f2590143 Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Sat, 22 Nov 2014 07:53:13 +0900 Subject: [PATCH 5/5] docs/guide-ja/runtime-responses.md - completed --- docs/guide-ja/runtime-responses.md | 85 +++++++++++++++--------------- 1 file changed, 43 insertions(+), 42 deletions(-) diff --git a/docs/guide-ja/runtime-responses.md b/docs/guide-ja/runtime-responses.md index 5375a6e255..0be3639f29 100644 --- a/docs/guide-ja/runtime-responses.md +++ b/docs/guide-ja/runtime-responses.md @@ -184,32 +184,33 @@ public function actionOld() \Yii::$app->response->redirect('http://example.com/new', 301)->send(); ``` -> Info: By default, the [[yii\web\Response::redirect()]] method sets the response status code to be 302 which instructs - the browser that the resource being requested is *temporarily* located in a different URI. You can pass in a status - code 301 to tell the browser that the resource has been *permanently* relocated. +> Info|情報: 既定では、[[yii\web\Response::redirect()]] メソッドはレスポンスのステータスコードを 302 にセットします。 +これはブラウザに対して、リクエストされているリソースが *一時的に* 異なる URI に配置されていることを示すものです。 +ブラウザに対してリソースが *恒久的に* 配置替えされたことを教えるためには、ステータスコード 301 を渡すことが出来ます。 -When the current request is an AJAX request, sending a `Location` header will not automatically cause the browser -to redirect. To solve this problem, the [[yii\web\Response::redirect()]] method sets an `X-Redirect` header with -the redirection URL as its value. On the client side, you may write JavaScript code to read this header value and -redirect the browser accordingly. +現在のリクエストが AJAX リクエストである場合は、`Location` ヘッダを送っても自動的にブラウザをリダイレクトすることにはなりません。 +この問題を解決するために、[[yii\web\Response::redirect()]] メソッドは `X-Redirect` ヘッダにリダイレクト先 URL を値としてセットします。 +そして、クライアントサイドで、このヘッダの値を読み、それに応じてブラウザをリダイレクトする JavaScript を書くことが出来ます。 -> Info: Yii comes with a `yii.js` JavaScript file which provides a set of commonly used JavaScript utilities, - including browser redirection based on the `X-Redirect` header. Therefore, if you are using this JavaScript file - (by registering the [[yii\web\YiiAsset]] asset bundle), you do not need to write anything to support AJAX redirection. +> Info|情報: Yii には `yii.js` という JavaScript ファイルが付いています。これは、よく使われる一連の JavaScript 機能を提供するもので、 +その中には `X-Redirect` ヘッダに基づくブラウザのリダイレクトも含まれています。従って、あなたが +([[yii\web\YiiAsset]] アセットバンドルを登録して) この JavaScript ファイルを使うつもりなら、 +AJAX のリダイレクトをサポートするためには、何も書く必要がなくなります。 -## Sending Files +## ファイルを送信する -Like browser redirection, file sending is another feature that relies on specific HTTP headers. Yii provides -a set of methods to support various file sending needs. They all have built-in support for the HTTP range header. +ブラウザのリダイレクトと同じように、ファイルの送信という機能も特定の HTTP ヘッダに依存しています。 +Yii はさまざまなファイル送信の必要をサポートするための一連のメソッドを提供しています。それらはすべて、 +HTTP range ヘッダに対するサポートを内蔵しています。 -* [[yii\web\Response::sendFile()]]: sends an existing file to a client. -* [[yii\web\Response::sendContentAsFile()]]: sends a text string as a file to a client. -* [[yii\web\Response::sendStreamAsFile()]]: sends an existing file stream as a file to a client. +* [[yii\web\Response::sendFile()]]: 既存のファイルをクライアントに送信する +* [[yii\web\Response::sendContentAsFile()]]: テキストの文字列をファイルとしてクライアントに送信する +* [[yii\web\Response::sendStreamAsFile()]]: 既存のファイルストリームをファイルとしてクライアントに送信する -These methods have the same method signature with the response object as the return value. If the file -to be sent is very big, you should consider using [[yii\web\Response::sendStreamAsFile()]] because it is more -memory efficient. The following example shows how to send a file in a controller action: +これらのメソッドは同じメソッドシグニチャを持ち、返り値としてレスポンスオブジェクトを返します。 +送信しようとしているファイルが非常に大きなものである場合は、メモリ効率の良い [[yii\web\Response::sendStreamAsFile()]] の使用を検討すべきです。 +次の例は、コントローラアクションでファイルを送信する方法を示すものです。 ```php public function actionDownload() @@ -218,18 +219,18 @@ public function actionDownload() } ``` -If you are calling the file sending method in places other than an action method, you should also call -the [[yii\web\Response::send()]] method afterwards to ensure no extra content will be appended to the response. +ファイル送信メソッドをアクションメソッド以外の場所で呼ぶ場合は、その後で [[yii\web\Response::send()]] メソッドも呼んで、 +レスポンスに余計なコンテンツが追加されないことを保証すべきです。 ```php \Yii::$app->response->sendFile('path/to/file.txt')->send(); ``` -Some Web servers have a special file sending support called *X-Sendfile*. The idea is to redirect the -request for a file to the Web server which will directly serve the file. As a result, the Web application -can terminate earlier while the Web server is sending the file. To use this feature, you may call -the [[yii\web\Response::xSendFile()]]. The following list summarizes how to enable the `X-Sendfile` feature -for some popular Web servers: +ウェブサーバには、*X-Sendfile* と呼ばれる特別なファイル送信をサポートするものがあります。アイデアとしては、 +ファイルに対するリクエストをウェブサーバにリダイレクトして、ウェブサーバに直接にファイルを送信させる、というものです。 +その結果として、ウェブサーバがファイルを送信している間でも、ウェブアプリケーションは早期に終了することが出来るようになります。 +この機能を使うために、[[yii\web\Response::xSendFile()]] を呼ぶことが出来ます。次のリストは、 +よく使われるいくつかのウェブサーバにおいて `X-Sendfile` 機能を有効にする方法を要約するものです。 - Apache: [X-Sendfile](http://tn123.org/mod_xsendfile) - Lighttpd v1.4: [X-LIGHTTPD-send-file](http://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file) @@ -238,24 +239,24 @@ for some popular Web servers: - Cherokee: [X-Sendfile and X-Accel-Redirect](http://www.cherokee-project.com/doc/other_goodies.html#x-sendfile) -## Sending Response +## レスポンスを送信する -The content in a response is not sent to the user until the [[yii\web\Response::send()]] method is called. -By default, this method will be called automatically at the end of [[yii\base\Application::run()]]. You can, however, -explicitly call this method to force sending out the response immediately. +レスポンスの中のコンテントは、[[yii\web\Response::send()]] メソッドが呼ばれるまでは、エンドユーザに向けて送信されません。 +既定では、このメソッドは [[yii\base\Application::run()]] の最後で自動的に呼ばれます。しかし、 +このメソッドを明示的に呼んで、強制的にレスポンスを即座に送信することも可能です。 -The [[yii\web\Response::send()]] method takes the following steps to send out a response: +[[yii\web\Response::send()]] メソッドは次のステップを踏んでレスポンスを送出します。 -1. Trigger the [[yii\web\Response::EVENT_BEFORE_SEND]] event. -2. Call [[yii\web\Response::prepare()]] to format [[yii\web\Response::data|response data]] into - [[yii\web\Response::content|response content]]. -3. Trigger the [[yii\web\Response::EVENT_AFTER_PREPARE]] event. -4. Call [[yii\web\Response::sendHeaders()]] to send out the registered HTTP headers. -5. Call [[yii\web\Response::sendContent()]] to send out the response body content. -6. Trigger the [[yii\web\Response::EVENT_AFTER_SEND]] event. +1. [[yii\web\Response::EVENT_BEFORE_SEND]] イベントをトリガする。 +2. [[yii\web\Response::prepare()]] を呼んで [[yii\web\Response::data|レスポンスデータ]] を + [[yii\web\Response::content|レスポンスコンテント]] としてフォーマットする。 +3. [[yii\web\Response::EVENT_AFTER_PREPARE]] イベントをトリガする。 +4. [[yii\web\Response::sendHeaders()]] を呼んで、登録された HTTP ヘッダを送出する。 +5. [[yii\web\Response::sendContent()]] を呼んで、レスポンスのボディコンテントを送出する。 +6. [[yii\web\Response::EVENT_AFTER_SEND]] イベントをトリガする。 -After the [[yii\web\Response::send()]] method is called once, any further call to this method will be ignored. -This means once the response is sent out, you will not be able to append more content to it. +[[yii\web\Response::send()]] メソッドが一度呼び出された後では、このメソッドに対する更なる呼び出しは無視されます。 +このことは、いったんレスポンスが送出された後では、それにコンテントを追加することは出来なくなる、ということを意味します。 -As you can see, the [[yii\web\Response::send()]] method triggers several useful events. By responding to -these events, it is possible to adjust or decorate the response. +ごらんのように、the [[yii\web\Response::send()]] メソッドはいくつかの有用なイベントをトリガします。これらのイベントに反応することによって、 +レスポンスを調整したり修飾したりすることが出来ます。