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 config/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 config/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 (see config/routes.php), 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 theme

This step is optional but highly recommended. Without it, forms and buttons will render without any styling.

Voyti’s forms (login, registration, profile, etc.) and button-styled links render through yiisoft/form’s ThemeContainer.

Set a theme in config/params.php. yiisoft/form ships ready-made Bootstrap 5 configs you can use as-is:
```
use Yiisoft\Form\Theme\ThemePath;
use Yiisoft\FormModel\ValidationRulesEnricher;

return [
    'yiisoft/form' => [
        'themes' => [
            'default' => [
                ...require ThemePath::BOOTSTRAP5_VERTICAL,
                'enrichFromValidationRules' => true,
                'validationRulesEnricher' => new ValidationRulesEnricher(),
            ],
        ],
        'defaultTheme' => 'default',
    ],
];
```
Swap in ThemePath::BOOTSTRAP5_HORIZONTAL for a horizontal label/input layout, or write your own array of Theme::__construct() options if you’re not using Bootstrap.

enrichFromValidationRules and validationRulesEnricher translate the yiisoft/validator rules on your 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

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

Configuration

Voyti

Quick Start

Verify prerequisites

Install

Set the cookie secret

Run migrations

Register routes

Configure the form theme

Done