Auth Kit Bundle Laravel Package

Getting Started

Reality check first: this is a Symfony bundle, not a Laravel package. If you're coming from Laravel, map your mental model: no php artisan vendor:publish, no service provider auto-discovery. Instead you get Composer install + bundle registration + YAML config + Twig template overrides under templates/bundles/.

1. Install and register (Symfony Flex usually does the registration):

   composer require nowo-tech/auth-kit-bundle
   

   Confirm the bundle is listed in config/bundles.php with the key the package documents (namespace matches Nowo\...\AuthKitBundle).

2. Import routes. Add a routes file (e.g. config/routes/auth_kit.yaml) pointing at the bundle's routing resource, and check the bundle's Resources/config/routes.* for the exact resource path. Run php bin/console debug:router | grep -i auth to see exactly what got registered — this is your fastest source of truth.

3. Configure one named profile. Open the bundle's DependencyInjection/Configuration.php (or its README config reference) to get the real config alias and keys. Then enable the minimum: a single profile with login + registration turned on, templates left at defaults, and no locale prefix yet.

4. Wire the firewall. Point security.yaml's form_login at the login route the bundle exposes, define login_path / check_path, and set a logout route. Until this is done, the routes render but nothing authenticates.

5. First use case: log in, register, hit "forgot password," and confirm the reset email arrives (use Mailpit/symfony/mailer in dev + the profiler). Then override one Twig template locally to prove the theming path works before you invest in design.

Where to look first: the bundle's README config block, Resources/config/routes.*, the Templates/ directory, and the Configuration.php tree. Those four files tell you 90% of what you need.

Implementation Patterns

Named profiles are the main lever. Treat profiles as app segments — e.g. public (self-service registration), admin (login only, stricter templates), partner (magic-login only). Each profile gets its own enabled features, template set, and route prefix. Configure them under the bundle's profiles config key and give each a distinct path (/login vs /admin/login) so you can attach separate firewalls.

Locale-prefixed routes. The bundle supports /{_locale}/... route patterns. Configure a _locale default on the profile, keep requirements: { _locale: en|fr|de }, and generate links with the locale argument in Twig. If you also need bare /login (no prefix), register a redirect or a second profile rather than fighting the route requirements.

Template overrides the Symfony way. Copy the vendor template into templates/bundles/AuthKitBundle/<subpath>/<file>.twig, change only the blocks you need, and leave the rest inherited. Never edit inside vendor/ — the next composer update wipes it. Keep block names and DOM ids stable if your JS hooks depend on them.

Magic login in practice. Generate the signed link, hand it to Symfony Mailer (optionally via Messenger for async delivery), and consume the token on a POST handler so it never sits in the Referer header or browser history. Set a short TTL and enforce single-use in your config if exposed.

Password reset flow. The bundle emits the request/confirm routes; you supply the mailer transport and a reset-email template override. Chain it with symfony/notifier if you want SMS fallback, but keep the email path working first.

Hooking into lifecycle events. Prefer the bundle's event subscribers/listeners for post-registration or post-reset side effects (welcome mail, audit log) over decorating controllers. If no event exists for what you need, decorate the specific service via services.yaml and keep the public service id unchanged so future bundle updates don't break you.

Security integration. One firewall per profile path, access_control sorted most-specific-first, and a shared User provider. If you're using a custom authenticator, let the bundle own only the form/route layer and keep your authenticator focused on credential checks — that's the seam most likely to survive upgrades.

Gotchas and Tips

• It's Symfony, not Laravel. Don't look for publish commands, facades, or Eloquent bindings. Everything is DI, YAML, and Twig-bundle-override conventions.
• Config alias is not guessable. Verify the real root key in Configuration.php before writing YAML; a wrong alias silently does nothing and you'll spend an hour wondering why registration is still off.
• Locale routes order matters. A catch-all /{_locale}/... pattern will shadow non-locale routes. Register non-localized routes first, or constrain _locale with a requirements regex.
• Template override path is exact. templates/bundles/AuthKitBundle/ — case-sensitive on Linux CI. A near-miss path falls back to the vendor template with no error.
• Clear cache after config edits. php bin/console cache:clear and then debug:router and debug:container --parameter=<bundle params> to confirm your profile actually compiled.
• Firewall bleed with multiple profiles. If two profiles share a path prefix, sessions can cross. Give each profile a distinct pattern and explicit access_control entries.
• Magic-login token hygiene. Enforce expiry, single-use, and POST consumption. Log token issuance but never log the token itself.
• Dev mailer trap. In dev, MAILER_DSN=null:// swallows reset and magic-login mail. Either use Mailpit or inspect the Profiler's mail panel — otherwise "the email never arrived" is a config issue, not a bug.
• Maturity caveat. 1 star and 0 dependents means you're an early adopter. Pin the version in composer.json, read the source of the flows you depend on, and write a functional test (WebTestCase) for login → register → reset before you ship. Upstream BC breaks are plausible; your tests are the safety net.
• Extension points to prefer: config keys, events/listeners, Twig block overrides, and service decoration. Avoid subclassing bundle controllers or copying their internals into your app — that's the shortest path to pain on upgrade.
• Compat target. The repo targets PHP 8.2+ and Symfony 7.4/8.x with modern strict-typed, final-class code. If you're on older PHP or Symfony 6.x, verify support before committing.