leonardo/yii2-usuario
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add mkdocs and change menu names to avoid margin collisions (#468)

Browse Source
This commit is contained in:
Chris Smith
2022-08-18 15:39:18 -05:00
committed by GitHub
parent 99271a55c3
commit e460890be0
27 changed files with 30 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/customizing/how-to-enhance-a-user-model.md Normal file
View File

@ -0,0 +1,77 @@
How to Enhance a User Model
===========================
It is obvious that if you started your project development on Yii2 Framework, then your business and domain needs
are going to be very customized, and more or less unique. While our extension (and of course Yii2 Framework itself!)
provide sensible defaults where it's possible, we encourage and keep in mind user will extend classes.
Very often you have to override and add your own domain (or application specific code) to your user model. With this
extension this is very easy and can be done in a few minutes!
For the case if you're using [Sidekit Application Template](../install/sidekit-application-template.md) or
[Advanced Application Template](../install/advanced-application-template.md) create the following class file
at the `%PROJECT_DIR%/common/models/User.php` path:
```php
namespace common\models;
use Da\User\Model\User as BaseUser;
class User extends BaseUser
{
}
```
Then adjust configuration of `yii2-usuario` extension module as follows:
```php
'modules' => [
'user' => [
'class' => Da\User\Module::class,
'classMap' => [
'User' => common\models\User::class,
],
],
],
```
Another way to do that is to use Yii2 Dependency Injection configuration as we extensively use service container
feature. This is good approach too:
```php
'container' => [
'definitions' => [
Da\User\Model\User::class => common\models\User::class,
],
],
```
> Please note, the method above works only starting from Yii 2.0.10 and upper. In version 2.0.9 and lower you can
> use explicit calls to DI container from application `bootstrap.php` file.
Finally you can now add new methods, properties, and other things to your new `User` model class:
```php
// model
class User extends BaseUser
{
public function addFriend(User $friend)
{
// ...
}
}
// somewhere in controller
class ProfileController extends Controller
{
public function actionAddFriend(int $id)
{
Yii::$app->user->identity->addFriend(User::findOne($id));
}
}
```
> This is absolutely good way to extend almost any class of the extension. For more information you could
> check `Da\User\Bootstrap` class file to see what you have in your control.
© [2amigos](http://www.2amigos.us/) 2013-2019

113
docs/customizing/overriding-classes.md Normal file
View File

@ -0,0 +1,113 @@
Overriding Classes
==================
This module makes extensive use of the Yii2's Dependency Injection Container. The module has a special attribute
named `classMap` where it allows you to override specific classes.
The following are the classes that you can override throughout that attribute:
- Model Classes (AR)
- User
- SocialNetworkAccount
- Profile
- Token
- Assignment
- Permission
- Role
- Search Classes
- UserSearch
- PermissionSearch
- RoleSearch
- Form Classes
- RegistrationForm
- ResendForm
- LoginForm
- SettingsForm
- RecoveryForm
- Service Classes
- MailService
How to Override
---------------
The `classMap` contains an easy to recognize name and their correspondent definition. The default configuration can be
seen at the `Bootstrap` class:
```php
$defaults = [
// --- models
'User' => 'Da\User\Model\User',
'SocialNetworkAccount' => 'Da\User\Model\SocialNetworkAccount',
'Profile' => 'Da\User\Model\Profile',
'Token' => 'Da\User\Model\Token',
'Assignment' => 'Da\User\Model\Assignment',
'Permission' => 'Da\User\Model\Permission',
'Role' => 'Da\User\Model\Role',
// --- search
'UserSearch' => 'Da\User\Search\UserSearch',
'PermissionSearch' => 'Da\User\Search\PermissionSearch',
'RoleSearch' => 'Da\User\Search\RoleSearch',
// --- forms
'RegistrationForm' => 'Da\User\Form\RegistrationForm',
'ResendForm' => 'Da\User\Form\ResendForm',
'LoginForm' => 'Da\User\Form\LoginForm',
'SettingsForm' => 'Da\User\Form\SettingsForm',
'RecoveryForm' => 'Da\User\Form\RecoveryForm',
// --- services
'MailService' => 'Da\User\Service\MailService',
];
```
As you can see, the only thing we need to do is actually modify its definition. For example, the following configuration
will override the `RegistrationForm` class:
```php
namespace app\forms;
use Da\User\Form\RegistrationForm as BaseForm;
class RegistrationForm extends BaseForm {
/**
* Override from parent
*/
public function rules() {
// your logic
}
}
```
Now, to tell the module to use your class instead, you simply need to update the definition of that class into the
the `Module::classMap` attribute.
```php
// ...
'modules' => [
'user' => [
'class' => Da\User\Module::class,
'classMap' => [
'RegistrationForm' => 'app\forms\RegistrationForm'
]
]
]
```
The definition can be any of the following (from Yii2's DI container):
- a **PHP callable**: The callable will be executed when `Container::get()]]` is invoked. The signature of the callable
should be `function ($container, $params, $config)`, where `$params` stands for the list of constructor
parameters, `$config` the object configuration, and `$container` the container object. The return value
of the callable will be returned by `Container::get()]]` as the object instance requested.
- a **configuration array**: the array contains name-value pairs that will be used to initialize the property
values of the newly created object when `Container::get()]]` is called. The `class` element stands for the
the class of the object to be created. If `class` is not specified, `$class` will be used as the class name.
- a **string**: a class name, an interface name or an alias name.
> See [how to enhance a User model](how-to-enhance-a-user-model.md) guide to see a practical example.
© [2amigos](http://www.2amigos.us/) 2013-2019

82
docs/customizing/overriding-controllers.md Normal file
View File

@ -0,0 +1,82 @@
Overriding Controllers
======================
Maybe you need to override the default's functionality of the module's controllers. For that, as you probably know,
Yii2 Modules have an attribute named `controllerMap` that you can configure with your very own controllers.
Please, before you override a controller's action, make sure that it won't be enough with using the
[events](../events). For example you can use event for redirect after finish confirmation or recovery:
```php
'modules' => [
'user' => [
'controllerMap' => [
'recovery' => [
'class' => \Da\User\Controller\RecoveryController::class,
'on ' . \Da\User\Event\FormEvent::EVENT_AFTER_REQUEST => function (\Da\User\Event\FormEvent $event) {
\Yii::$app->controller->redirect(['/user/security/login']);
\Yii::$app->end();
},
'on ' . \Da\User\Event\ResetPasswordEvent::EVENT_AFTER_RESET => function (\Da\User\Event\ResetPasswordEvent $event) {
if ($event->token->user ?? false) {
\Yii::$app->user->login($event->token->user);
\Yii::$app->session->setFlash('success', Yii::t('usuario', 'Password has been changed'));
}
\Yii::$app->controller->redirect(\Yii::$app->getUser()->getReturnUrl());
\Yii::$app->end();
},
],
'registration' => [
'class' => \Da\User\Controller\RegistrationController::class,
'on ' . \Da\User\Event\FormEvent::EVENT_AFTER_REGISTER => function (\Da\User\Event\FormEvent $event) {
\Yii::$app->controller->redirect(['/user/security/login']);
\Yii::$app->end();
},
'on ' . \Da\User\Event\FormEvent::EVENT_AFTER_RESEND => function (\Da\User\Event\FormEvent $event) {
\Yii::$app->session->setFlash('info', Yii::t('usuario', 'A message has been sent to your email address. It contains a confirmation link that you must click to complete registration.'));
\Yii::$app->controller->redirect(['/user/security/login']);
\Yii::$app->end();
},
],
...
```
> See more about this attribute on
> [ The Definitive Guide to Yii 2.0](http://www.yiiframework.com/doc-2.0/guide-structure-controllers.html#controller-map)
How to Override
---------------
First, create your new controller:
```php
namespace app\controllers;
use Da\User\Controller\RegistrationController as BaseController;
class ProfileController extends BaseController {
public function actionConfirm($id, $code) {
// ... your code here
}
}
```
Now, the only thing that is missing is to add your brand new controller to the module's controller's map:
```php
'modules' => [
// ...
'user' => [
'class' => 'Da\User\Module',
'controllerMap' => [
'profile' => 'app\controllers\ProfileController'
]
]
]
```
© [2amigos](http://www.2amigos.us/) 2013-2019

57
docs/customizing/overriding-views.md Normal file
View File

@ -0,0 +1,57 @@
Overriding Views
================
In case you need to override the default views (that you surely have to do if you use a different them than default's
Bootstrap), Yii2 provides a mechanism that is really easy to do:
```php
// ... other configuration here
'components' => [
'view' => [
'theme' => [
'pathMap' => [
'@Da/User/resources/views' => '@app/views/user'
]
]
]
]
// ...
```
The above code tells Yii2 to search on `@app/view/user` for views prior to go to `@Da/User/resources/views`. That is,
if a view is found on `@app/view/user` that matches the required render it will be displayed instead of the one on
`@Da/User/resources/views`.
You need to remember that the folder structure on your new location must match that of the module. For example, if we
wish to override the `login.php` view using the above setting, we would have to create the following structure on our
path:
```
app [ Your root ]
|
└─ views
└─ user
└─ security
login.php
```
See how it follows the same structure as within the User's module `resources/views` path? Well, that's what you should
do with any of the others in order to override them.
There is another way, and is by setting the `viewPath` attribute of the module:
```php
'modules' => [
'user' => [
'class' => Da\User\Module::class,
'viewPath' => '@app/views/user'
],
],
```
But it will force you to override **ALL** views from the module. The recommended way is throughout the `theme` property
of `view` component as previously mentioned.
© [2amigos](http://www.2amigos.us/) 2013-2019