From a1f396c5d85751c6a4dd313462967c4d98e5d748 Mon Sep 17 00:00:00 2001
From: Carsten Brandt <mail@cebe.cc>
Date: Wed, 31 May 2017 15:36:50 +0200
Subject: [PATCH] improved docs

---
 docs/guide/security-authorization.md | 50 +++++++++++++---------------
 framework/filters/AccessRule.php     | 14 +++++---
 2 files changed, 34 insertions(+), 30 deletions(-)

diff --git a/docs/guide/security-authorization.md b/docs/guide/security-authorization.md
index fed710e4f9f..55dc0458935 100644
--- a/docs/guide/security-authorization.md
+++ b/docs/guide/security-authorization.md
@@ -491,36 +491,34 @@ public function behaviors()
 If all the CRUD operations are managed together then it's a good idea to use a single permission, like `managePost`, and
 check it in [[yii\web\Controller::beforeAction()]].
 
-You can also use rules from the [[yii\filters\AccessControl|AccessControl]] filter. For that you specify the
-[[yii\filters\AccessRule::roleParams|roleParams]] that you need to pass to the [[yii\filters\AccessRule|AccessRule]]:
-
+In the above example, no parameters are passed with the roles specified for accessing an action, but in case of the
+`updatePost` permission, we need to pass a `post` parameter for it to work properly.
+You can pass parameters to [[yii\web\User::can()]] by specifying [[yii\filters\AccessRule::roleParams|roleParams]] on
+the access rule:
 
 ```php
-use yii\filters\AccessControl;
-
-class PostsController extends Controller
-{
-    public function behaviors()
-    {
-        return [
-            'access' => [
-                'class' => AccessControl::className(),
-                'rules' => [
-                    [
-                        'actions' => ['update'],
-                        'roles' => ['updatePost'],
-                        'roleParams' => function() {
-                            return ['post' => Post::findOne(Yii::$app->request->get('id'))];
-                        },
-                        'allow' => true,
-                    ],
-                ],
-            ],
-        ];
-    }
-}
+[
+    'allow' => true,
+    'actions' => ['update'],
+    'roles' => ['updatePost'],
+    'roleParams' => function() {
+        return ['post' => Post::findOne(Yii::$app->request->get('id'))];
+    },
+],
 ```
 
+In the above example, [[yii\filters\AccessRule::roleParams|roleParams]] is a Closure that will be evaluated when
+the access rule is checked, so the model will only be loaded when needed.
+If the creation of role parameters is a simple operation, you may just specify an array, like so:
+
+```php
+[
+    'allow' => true,
+    'actions' => ['update'],
+    'roles' => ['updatePost'],
+    'roleParams' => ['postId' => Yii::$app->request->get('id')];
+],
+```
 
 ### Using Default Roles <span id="using-default-roles"></span>
 
diff --git a/framework/filters/AccessRule.php b/framework/filters/AccessRule.php
index 892dbd24fb6..26d3d2b8ff4 100644
--- a/framework/filters/AccessRule.php
+++ b/framework/filters/AccessRule.php
@@ -63,10 +63,16 @@ class AccessRule extends Component
      * @var array|Closure parameters to pass to the [[User::can()]] function for evaluating
      * user permissions in [[$roles]].
      *
-     * If this is an array, it will be passed directly to [[User::can()]].
+     * If this is an array, it will be passed directly to [[User::can()]]. For example for passing an
+     * ID from the current request, you may use the following:
+     *
+     * ```php
+     * ['postId' => Yii::$app->request->get('id')]
+     * ```
+     *
      * You may also specify a closure that returns an array. This can be used to
-     * evaluate the array values only if they are needed.
-     * This can be used for example like this:
+     * evaluate the array values only if they are needed, for example when a model needs to be
+     * loaded like in the following code:
      *
      * ```php
      * 'rules' => [
@@ -75,7 +81,7 @@ class AccessRule extends Component
      *         'actions' => ['update'],
      *         'roles' => ['updatePost'],
      *         'roleParams' => function($rule) {
-     *             return ['postId' => Yii::$app->request->get('id')];
+     *             return ['post' => Post::findOne(Yii::$app->request->get('id'))];
      *         },
      *     ],
      * ],