Puzi Auth Bundle Laravel Package

Getting Started

This is the first public release (0.1.0) of puzi/auth-bundle, so treat the package as early-stage and API-unstable. The release notes only announce the initial cut, so the source and its composer.json/service provider are the authoritative reference—start there rather than assuming Laravel Breeze/Fortify conventions.

Recommended first steps:

1. Install with Composer (composer require puzi/auth-bundle) and confirm it supports your Laravel/PHP versions in composer.json before wiring anything up.
2. Read the service provider. Check src/ for PuziAuthBundleServiceProvider (or equivalent) to see what is auto-discovered, what gets bound in the container, and whether it registers routes, guards, or middleware.
3. Publish and inspect config. Run php artisan vendor:publish and review any published config/*.php and migration files. Since this is a v0.x, published config may still change between releases—treat it as a reference, not a stable contract.
4. Check for migrations and run php artisan migrate in a throwaway database first to see what tables the bundle expects.
5. First use case: get a single authentication flow working end-to-end—typically authenticating a user and protecting one route with a guard or middleware the bundle provides. Validate that before integrating with existing user models.

If the package registers its own guard or middleware, confirm the guard driver name in config/auth.php matches what the bundle exposes; this is usually the first thing that breaks.

Implementation Patterns

Given the limited release documentation, assume standard Laravel auth-package conventions and verify each against the source:

• Config-driven guards. Most auth bundles expose a guard driver that you register in config/auth.php. If present, set it up as a named guard and reference it with Auth::guard('puzi') or auth:puzi middleware, rather than relying on the default web guard.
• Middleware for route protection. If the bundle ships middleware, register it in app/Http/Kernel.php (or bootstrap/app.php in Laravel 11+) and apply it to route groups. Prefer group-level application over per-route to keep definitions consistent.
• Custom user model / contract. Determine whether the bundle expects you to implement an interface, extend a base model, or use your own App\Models\User. If it expects an interface, implement it on your existing model instead of swapping models—this keeps the rest of your app intact.
• Events and hooks. Check for dispatched events (e.g. login/logout) and listener extension points. Wiring your own listeners here is usually cleaner than overriding package internals.
• Integration with existing auth. If you already use Breeze, Fortify, or a custom flow, avoid running two auth systems against the same routes. Pick one owner of the login/logout routes and disable the other.

A minimal safe workflow: install → publish config/migrations → run migrations in a scratch DB → bind the guard → protect one test route → write a feature test asserting unauthenticated access is redirected and authenticated access succeeds. That test is your guard against breaking changes in the next 0.x release.

Gotchas and Tips

• 0.1.0 is pre-1.0. Expect breaking changes on minor bumps. Pin the version tightly ("puzi/auth-bundle": "0.1.*") and read changelogs before upgrading.
• Sparse release notes. The initial release notes give no detail on features, config keys, or supported Laravel versions. Do not infer behavior from the name—verify in src/.
• Service provider discovery. If the package isn't auto-discovered, you must add it to config/app.php providers. Check composer.json for a laravel.extra.providers block.
• Publishing collisions. If the bundle publishes migrations, watch for timestamp or table-name collisions with your existing auth tables. Run migrations on a fresh DB first; rename or adjust if it tries to recreate users.
• Guard caching. After changing config/auth.php, run php artisan config:clear—cached config is the most common cause of "guard not found" confusion during setup.
• Debugging auth failures. Use Auth::guard('puzi') in a Tinker session to confirm the guard resolves and the user provider is wired. If it returns null unexpectedly, the issue is almost always the provider model or a misconfigured driver, not the bundle logic.
• Extension points. Prefer the bundle's published config, events, and interfaces over editing vendor files. Since APIs are unstable at 0.1.x, keep customizations in your own service provider or listeners so upgrades don't overwrite them.
• Missing documentation. Flag this for the maintainer—until a README documents supported Laravel versions, config keys, and the guard contract, treat every integration detail as something to confirm from source before relying on it in production.