Voyti

User management, authentication & authorization

Quick Start

Verify prerequisites
- PHP 8.3 or higher with ext-intl
- A connected database in your host application via Yii Database
Install
Voyti's core is view-agnostic; you need a views implementation package to render any pages. voyti-views-bootstrap5 is the reference implementation using Bootstrap 5. You can substitute an alternative views package if you prefer a different UI framework, as long as it announces its views directory through the viewsPackagePaths param.
Building an API-only backend instead? voyti-api-stateless-client already provides the yiirocks/voyti-views contract itself, so installing it satisfies this requirement without a separate views package.
Optional packages to extend functionality:
Bot Protection
Google reCAPTCHA v2/v3 for registration and login forms
Brute-force Protection
Exponential backoff delays for failed login and registration attempts, tracked per IP address
GDPR Data Handling
Export user data and anonymize accounts for compliance with data protection regulations
REST API / User
JSON user CRUD endpoints with bearer-token authentication and API key lifecycle management. Add the optional rate-limiter package for per-user request throttling.

Stateless Client API
Credential login, registration, password reset, profile and session management for SPAs and other bearer-token clients
Social Authentication
OAuth2 login via Google, GitHub, Facebook, and more
Toast Notifications
Renders Voyti's flash messages as Bootstrap 5 toasts
Two-Factor Authentication
Email codes and/or TOTP (authenticator app) and/or WebAuthn/passkeys for stronger account security
Set the cookie secret
Voyti encrypts the remember-me cookie using yiisoft/cookies' secret key. Leaving it unset throws a LogicException. Generate a strong, random string and set it in params.php.
```
return [
    'yiisoft/cookies' => [
        'secretKey' => $_ENV['COOKIES_SECRET'],
    ],
];
```
Here's a random value for secretKey, in case you need one:
Run migrations
Voyti provides its migration path through params-console.php using the standard yiisoft/db-migration configuration keys. With yiisoft/db-migration enabled in your console app, run:
Voyti's migration creates 6 user-related tables (user, user_profile, user_token, user_sessions, user_password_history, user_audit_log) and seeds default roles and permissions into the RBAC tables created by yiisoft/rbac-db.
The same migration also seeds a default admin account: username admin, email admin@example.com, and a random password printed to the console. Change this password immediately after first login.
The account is assigned the administrator role, which is granted the administratorPermissionName permission needed to reach the admin dashboard.

Register routes

Routes are not auto-registered - you must add them to your router configuration.

Pull the voyti-routes config group into your router definition. The example below mounts them under a /user/ prefix as their own group, alongside your app’s own routes:

use Yiisoft\Config\Config;
use Yiisoft\Definitions\DynamicReference;
use Yiisoft\Router\Group;
use Yiisoft\Router\RouteCollection;
use Yiisoft\Router\RouteCollectionInterface;
use Yiisoft\Router\RouteCollector;
use Yiisoft\Session\SessionMiddleware;
use YiiRocks\Voyti\Middleware\VoytiMiddleware;

/** @var Config $config */

return [
    RouteCollectionInterface::class => [
        'class' => RouteCollection::class,
        '__construct()' => [
            'collector' => DynamicReference::to(
                static fn() => (new RouteCollector())
                    ->addRoute(
                        Group::create('/')
                            ->middleware(
                                SessionMiddleware::class,                  # required for site-wide session support
                                VoytiMiddleware::class,                    # Site-wide enforcement
                            )
                            ->routes(...$config->get('routes')),           # Your routes
                        Group::create('/user/')                            # Voyti web URL prefix
                            ->routes(...$config->get('voyti-routes')),     # Voyti web routes
                    )
            ),
        ],
    ],
];

voyti-routes already wraps itself with its own required middleware, so the group above doesn’t repeat any of it, and adding VoytiMiddleware to your own group only extends that same coverage to your app’s pages.

Configure the form and widget themes
This configuration is optional, but recommended when using views. Without it, forms, buttons, and widgets render without styling.
Forms (login, registration, profile, etc.) and button-styled links render through the ThemeContainer of yiisoft/form. Some views can also use yiisoft/widget, which applies the configured widget theme.
Configure themes in your application’s params.php. Both packages provide Bootstrap 5 themes by default:
```
use Yiisoft\Form\Theme\ThemePath;
use Yiisoft\FormModel\ValidationRulesEnricher;

return [
    'yiisoft/form' => [
        'themes' => [
            'default' => [
                ...require ThemePath::BOOTSTRAP5_VERTICAL, # ThemePath::BOOTSTRAP5_HORIZONTAL is also available
                'enrichFromValidationRules' => true,
                'validationRulesEnricher' => new ValidationRulesEnricher(),
            ],
        ],
        'defaultTheme' => 'default',
    ],

    'yiisoft/widget' => [
        'defaultTheme' => 'bootstrap5',
    ],
];
```
enrichFromValidationRules and validationRulesEnricher translate the yiisoft/validator rules on form models (Required, Length, Regex, etc.) into matching HTML5 input attributes (required, minlength/maxlength, pattern, and so on), giving you client-side validation automatically.
Done
You’re ready to use the extension. Enjoy using Voyti in your application. If you run into an issue, open an issue on GitHub.

Configuration

Voyti

Quick Start

Verify prerequisites

Install

Set the cookie secret

Run migrations

Register routes

Configure the form and widget themes

Done