[ja][WIP] translate 3-5-migration-guide.rst

en/appendices/3-5-migration-guide.rst

@@ -196,7 +196,7 @@ Console Integration Testing
 The ``Cake\TestSuite\ConsoleIntegrationTestCase`` class was added to make
 integration testing console applications easier. For more information, visit
 the :ref:`console-integration-testing` section. This test class is fully
-compatible with the current shell dispatcher as well as the new
+compatible with the current ``Cake\Console\ShellDispatcher`` as well as the new
 ``Cake\Console\CommandRunner``.
 
 Collection

en/development/routing.rst

@@ -61,7 +61,7 @@ you wish, you can restrict some parameters to conform to a regular expression::
         '/articles/:id',
         ['controller' => 'Articles', 'action' => 'view'],
         ['id' => '\d+', 'pass' => ['id']]
-    )
+    );
 
 The previous example changed the star matcher by a new placeholder ``:id``.
 Using placeholders allows us to validate parts of the URL, in this case we used

ja/controllers/components/cookie.rst

@@ -8,6 +8,10 @@
 CookieComponent は PHP に組み込まれている ``setcookie()`` メソッドのラッパーです。
 このコンポーネントは、 Cookie の扱いを容易にし、 Cookie のデータを暗号化します。
 
+.. deprecated:: 3.5.0
+    You should use :ref:`encrypted-cookie-middleware` instead of
+    ``CookieComponent``.
+
 Cookie の設定
 =================
 

ja/controllers/components/csrf.rst

@@ -26,6 +26,10 @@ hidden フィールドに CSRF トークンが追加されます。 ``Controller
     例外の型が :php:class:`Cake\\Network\\Exception\\ForbiddenException` から
     :php:class:`Cake\\Network\\Exception\\InvalidCsrfTokenException` に変更されました。
 
+.. deprecated:: 3.5.0
+    You should use :ref:`csrf-middleware` instead of
+    ``CsrfComponent``.
+
 CsrfComponent を使用する
 ============================
 

ja/controllers/middleware.rst

@@ -3,12 +3,34 @@
 
 ミドルウェアオブジェクトは、再利用可能で構成可能なリクエスト処理、あるいは
 レスポンス構築処理の層でアプリケーションを‘ラップ’する機能を提供します。
-ミドルウェアは CakePHP における新しい HTTP スタックの部分で、 PSR-7 のリクエスト
-およびレスポンスのインターフェイスを活用しています。 PSR-7 標準の活用によって、
-`Packagist <https://packagist.org>`__ で利用可能な、あらゆる PSR-7 互換の
-ミドルウェアを使うことができます。
+視覚的には、アプリケーションは中央で終了し、ミドルウェアはタマネギのように
+アプリの周囲を包み込みます。この例では、Routes、Assets、Exception Handling、
+およびCORSヘッダーミドルウェアでラップされたアプリケーションを見て取れます。
 
-CakePHP はいくつかのミドルウェアを既成で提供します。
+.. image:: /_static/img/middleware-setup.png
+
+When a request is handled by your application it enters from the outermost
+middleware. Each middleware can either delegate the request/response to the next
+layer, or return a response. Returning a response prevents lower layers from
+ever seeing the request. An example of that is the AssetMiddleware handling
+a request for a plugin image during development.
+
+.. image:: /_static/img/middleware-request.png
+
+If no middleware take action to handle the request, a controller will be located
+and have its action invoked, or an exception will be raised generating an error
+page.
+
+Middleware are part of the new HTTP stack in CakePHP that leverages the PSR-7
+request and response interfaces. Because CakePHP is leveraging the PSR-7
+standard you can use any PSR-7 compatible middleware available on `The Packagist
+<https://packagist.org>`__.
+
+CakePHP にあるミドルウェア
+==========================
+
+CakePHP はWebアプリケーションで一般的なタスクを取り扱うためのいくつかのミドルウェアを
+提供します。
 
 * ``Cake\Error\Middleware\ErrorHandlerMiddleware`` はラップされたミドルウェアからくる
   例外を捕まえ、 :doc:`/development/errors` の例外ハンドラーを使ってエラーページを描画します。
@@ -19,16 +41,26 @@ CakePHP はいくつかのミドルウェアを既成で提供します。
   リクエストにルーティングパラメーターを割り当てるために ``Router`` を使用します。
 * ``Cake\I18n\Middleware\LocaleSelectorMiddleware`` はブラウザーによって送られる
   ``Accept-Language`` ヘッダーによって自動で言語を切り替えられるようにします。
