update docs

yii1tech · Jun 16, 2023 · a425c82 · a425c82
1 parent 6d18cd2
commit a425c82
Show file tree

Hide file tree

Showing 2 changed files with 135 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -57,8 +57,8 @@ return [
     'components' => [
         'user' => [
             'class' => yii1tech\web\user\WebUser::class,
-            'onAfterLogin' => function (CEvent $raisedEvent) {
-                Yii::log('User login ID=' . $raisedEvent->sender->getId());
+            'onAfterLogin' => function (CEvent $event) {
+                Yii::log('Login User ID=' . $event->sender->getId());
             },
         ],
         // ...
@@ -79,11 +79,11 @@ return [
     'components' => [
         'user' => [
             'class' => yii1tech\web\user\WebUser::class,
-            'onAfterRestore' => function (CEvent $raisedEvent) {
-                $user = User::model()->findByPk($raisedEvent->sender->getId());
+            'onAfterRestore' => function (CEvent $event) {
+                $user = User::model()->findByPk($event->sender->getId());
 
                 if (empty($user) || $user->is_banned) {
-                    $raisedEvent->sender->logout(false);
+                    $event->sender->logout(false);
                 }
             },
         ],
@@ -93,6 +93,9 @@ return [
 ];
 ```
 
+
+## Operating ActiveRecord model via WebUser
+
 This package also provides `yii1tech\web\user\ActiveRecordModelBehavior` behavior for the `yii1tech\web\user\WebUser`, which allows
 operating ActiveRecord model at the WebUser component level.
 
@@ -109,7 +112,7 @@ return [
                 'modelBehavior' => [
                     'class' => yii1tech\web\user\ActiveRecordModelBehavior::class,
                     'modelClass' => app\models\User::class, // ActiveRecord class to used for model source
-                    'attributeToStateMap' => [ // map for WebUser states fill up
+                    'attributeToStateMap' => [ // map for WebUser states fill up from ActiveRecord model attributes
                         'username' => '__name', // matches `Yii::app()->user->getName()`
                         'email' => 'email', // matches `Yii::app()->user->getState('email')`
                     ],
@@ -133,4 +136,127 @@ $user = Yii::app()->user->getModel();
 var_dump($user->id == Yii::app()->user->getId()); // outputs `true`
 var_dump($user->username == Yii::app()->user->getName()); // outputs `true`
 var_dump($user->email == Yii::app()->user->getState('email')); // outputs `true`
+
+$user->setAttributes($_POST['User']);
+$user->save();
 ```
+
+In case there is no authenticated user `yii1tech\web\user\ActiveRecordModelBehavior::getModel()` returns `null`.
+For example:
+
+```php
+<?php
+
+$user = Yii::app()->user->getModel();
+if ($user) {
+    var_dump(Yii::app()->user->getIsGuest()); // outputs `false`
+} else {
+    var_dump(Yii::app()->user->getIsGuest()); // outputs `true`
+}
+```
+
+By default `yii1tech\web\user\ActiveRecordModelBehavior` automatically logs out any authenticated user, if it is unable to get his
+related record from database. You may control this behavior via `yii1tech\web\user\ActiveRecordModelBehavior::$autoSyncModel`.
+
+You may add extra condition for the user search query via `yii1tech\web\user\ActiveRecordModelBehavior::$modelFindCriteria`.
+This allows you to handle such things as user's ban or account confirmation. For example:
+
+```php
+<?php
+
+return [
+    'components' => [
+        'user' => [
+            'class' => yii1tech\web\user\WebUser::class,
+            'behaviors' => [
+                'modelBehavior' => [
+                    'class' => yii1tech\web\user\ActiveRecordModelBehavior::class,
+                    'modelClass' => app\models\User::class,
+                    'modelFindCriteria' => [
+                        'scopes' => [
+                            'activeOnly',
+                        ],
+                        'condition' => 'is_banned = 0',
+                    ],
+                ],
+            ],
+        ],
+        // ...
+    ],
+    // ...
+];
+```
+
+You may use `yii1tech\web\user\ActiveRecordModelBehavior::setModel()` method to switch user identity. For example:
+
+```php
+<?php
+
+$user = User::model()->findByPk(1);
+
+Yii::app()->user->setModel($user);
+
+var_dump(Yii::app()->user->getIsGuest()); // outputs `false`
+var_dump($user->id == Yii::app()->user->getId()); // outputs `true`
+```
+
+> Note: while method `yii1tech\web\user\ActiveRecordModelBehavior::setModel()` can be used for user identity switching, 
+  it is not equal to `\CWebUser::login()` or `\CWebUser::changeIdentity()`, since it does not handle related Cookies
+  and some other related features.
+
+You may use `yii1tech\web\user\ActiveRecordModelBehavior::setModel()` in junction with ["yii1tech/session-dummy"](https://github.com/yii1tech/session-dummy)
+to easily create authentication flow for API. For example:
+
+```php
+<?php
+
+namespace app\web\controllers;
+
+use app\models\OAuthToken;
+use app\models\User;
+use CController;
+use Yii;
+use yii1tech\session\dummy\DummySession;
+
+class ApiController extends CController
+{
+    public function init()
+    {
+        parent::init();
+
+        // mock session, so it does not send any Cookies to the API client:
+        Yii::app()->setComponent('session', new DummySession(), false);
+
+        // find OAuth token matching request:
+        $oauthToken = OAuthToken::model()->findByPk(Yii::app()->request->getParam('oauth_token'));
+        if (!$oauthToken) {
+            return;
+        }
+
+        // find User matching OAuth token:
+        $user = User::model()->findByPk($oauthToken->user_id);
+        if (!$user) {
+            return;
+        }
+
+        // act as found user:
+        Yii::app()->user->setModel($user);
+    }
+
+    public function filters()
+    {
+        return [
+            'accessControl', // now we can freely use standard "access control" filter and other features
+        ];
+    }
+
+    public function accessRules()
+    {
+        return [
+            // ...
+        ];
+    }
+
+    // ...
+}
+```
diff --git a/src/WebUser.php b/src/WebUser.php
@@ -15,6 +15,9 @@
  *     'components' => [
  *         'user' => [
  *             'class' => yii1tech\web\user\WebUser::class,
+ *             'onAfterLogin' => function (CEvent $event) {
+ *                 Yii::log('Login User ID=' . $event->sender->getId());
+ *             },
  *         ],
  *         // ...
  *     ],