Voyti — Yii3 User Management Extension ¶

1. Table of Contents
2. Features
3. Requirements
4. Quick Start
5. Configuration
6. Social Authentication
7. Middleware
8. RBAC
9. Routes
10. Testing
11. Credits
12. License

войти
/vɐjˈtʲi/
verb

"to enter" or "to log in"

Highly customizable and extensible user management, authentication, and authorization extension for Yii3.

Ported from 2amigos/yii2-usuario and rebuilt for Yii3 with PSR-15 middleware, PSR-11 DI, ActiveRecord entities, FormModel forms, and the yiisoft/rbac package.

Table of Contents ¶

1. Features
2. Quick Start
3. Configuration
4. Social Authentication
5. Middleware
6. RBAC
7. Routes
8. Testing

Features ¶

• User Management — Registration, email confirmation, login/logout, password recovery, password expiration
• Profile Management — User profiles with gravatar, timezone, social links
• Social Authentication — 9 built-in auth clients (Facebook, GitHub, Google, LinkedIn, Twitter, VKontakte, Yandex, Keycloak, Microsoft365)
• Two-Factor Authentication — TOTP (authenticator app), email, and SMS 2FA with enforced-per-permission support
• RBAC Management — Full admin UI for roles, permissions, and rules with parent-child hierarchy, assignment management, and filtering
• Session Management — Session history tracking and termination
• GDPR Compliance — Consent management, data export, anonymized deletion with admin notification
• Password Policies — Minimum complexity requirements, max age enforcement via middleware
• Email Change Strategies — Three modes: insecure (immediate), default (confirm new address), secure (confirm both old and new)
• REST API — Optional JSON API for user CRUD
• CAPTCHA — Optional reCAPTCHA v2/v3 integration via yiirocks/recaptcha
• i18n — Built-in translations for multiple languages
• Themed Views — Bootstrap 5 views shipped by default; mail templates separate and independently overridable

Requirements ¶

• PHP >= 8.3
• Yii3 packages (yiisoft/db, yiisoft/rbac, yiisoft/view, yiisoft/validator, etc.)

Quick Start ¶

1. Install ¶

composer require yiirocks/voyti

For reCAPTCHA support (optional):

composer require yiirocks/recaptcha

For 2FA TOTP support (optional):

composer require chillerlan/php-authenticator chillerlan/php-qrcode

2. Run migrations ¶

Voyti provides its migration path through config/params-console.php using the standard yiisoft/db-migration configuration keys. With yiisoft/db-migration enabled in your console app, run:

./yii migrate:up

One migration creates the user, user_profile, user_social_account, user_token, and user_session_history tables with all columns (2FA, GDPR, password expiration, last login IP, etc.) included.

3. Done ¶

DI bindings, event listeners, and console commands are auto-registered via the Yii3 config plugin. No manual wiring needed.

Console commands:

To customize behaviour, see Configuration. To mount routes under a prefix, see Router Setup.

Configuration ¶

Override Voyti params in your app's config/params.php using the yiirocks/voyti key:

return [
    'yiirocks/voyti' => [
        'enableTwoFactorAuthentication' => true,
        'recaptchaVersion' => 'v3',
    ],
];

Below are all top-level yiirocks/voyti options, followed by the nested mailParams and socialNetworkClients options.

Authentication & Registration ¶

Two-Factor Authentication ¶

'yiirocks/voyti' => [
    'enableTwoFactorAuthentication' => true,
    'twoFactorAuthenticationForcedPermissions' => ['admin'],
],

GDPR ¶

'yiirocks/voyti' => [
    'enableGdprCompliance' => true,
    'gdprAnonymizePrefix' => 'ANON-',
],

Session & Security ¶

Views & Mail ¶

Mail params defaults:

[
    'fromEmail' => 'no-reply@example.com',
    'welcomeMailSubject' => 'Welcome to {app}',
    'confirmationMailSubject' => 'Confirm account on {app}',
    'reconfirmationMailSubject' => 'Confirm email change on {app}',
    'recoveryMailSubject' => 'Complete password reset on {app}',
    'twoFactorMailSubject' => 'Code for two factor authentication on {app}',
]

