Auth Laravel Package

Getting Started

The package builds on Laravel's native auth scaffolding rather than replacing it, so your first move is to get a stock Laravel app authenticating before adding awes-io/auth on top. Install with Composer, then read the service provider (AwesIO\Auth\AuthServiceProvider) before publishing anything — it reveals which routes, migrations, config keys, and view namespaces the package registers, which is faster than guessing from the README.

composer require awes-io/auth
php artisan vendor:publish --provider="AwesIO\Auth\AuthServiceProvider"
php artisan migrate

Publishing typically gives you a config file, migrations (social account linkage plus two-factor columns on users), and translatable views/notifications. Configure credentials in .env:

• AUTHY_API_KEY (and the sandbox/production flag) for two-factor.
• Standard Socialite keys per provider (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_REDIRECT_URI, etc.).

First use case: add two-factor to an existing login without rewriting your auth flow. Keep Laravel's LoginController, let the package intercept post-login, and enable the package's two-factor middleware on the routes you want protected. Verify the whole loop end-to-end (login → token challenge → session) in a local app before wiring it into a real project; the package is small (38 stars) and its assumptions about your User model are worth confirming early.

Implementation Patterns

Treat it as a route + controller layer, not a black box. The package ships controllers for login, registration, password reset, email verification, social redirect/callback, and the two-factor challenge. For day-to-day work, extend those controllers (or republish and edit them) rather than fighting the defaults. Overriding a single action — say, the post-registration redirect — is the common case.

Social login as an account-linking feature. The typical integration is: user signs up normally, later connects GitHub/Google. The package stores provider IDs in a social-accounts table keyed to user_id. Use this for "connect account" on a profile screen, not just "login with X", and guard against a provider identity already being linked to a different user (merge prompts, don't silently attach).

Two-fer gating with middleware. After the password check succeeds, users with two-factor enabled hit a challenge step. Protect sensitive route groups with the package's two-factor middleware, and keep the challenge route itself outside that group. A clean pattern is a TwoFactorRequired middleware alias registered in Kernel.php and applied to auth-protected groups.

Notifications and events. Email verification and 2FA prompts ride on Laravel notifications. Swap the package's notification classes for your own by rebinding them in a service provider — this is the cleanest extension point when you need branded emails or SMS fallback alongside Authy.

Blade-first integration. The default UI is Blade views. If you're building SPA/Vue (awes-io's home turf), use the package's JSON endpoints and let it return tokens or session cookies per your guard setup, rather than republishing views.

Config-first customization. Provider lists, redirect paths after login/logout, and 2FA enforcement live in the published config. Prefer config overrides in config/ over editing vendor files, so composer update stays safe.

Gotchas and Tips

• Authy is a hard dependency for 2FA. It needs a valid phone number and API key; sandbox vs. production matters. Users without a phone will break the flow — feature-flag 2FA per user, not globally, unless you've backfilled phone data.
• Config and route caching. After touching config or adding middleware aliases, run php artisan config:clear route:clear. A stale cached route list is the usual cause of "my override isn't firing."
• Route precedence for overrides. Package routes are registered in its service provider. To shadow one (e.g., a custom /login GET), register your route after the package loads — typically in RouteServiceProvider::boot() or by conditionally disabling the package route via config.
• Social account conflicts. Two accounts with the same email across providers, or a provider identity already linked elsewhere, produce confusing failures. Add an explicit "this email is already registered" branch in your callback handling.
• Migrations and the users table. The package assumes specific columns exist. If you're adding it to an existing app, diff the published migration against your schema rather than running it blindly — column name collisions (phone, verification timestamps) are common.
• Maintenance risk. Low star count and slow release cadence mean Laravel major-version compatibility is the biggest long-term concern. Pin the package version, and isolate it behind your own AuthService/contracts so you can swap in Fortify or a first-party 2FA solution without a rewrite.
• Email verification edge cases. If you already use Laravel's MustVerifyEmail, disable one of the two verification paths — running both produces duplicate emails and confusing middleware behavior.
• Debugging tip. Log the two-factor challenge lifecycle (challenge issued, token verified, fallback used). Authy network failures are silent in the default flow and look like "wrong code" to users.