Voyager Api Auth Laravel Package

Getting Started

• Install the package with Composer and let Laravel discover its service provider. If discovery is disabled, register the provider listed in vendor/joy/voyager-api-auth/composer.json under extra.laravel.providers:

  composer require joy/voyager-api-auth
  php artisan vendor:publish
  php artisan migrate
  php artisan route:list --path=api
  

• Look first at:
  • vendor/joy/voyager-api-auth/src for controllers, routes, middleware, and config keys
  • the package README.md and composer.json for supported Laravel/Voyager versions and auth driver
  • config/ after publishing for guard, token, route-prefix, and model settings
  • routes/api.php or the package route files to confirm actual endpoints
• First use case: authenticate a Voyager admin/user through the API, receive a token, and use that token on protected API routes. Confirm the endpoint names with php artisan route:list, then test:

  POST /api/auth/login
  Content-Type: application/json
  
  {"email":"[email protected]","password":"secret"}
  

  Use the returned token as Authorization: Bearer <token> against the package’s me/profile route or your own protected routes.

Implementation Patterns

• Treat the package as the auth layer, not the whole API. Keep your business endpoints in application routes and protect them with the same guard/token driver the package uses.

  Route::middleware(['api', 'auth:sanctum'])
      ->prefix('v1')
      ->group(function () {
          Route::get('/profile', [ProfileController::class, 'show']);
      });
  

  If the package uses Passport or JWT instead of Sanctum, replace auth:sanctum with the corresponding middleware after checking config/auth.php and the package config.

• Standardize the client workflow around login, current user, refresh/renew if supported, and logout/revoke:

  • Login: validate credentials, return token plus minimal user payload.
  • Authenticated requests: send bearer token; never rely on the Voyager web session for API clients.
  • Logout: revoke the current token where the driver supports it, or invalidate the JWT/session.
  • Password change: revoke existing tokens and force re-login.

• Integrate Voyager roles/permissions rather than inventing a parallel authorization system. Use Voyager’s user model, roles, and permissions to gate API actions through middleware, policies, or gates. Keep the API guard/provider aligned with the Voyager user provider in config/auth.php.

• Customize at the edges first:

  • Publish config and override route prefix, middleware, guard, and model class.
  • Override package controllers by binding your own implementation in a service provider if response shapes or validation need to change.
  • Prefer your own thin AuthController wrapper if the package’s endpoints are too rigid for mobile/SPA requirements.

• Add operational middleware around the package’s login route: throttle, CORS, JSON error handling, and request logging. The package may provide the auth mechanics but not production hardening.

• Test the full flow in feature tests: create a Voyager user, call login, assert token/JSON shape, call a protected route with the token, then assert logout/revocation. For routes that only need authentication, actingAs($user, 'api') is usually faster than generating real tokens.

Gotchas and Tips

• This is a small package: 8 stars, 0 dependents, last release February 2024. Pin the version, audit the source, and avoid assuming long-term maintenance. Check its composer.json constraints against your Laravel, Voyager, PHP, and auth-driver versions before adopting it.
• Token-driver mismatch is the most likely failure mode. Confirm whether the package expects Sanctum, Passport, JWT, or Laravel’s session guard. Missing personal_access_tokens, Passport keys, or JWT secrets typically show up as 500s on login or 401s on protected routes.
• Voyager often uses the web guard and its own user provider. The API package may expect an api guard or a specific user model. Align config/auth.php, config/voyager.php, and the package config; otherwise login succeeds but authenticated requests resolve the wrong user or fail.
• Publish and inspect config/migrations before running them in production. Do not assume publish tags; run php artisan vendor:publish interactively and diff the generated files. Clear caches after installation:

  php artisan config:clear
  php artisan route:clear
  php artisan cache:clear
  

• Watch for route collisions with your existing routes/api.php, Voyager routes, or other auth packages. Use php artisan route:list -v to see middleware, guards, and controller actions.
• CORS and CSRF depend on client type. Bearer-token mobile clients need correct CORS headers; cookie-based SPAs need Sanctum stateful domains, CSRF cookies, and credentials. Do not put the login endpoint behind auth middleware.
• Password reset and email verification flows depend on mail configuration, notifications, and signed URLs. Test them with MAIL_MAILER=log before relying on them in production.
• Add rate limiting to login and registration yourself if the package does not. Also consider disabling public registration for an admin API, enforcing strong passwords, and revoking tokens on password changes.
• Debug from the route and provider outward: route:list, php artisan about, Laravel logs, and temporary logging in published controllers. If the package is too opaque, replace its auth controller with a small application-owned controller using the same guard and token driver.
• Extension points to check: package config, service-provider bindings, route files, middleware aliases, controller classes, user model resolution, events/listeners, and Voyager menu/admin hooks. Prefer overriding these over editing vendor/ files.