README

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.

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 English, German, Dutch, and Russian
• Themed Views — Bootstrap 5 views shipped by default; mail templates separate and independently overridable

Requirements

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

Installation

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

Quick Start

1. Run migrations

php yii migrate

Five migrations create the user, profile, social_account, token, and session_history tables with all columns (2FA, GDPR, password expiration, last login IP, etc.) included.

2. Configure the module (optional)

Sensible defaults are auto-registered via the Yii3 config plugin — no manual setup required. To customize, override ModuleConfig in your application's config/params.php:

use YiiRocks\Voyti\ModuleConfig;

return [
    YiiRocks\Voyti\ModuleConfig::class => new ModuleConfig(
        enableRegistration: true,
        enablePasswordRecovery: true,
        enableTwoFactorAuthentication: true,
        recaptchaVersion: 'v3',
        emailChangeStrategy: 1,
        enableGdprCompliance: true,
        maxPasswordAge: 90,
        enableRestApi: true,
    ),
];

3. That's it

Routes, DI bindings, event listeners, and console commands are all auto-registered via the config plugin. The package works out of the box under the /voyti URL prefix.

Web routes cover security, registration, recovery, profile, settings, admin, and RBAC. REST API routes (under /voyti/api/v1) are enabled when enableRestApi is true.

Console commands:

Configuration Reference

ModuleConfig provides 40+ options:

Views

Web Views

Web views are in src/resources/views/bootstrap5/ and use the @voytiViews alias. They can be overridden via the Yii3 View theme pathMap:

// config/params.php
'yiisoft/view' => [
    'theme' => [
        'pathMap' => [
            '@voytiViews' => [
                '/path/to/your/custom/views',
                '@voyti/resources/views/bootstrap5',  // fallback
            ],
        ],
    ],
],

To use a different CSS framework (e.g. Tailwind), create your view files and point @voytiViews at them via pathMap, falling back to the bundled Bootstrap 5 views:

'yiisoft/view' => [
    'theme' => [
        'pathMap' => [
            '@voytiViews' => [
                '/path/to/your/tailwind/views',
                '@voyti/resources/views/bootstrap5',
            ],
        ],
    ],
],

Mail Views

Mail templates are in src/resources/mail/ and use the @voytiMail alias — separate from web views so they can be overridden independently:

'yiisoft/view' => [
    'theme' => [
        'pathMap' => [
            '@voytiMail' => [
                '/path/to/your/custom/mail',
                '@voyti/resources/mail',  // fallback
            ],
        ],
    ],
],

Middleware

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

Register them in your application's middleware pipeline as needed.

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' => [],
    ],
];

Social Authentication

Nine 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 SocialNetworkAuthenticateService handles account lookup, creation, and user login. The SocialNetworkAccountConnectService links a social account to an existing user.

Testing

# Unit tests (264 tests, 3509 assertions)
composer phpunit

# Mutation testing (275 mutants, 100% MSI)
composer infection

# Code style
composer php-cs-fixer

# Static analysis
composer psalm

# Mess detector
composer phpmd

Project Structure

src/
├── AuthClient/          9 social auth clients
├── Command/             4 console commands
├── Controller/          11 web controllers + 1 API controller
├── Entity/              5 ActiveRecord entities (User, Profile, Token, SocialNetworkAccount, SessionHistory)
├── Event/               11 event classes
├── Factory/             TokenFactory, MailFactory
├── Form/                9 form models (Login, Registration, Recovery, Resend, Settings, Rule, Permission, Role, Assignment, GdprDelete)
├── Helper/              5 helpers (Auth, Gravatar, Recaptcha, Security, Timezone)
├── Listener/            4 event listeners
├── Middleware/          3 PSR-15 middleware
├── Migration/           5 table-creation migrations
├── Repository/          6 repositories (User, Profile, Token, SocialNetworkAccount, SessionHistory + RepositoryTrait)
├── Service/             22 services + 5 session history services
├── Strategy/            3 email-change strategies + factory + interface
├── Validator/           5 validators
├── Widget/              4 widgets
├── resources/
│   ├── mail/            5 mail templates (independently overridable)
│   ├── messages/        4 locales (en, de, nl, ru)
│   └── views/
│       └── bootstrap5/  33 web views
└── ModuleConfig.php     40+ configuration options

Credits

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

License

MIT