+* ``Cake\Http\Middleware\SecurityHeadersMiddleware`` makes it easy to add
+  security related headers like ``X-Frame-Options`` to responses.
+* ``Cake\Http\Middleware\EncryptedCookieMiddleware`` gives you the ability to
+  manipulate encrypted cookies in case you need to manipulate cookie with
+  obfuscated data.
+* ``Cake\Http\Middleware\CsrfProtectionMiddleware`` adds CSRF protection to your
+  application.
 
 .. _using-middleware:
 
 ミドルウェアの使用
 ==================
 
-``App\Application`` クラスの ``middleware`` メソッドの中でミドルウェアを加えることができます。
-もし ``App\Application`` クラスを持っていない場合、詳しくは :ref:`adding-http-stack`
-の当該のセクションを参照してください。アプリケーションの ``middleware`` フックメソッドは
-リクエスト処理の中で早くに呼ばれて、 ``Middleware`` オブジェクトを加えることができます。 ::
+ミドルウェアは、アプリケーションの全体、またはルーティングスコープ個別に適用できます
+
+すべてのリクエストにミドルウェアを適用するには、 ``App\Application`` クラスの
+``middleware`` メソッドを使用します。 ``App\Application`` クラスを持っていなかった場合、
+:ref:`adding-http-stack` の該当のセクションを参照してください。
+アプリケーションの ``middleware`` フックメソッドはリクエスト処理の開始時に
+呼ばれて ``MiddlewareQueue`` オブジェクトを加えることができます::
 
     namespace App;
 
@@ -37,11 +69,11 @@ CakePHP はいくつかのミドルウェアを既成で提供します。
 
     class Application extends BaseApplication
     {
-        public function middleware($middlewareStack)
+        public function middleware($middlewareQueue)
         {
             // ミドルウェアのキューにエラーハンドラーを結びつけます。
-            $middlewareStack->add(new ErrorHandlerMiddleware());
-            return $middlewareStack;
+            $middlewareQueue->add(new ErrorHandlerMiddleware());
+            return $middlewareQueue;
         }
     }
 
@@ -50,27 +82,27 @@ CakePHP はいくつかのミドルウェアを既成で提供します。
         $layer = new \App\Middleware\CustomMiddleware;
 
         // 追加されたミドルウェアは行列の末尾になります。
-        $middlewareStack->add($layer);
+        $middlewareQueue->add($layer);
 
         // 追加されたミドルウェアは行列の先頭になります。
-        $middlewareStack->prepend($layer);
+        $middlewareQueue->prepend($layer);
 
         // 特定の位置に挿入します。もし位置が範囲外の場合、
         // 末尾に追加されます。
-        $middlewareStack->insertAt(2, $layer);
+        $middlewareQueue->insertAt(2, $layer);
 
         // 別のミドルウェアの前に挿入します。
         // もしその名前のクラスが見つからない場合、
         // 例外が発生します。
