Auth Http Laravel Package

Getting Started

1. Install the package via Composer (note: last release was in 2020; verify compatibility with your Spiral framework version):

   composer require spiral/auth-http
   

2. Register middleware in your HTTP kernel (config/http.php or app.php), typically in the middlewares section:

   Spiral\AuthHttp\Middleware\Authenticate::class,
   

   or per-route using route groups.

3. Configure guards in config/auth.php (or equivalent), mapping guard names to transport strategies (e.g., header, cookie, query).
   Example:

   'guards' => [
       'api' => [
           'transport' => 'header',
           'header'    => 'Authorization',
           'prefix'    => 'Bearer',
       ],
   ],
   

4. First use case: Protect a route/controller with authentication:

   $router->get('/secure', [SecureController::class, 'index'])
       ->middleware(Authenticate::class . ':api');
   

Implementation Patterns

• Middleware-based guards: Use Authenticate middleware with guard configuration to enforce auth per-route. Chain with Authorize (if available in related packages) for RBAC/ABAC checks.

• Transport abstraction: Leverage built-in transport strategies (header, cookie, query) or write a custom one implementing Spiral\AuthHttp\Transport\TransportInterface. Example:

  class CustomTokenTransport implements TransportInterface
  {
      public function extract(Request $request): ?TokenInterface
      {
          return $request->getHeaderLine('X-Custom-Token') 
              ? new BearerToken($request->getHeaderLine('X-Custom-Token'))
              : null;
      }
  }
  

• Guard composition: Define guards with multiple fallback transports (e.g., fallback to cookie if header missing):

  'fallback' => [
      'transport' => 'cookie',
      'name'      => 'auth_token',
  ]
  

• Response consistency: Utilize the framework’s built-in UnauthorizedHttpException and ForbiddenHttpException thrown by the middleware—no manual 401/403 handling needed.

• Integration with domain auth: Inject your application’s auth service (e.g., UserProvider, TokenValidator) into guards via DI. Let the middleware only coordinate—your domain validates credentials.

Gotchas and Tips

• Legacy status warning: This package is read-only and last updated in 2020. Spiral 3+ may use spiral/auth + middleware split differently. Verify if spiral/auth suffices or if auth-http adds non-duplicate value.

• Token parsing quirks: If using header transport with prefix (e.g., Bearer), the prefix must match exactly (case-sensitive). A mismatch causes silent auth failures—log or debug with custom middleware wrapping.

• Middleware order matters: Place Authenticate before action-specific logic (e.g., validation, controller), but after session/middleware that populates request data.

• Customizing responses: Override default 401/403 handlers by extending Authenticate middleware and overriding onUnauthorized()/onForbidden(), or binding custom handlers in config/auth.php.

• Testing tip: Mock the GuardInterface and TransportInterface in unit tests. For feature tests, inject AuthorizationCheckerInterface (if present) to assert access decisions directly.

• Extensibility: The package exposes hooks like GuardInterface::authenticate(TokenInterface $token)—implement custom guards (e.g., JWT, API key, session) by conforming to this interface and wiring them via config.