Nova Google2Fa Laravel Package

Getting Started

Start by installing the package and publishing its config and migrations:

composer require <vendor>/<package>
php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"
php artisan migrate

Look first at:

1. The published config file, usually config/user2fa.php or similar.
2. The package service provider to see how User2Fa is bound or resolved.
3. The package User2Fa class itself, especially its constructor and public methods.
4. The trait/contract/model integration expected on your User model.

The first day-to-day use case is enabling 2FA for a user: generate a secret, show a QR code, verify the first code, persist the secret, and issue recovery codes. In v1.0.1, the new override option means you can replace the package’s User2Fa implementation without forking the package. Use that only when you need custom secret generation, verification rules, recovery-code behavior, or storage semantics.

Implementation Patterns

Use the default package flow first. Most Laravel 2FA packages follow this shape:

• A user starts 2FA setup.
• The package generates and stores a secret.
• The app displays a QR code/secret.
• The user submits a TOTP code.
• The package verifies the code and marks 2FA as confirmed.
• Recovery codes are generated and stored.

For the new override capability, create an application-level class that extends the package class:

namespace App\Support;

use Vendor\Package\User2Fa as BaseUser2Fa;

class User2Fa extends BaseUser2Fa
{
    public function generateSecret(): string
    {
        // custom behavior, then fall back to parent where possible
        return parent::generateSecret();
    }

    public function verify(string $code): bool
    {
        // custom verification rules
        return parent::verify($code);
    }
}

Then register it using the package’s new override option. Depending on the package, this will be either a config value, a container binding, or both:

// config/user2fa.php
'class' => App\Support\User2Fa::class,

or:

// AppServiceProvider::register()
$this->app->bind(
    \Vendor\Package\User2Fa::class,
    \App\Support\User2Fa::class
);

Prefer extending the original class and calling parent:: for behavior you do not need to change. If the package resolves User2Fa from the container, use a binding; if it reads a config class name, set the config value. Check the package service provider to confirm which mechanism applies.

Common integration patterns:

• Keep 2FA enablement behind authentication and recent-password confirmation.
• Use the package’s middleware for the challenge step rather than duplicating login checks.
• Store secrets encrypted at rest using Laravel’s encrypted cast or the package’s built-in encryption.
• Generate recovery codes once, show them once, and store hashed versions.
• Add an application-level test that swaps in a custom User2Fa subclass and asserts your override is used.
• If you support multiple user types, bind separate User2Fa implementations per guard only if the package supports contextual resolution; otherwise keep one implementation and branch inside it.

For day-to-day work, treat User2Fa as the main extension point and avoid editing vendor files. The v1.0.1 release is specifically useful when you need small behavioral changes without maintaining a fork.

Gotchas and Tips

• Run php artisan config:clear after changing the override config. Cached config is the most common reason a custom User2Fa class is ignored.
• Confirm the override class is compatible with the package class. Extending the original class is safest; implementing only a contract can break if the package expects concrete methods.
• Preserve the parent constructor signature. If the package injects dependencies into User2Fa, your subclass must accept and forward them.
• If the package uses container binding rather than config, check app()->make(User2Fa::class) resolves to your class. A config-only change will not help in that case.
• Do not override verification in a way that weakens replay protection, rate limiting, or time-window checks. Call parent::verify() and add rules around it where possible.
• Keep recovery-code generation and secret storage consistent with the package’s migrations and model casts. Changing storage format can strand existing users.
• Test the upgrade from the previous version in a staging environment. v1.0.1 is additive, but confirm your app does not already bind or alias the package’s User2Fa class.
• Debug override issues by checking: config value, container binding, class_exists(), parent class compatibility, and whether the package instantiates User2Fa directly with new.
• Use the override for application-specific policy, not for package bugs. Report upstream issues instead of accumulating permanent subclass workarounds.
• If you do not need custom User2Fa behavior, v1.0.1 requires no code changes beyond a normal Composer update.