-        $middlewareStack->insertBefore(
+        $middlewareQueue->insertBefore(
             'Cake\Error\Middleware\ErrorHandlerMiddleware',
             $layer
         );
 
         // 別のミドルウェアの後に挿入します。
         // もしその名前のクラスが見つからない場合、
         // ミドルウェアは末尾に追加されます。
-        $middlewareStack->insertAfter(
+        $middlewareQueue->insertAfter(
             'Cake\Error\Middleware\ErrorHandlerMiddleware',
             $layer
         );
@@ -88,8 +120,8 @@ CakePHP はいくつかのミドルウェアを既成で提供します。
 
     EventManager::instance()->on(
         'Server.buildMiddleware',
-        function ($event, $middlewareStack) {
-            $middlewareStack->add(new ContactPluginMiddleware());
+        function ($event, $middlewareQueueStack) {
+            $middlewareQueueStack->add(new ContactPluginMiddleware());
         });
 
 PSR-7 リクエストとレスポンス
@@ -238,17 +270,138 @@ PSR-7 リクエストとレスポンス
 
     class Application
     {
-        public function middleware($middlewareStack)
+        public function middleware($middlewareQueueStack)
         {
             // 単純なミドルウェアをキューに追加します
-            $middlewareStack->add(new TrackingCookieMiddleware());
+            $middlewareQueueStack->add(new TrackingCookieMiddleware());
 
             // もう少しミドルウェアをキューに追加します
 
-            return $middlewareStack;
+            return $middlewareQueueStack;
         }
     }
 
+.. _security-header-middleware:
+
+Adding Security Headers
+=======================
+
+The ``SecurityHeaderMiddleware`` layer makes it easy to apply security related
+headers to your application. Once setup the middleware can apply the following
+headers to responses:
+
+* ``X-Content-Type-Options``
+* ``X-Download-Options``
+* ``X-Frame-Options``
+* ``X-Permitted-Cross-Domain-Policies``
+* ``Referrer-Policy``
+
+This middleware is configured using a fluent interface before it is applied to
+your application's middleware stack::
+
+    use Cake\Http\Middleware\SecurityHeadersMiddleware;
+
+    $headers = new SecurityHeadersMiddleware();
+    $headers
+        ->setCrossDomainPolicy()
+        ->setReferrerPolicy()
+        ->setXFrameOptions()
+        ->setXssProtection()
+        ->noOpen()
+        ->noSniff();
+
+    $middlewareQueue->add($headers);
+
+.. versionadded:: 3.5.0
+    The ``SecurityHeadersMiddleware`` was added in 3.5.0
+
+.. _encrypted-cookie-middleware:
+
+Encrypted Cookie Middleware
+===========================
+
+If your application has cookies that contain data you want to obfuscate and
+protect against user tampering, you may can use CakePHP's encrypted cookie
+middleware to transparently encrypt and decrypt cookie data via middleware.
+Cookie data is encrypted with via OpenSSL using AES::
+
+    use Cake\Http\Middleware\EncryptedCookieMiddleware;
+
+    $cookies = new EncryptedCookieMiddleware(
+        // Names of cookies to protect
+        ['secrets', 'protected'],
+        Configure::read('Security.cookieKey')
+    );
+
+    $middlewareQueue->add($cookies);
+
+.. note::
+    It is recommended that the encryption key you use for cookie data, is used
+    *exclusively* for cookie data.
+
+The encryption algorithms and padding style used by the cookie middleware are
+backwards compatible with ``CookieComponent`` from earlier versions of CakePHP.
+
+.. versionadded:: 3.5.0
+    The ``EncryptedCookieMiddleware`` was added in 3.5.0
+
+.. _csrf-middleware:
+
+Cross Site Request Forgery (CSRF) Middleware
+============================================
+
+CSRF protection can be applied to your entire application, or to specific scopes
+by applying the ``CsrfProtectionMiddleware`` to your middleware stack::
+
+    use Cake\Http\Middleware\CsrfProtectionMiddleware;
+
+    $options = [
+        // ...
+    ];
+    $csrf = new CsrfProtectionMiddleware($options);
+
+    $middlewareQueue->add($csrf);
+
+Options can be passed into the middleware's constructor.
+The available configuration options are:
+
+- ``cookieName`` The name of the cookie to send. Defaults to ``csrfToken``.
+- ``expiry`` How long the CSRF token should last. Defaults to browser session.
+- ``secure`` Whether or not the cookie will be set with the Secure flag. That is,
+  the cookie will only be set on a HTTPS connection and any attempt over normal HTTP
+  will fail. Defaults to ``false``.
+- ``field`` The form field to check. Defaults to ``_csrfToken``. Changing this
+  will also require configuring FormHelper.
+
+When enabled, you can access the current CSRF token on the request object::
+
+    $token = $this->request->getParam('_csrfToken');
+
+.. versionadded:: 3.5.0
+    The ``CsrfProtectionMiddleware`` was added in 3.5.0
+
+
+Integration with FormHelper
+---------------------------
+
+The ``CsrfProtectionMiddleware`` integrates seamlessly with ``FormHelper``. Each
+time you create a form with ``FormHelper``, it will insert a hidden field containing
+the CSRF token.
+
+.. note::
+
+    When using CSRF protection you should always start your forms with the
+    ``FormHelper``. If you do not, you will need to manually create hidden inputs in
+    each of your forms.
+
+CSRF Protection and AJAX Requests
+---------------------------------
+
+In addition to request data parameters, CSRF tokens can be submitted through
+a special ``X-CSRF-Token`` header. Using a header often makes it easier to
+integrate a CSRF token with JavaScript heavy applications, or XML/JSON based API
+endpoints.
+
 .. _adding-http-stack:
 
 既存アプリケーションへの新しい HTTP スタック追加