mailParams accepts the following keys:

REST API ¶

Social Authentication Providers ¶

socialNetworkClients is a keyed array where each key is a provider name such as github, google, or keycloak.

Every provider accepts these options unless noted otherwise:

Only Keycloak adds recognized extra options:

Social Authentication ¶

Various auth clients are included. Each implements the auth client interface and maps provider attributes to the SocialNetworkAccount entity:

• Facebook, GitHub, Google, Keycloak, LinkedIn, Microsoft365, Twitter, VKontakte, Yandex

The SocialAuthProviderService handles the OAuth redirect/callback flow. The UserSocialAuthenticateService handles account lookup, creation, and user login. The UserSocialAccountConnectService links a social account to an existing user.

Built-in defaults by provider ¶

The following table shows Voyti's built-in endpoints and scopes. These are used unless you override scope or redirectUri.

Provider-specific built-in request behavior ¶

Voyti also applies a few provider-specific defaults during the user-info step:

Example ¶

return [
    'yiirocks/voyti' => [
        'socialNetworkClients' => [
            'github' => [
                'clientId' => $_ENV['GITHUB_CLIENT_ID'] ?? '',
                'clientSecret' => $_ENV['GITHUB_CLIENT_SECRET'] ?? '',
            ],
            'google' => [
                'clientId' => $_ENV['GOOGLE_CLIENT_ID'] ?? '',
                'clientSecret' => $_ENV['GOOGLE_CLIENT_SECRET'] ?? '',
            ],
    ],
];

With credentials configured:

1. The login page shows social login buttons for configured providers.
2. settings/networks lists connected providers and renders connect buttons for the remaining configured providers.
3. New social identities redirect to the registration connect screen, where users can log in to an existing account or register a new one before the identity is linked.

Middleware ¶

The extension ships three PSR-15 middleware classes for access control:

Register them in your application's middleware pipeline as needed. Both redirect targets are configurable via ModuleConfig, so you can map them to your own route structure.

RBAC ¶

Built on yiisoft/rbac. The extension provides:

• Admin UI for managing permissions, roles, and rules (create, update, delete, filter)
• Assignment management — assign/revoke roles and permissions per user from the admin panel
• Parent-child hierarchy — roles can have child permissions/roles
• Rule management — register and manage custom RuleInterface classes

Default roles are configured in config/rbac.php:

return [
    'rbac' => [
        'guest' => [],
        'user' => [],
        'admin' => [],
    ],
];

Routes ¶

The library does not provide a menu model or navigation contract. It only exposes named routes that the host application can use in its own menu, sidebar, or access rules.

When enableRestApi is true, the API routes are mounted under adminRestPrefix and expose user CRUD endpoints for list, view, create, update, and delete.

Router Setup ¶

To mount Voyti routes under a prefix (e.g. /user), configure your router DI definition to include the voyti-routes config group:

// config/common/di/router.php
use Yiisoft\Config\Config;
use Yiisoft\Definitions\DynamicReference;
use Yiisoft\Router\Group;
use Yiisoft\Router\RouteCollection;
use Yiisoft\Router\RouteCollectionInterface;
use Yiisoft\Router\RouteCollector;

/** @var Config $config */

return [
    RouteCollectionInterface::class => [
        'class' => RouteCollection::class,
        '__construct()' => [
            'collector' => DynamicReference::to(
                static fn() => (new RouteCollector())->addRoute(
                    Group::create('/')
                        ->routes(...[
                            ...$config->get("routes"), // your own routes
                            Group::create('user/')
                                ->routes(...$config->get("voyti-routes"))
                        ],
                    ),
                ),
            ),
        ],
    ],
];

Without this configuration, Voyti routes are not registered.

Testing ¶

# Unit tests
composer phpunit

# Mutation testing
composer infection

# Static analysis
composer psalm

Credits ¶

Originally based on 2amigos/yii2-usuario by 2amigOS.

License ¶

MIT