From 7a73c0937c101c723bcb52c61de7b4d4bd081424 Mon Sep 17 00:00:00 2001
From: Philippe Gaultier <pgaultier@gmail.com>
Date: Fri, 4 Jul 2014 17:32:20 +0200
Subject: [PATCH] Adding CORS documentation

---
 docs/guide/README.md    |  1 +
 docs/guide/rest-cors.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 docs/guide/rest-cors.md

diff --git a/docs/guide/README.md b/docs/guide/README.md
index 37caef1..cfe4a1d 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -134,6 +134,7 @@ RESTful Web Services
 * [Routing](rest-routing.md)
 * [Response Formatting](rest-response-formatting.md)
 * [Authentication](rest-authentication.md)
+* [Cross Origin Resource Sharing](rest-cors.md)
 * [Rate Limiting](rest-rate-limiting.md)
 * [Versioning](rest-versioning.md)
 * [Error Handling](rest-error-handling.md)
diff --git a/docs/guide/rest-cors.md b/docs/guide/rest-cors.md
new file mode 100644
index 0000000..0a77fc1
--- /dev/null
+++ b/docs/guide/rest-cors.md
@@ -0,0 +1,78 @@
+Cross Origin Resource Sharing (CORS)
+====================================
+
+Cross-origin resource sharing (CORS) is a mechanism that allows many resources (e.g. fonts, JavaScript, etc.)
+on a web page to be requested from another domain outside the domain the resource originated from.
+In particular, JavaScript's AJAX calls can use the XMLHttpRequest mechanism. Such "cross-domain" requests would
+otherwise be forbidden by web browsers, per the same origin security policy.
+CORS defines a way in which the browser and the server can interact to determine whether or not to allow the cross-origin request.
+
+To enable CORS management, the [[yii\filters\Cors|Cors filter]] should be added to the target controllers.
+
+The [[yii\filters\Cors|Cors filter]] should be defined before Authentication / Authorization filters to make sure the CORS headers
+will always be sent.
+
+```php
+public function behaviors()
+{
+    $behaviors = ArrayHelper::merge([
+        'corsHeaders' => [
+            'class' => \yii\filters\Cors::className(),
+        ],
+    ], parent::behaviors());
+    return $behaviors;
+}
+```
+
+The Cors filtering could be tuned using the `cors` property.
+
+* `cors['Origin']`: array used to define allowed origins. Can be `['*']` (everyone) or `['http://www.myserver.net', 'http://www.myotherserver.com']`. Default to `['*']`.
+* `cors['Access-Control-Request-Method']`: array of allowed verbs like `['GET', 'OPTIONS', 'HEAD']`.  Default to `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']`.
+* `cors['Access-Control-Request-Headers']`: array of allowed headers. Can be `['*']` all headers or specific ones `['X-Request-With']`. Default to `['*']`.
+* `cors['Access-Control-Allow-Credentials']`: define if current request can be made using credentials. Can be `true`, `false`. Default to `true`.
+* `cors['Access-Control-Max-Age']`: define lifetime of pre-flight request. Default to `86400`.
+
+For example, allowing CORS for origin : `http://www.myserver.net` with method `GET`, `HEAD` and `OPTIONS` and do not send `Access-Control-Allow-Credentials` header :
+
+```php
+public function behaviors()
+{
+    $behaviors = ArrayHelper::merge([
+        'corsHeaders' => [
+            'class' => \yii\filters\Cors::className(),
+            'cors' => [
+                'Origin' => ['http://www.myserver.net'],
+                'Access-Control-Request-Method' => ['GET', 'HEAD', 'OPTIONS'],
+                'Access-Control-Allow-Credentials' => null,
+            ],
+        ],
+    ], parent::behaviors());
+    return $behaviors;
+}
+```
+
+You may tune the CORS headers by overriding default parameters on a per action basis.
+For example adding the `Access-Control-Allow-Credentials` for `login` action could be done like this :
+
+```php
+public function behaviors()
+{
+    $behaviors = ArrayHelper::merge([
+        'corsHeaders' => [
+            'class' => \yii\filters\Cors::className(),
+            'cors' => [
+                'Origin' => ['http://www.myserver.net'],
+                'Access-Control-Request-Method' => ['GET', 'HEAD', 'OPTIONS'],
+                'Access-Control-Allow-Credentials' => null,
+            ],
+            'actions' => [
+                'login' => [
+                    'Access-Control-Allow-Credentials' => true,
+                ]
+            ]
+        ],
+    ], parent::behaviors());
+    return $behaviors;
+}
+```
+