Tyro Login Laravel Package

Getting Started

Treat this as an auth scaffolding package first, a feature library second. The happy path is a fresh Laravel app where you want login, registration, password reset, email verification, OTP/TOTP, and captcha without hand-rolling each flow.

Minimal sequence:

1. Install into a throwaway app first. composer require hasinhayder/tyro-login, then run the package's install/publish command exactly as documented in the README (config, migrations, views/assets). Don't guess tags — copy them from the docs.
2. Read the published config file top-to-bottom before touching anything else. This is where feature toggles, layouts/themes, mail templates, captcha, lockout thresholds, and social providers live. The config is the API surface for this package.
3. Check composer.json constraints and the service provider to see what it actually registers: routes, middleware aliases, guards, notifications, view namespaces. Any of these can collide with existing auth scaffolding.
4. Run migrations and smoke-test all flows manually: register → verify email → login → logout → forgot password → OTP → TOTP enrolment → lockout after N failures.
5. Pick your integration mode early (see below) — retrofitting is painful once views and routes are in use.

First real use case: a greenfield Laravel 12 app that needs a complete, themed auth UI in an afternoon. That's where the package earns its keep. If you already have Breeze/Jetstream/Fortify installed, expect friction.

Implementation Patterns

Two modes, choose deliberately.

• Full-package mode — let Tyro own the routes, controllers, middleware, and views. You publish views and override CSS/blade, and drive behaviour through config. Fastest path; highest coupling.
• Feature-slice mode — keep your own auth controllers and guards, and use the package only for discrete capabilities (OTP, TOTP, captcha, lockout). This is the safer long-term pattern if auth is core to your product, but requires reading the internals to bind to the right services/events rather than relying on the package's routes.

Config-driven feature toggling. Day-to-day, most changes are config edits: turning OTP on for login, switching layout/theme, enabling social providers, tightening lockout. Keep an environment-specific override (config/tyro-login.php reading from env()) so you can disable captcha in testing and loosen lockout in local.

Social login wiring. Provider credentials go in config/services.php; the package config maps which providers appear. Watch account-linking and email-collision policy — decide up front whether an existing email + social login auto-links or requires confirmation.

Theming and layouts. Choose one of the five layouts, publish it, and override via your own CSS layer rather than editing vendor blade files. Keeps upgrades clean.

Testing pattern. Write one feature test per flow (register, verify, login, reset, OTP, lockout). Use RefreshDatabase, disable captcha via config in phpunit.xml, and fake the mail/notification layer to assert templates fire. Assertion targets: session regeneration on login, redirects, and lockout state.

Deployment. php artisan config:cache after any config change; ensure published assets are in your build. If lockout uses the cache, confirm your production cache store is shared across nodes.

Gotchas and Tips

• Maturity risk is the headline. 252 stars and a low quality score on a package that owns your entire auth surface is a yellow flag. Audit the security-sensitive paths before production: OTP entropy and expiry, TOTP window/drift tolerance, session regeneration on login, password reset token handling, and rate-limit backing. Treat "Laravel 12 and 13" as a forward-looking marketing claim and verify actual composer.json constraints — if it targets an unreleased major, pin carefully.
• Route and middleware collisions. If Breeze/Fortify/Jetstream is present, you'll get duplicate routes, conflicting middleware aliases, or double-registered guards. Remove the competing scaffolding or run Tyro in feature-slice mode.
• Config cache staleness. After publishing or editing config, config:clear in dev. A cached config silently ignoring your new toggles is the most common "it's broken" report.
• Captcha in CI/tests. Always add a config bypass for the testing environment; otherwise every auth test fails on captcha validation.
• Lockout and cache. Brute-force lockout typically keys off the cache. In multi-server setups with a file or array store, lockouts won't be enforced consistently — use Redis/database cache.
• Mail templates. Overriding package email templates usually means publishing views and keeping namespaces aligned. Verify with Mail::fake() and by actually sending one through your real mailer in staging.
• Upgrade friction. Because views, routes, and config are published, composer update can silently diverge from your overrides. Keep a changelog diff of published files and re-publish selectively.
• Extension points to look for: package events (login, registered, lockout), container bindings for its services, and middleware you can prepend/append. Prefer hooking these over forking vendor code.
• Debugging approach: disable features one at a time in config to isolate failures, and check storage/logs plus the framework's auth events. Most issues trace back to config, guard mismatch, or a competing auth package.

Bottom line: high leverage for prototypes and internal tools where speed beats depth; for production systems with real security exposure, budget time to audit the package internals or wrap it in feature-slice mode so you can eject cleanly.