Lumen Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require stormpath/lumen
   

   Add the service provider to bootstrap/app.php:

   $app->register('Stormpath\Lumen\StormpathServiceProvider');
   

2. Configure Stormpath Ensure .env contains:

   STORMPATH_CLIENT_APIKEY_ID=your_api_key_id
   STORMPATH_CLIENT_APIKEY_SECRET=your_api_key_secret
   STORMPATH_CLIENT_APPLICATION_HREF=https://api.stormpath.com/v1/applications/your_app_href
   

3. First Use Case: Auth Middleware Protect a route with Stormpath’s built-in middleware:

   $app->get('/protected', ['middleware' => 'stormpath.auth', function () {
       return response()->json(['message' => 'Authenticated!']);
   }]);
   

4. Verify Setup Test with curl or Postman:

   curl -X GET http://your-app.test/protected -H "Authorization: Stormpath <token>"
   

Implementation Patterns

Core Workflows

1. Authentication Flow

   • Use stormpath.auth middleware for route protection.
   • For custom logic, inject Stormpath facade:

     use Stormpath\Lumen\Facades\Stormpath;
     $user = Stormpath::authenticate($request);
     

2. User Management

   • Create User:

     $user = Stormpath::createUser([
         'email' => 'user@example.com',
         'password' => 'secure123',
     ]);
     

   • Fetch User:

     $user = Stormpath::getUserByEmail('user@example.com');
     

3. Session Handling

   • Generate tokens:

     $token = Stormpath::generateToken($user);
     

   • Validate tokens:

     if (Stormpath::validateToken($token)) {
         $user = Stormpath::getUserFromToken($token);
     }
     

4. Integration with Lumen’s Router

   • Dynamic route protection:

     $app->group(['middleware' => 'stormpath.auth'], function ($app) {
         $app->get('/dashboard', 'DashboardController@index');
     });
     

Advanced Patterns

• Custom Claims: Extend user data via Stormpath’s Custom Data API.
• Webhooks: Use Stormpath’s Event Hooks for real-time user lifecycle events (e.g., password changes).
• Multi-Tenancy: Leverage Stormpath’s Accounts to manage separate user bases per tenant.

Gotchas and Tips

Common Pitfalls

1. Environment Variables

   • Issue: Missing or misconfigured .env variables cause silent failures.
   • Fix: Validate with:

     if (!config('stormpath.client.apikey_id')) {
         throw new \RuntimeException('Stormpath API key not configured.');
     }
     

2. Token Expiry

   • Issue: Tokens expire after 24 hours (default). Use refresh tokens for long-lived sessions.
   • Fix: Implement token refresh logic:

     $refreshedToken = Stormpath::refreshToken($oldToken);
     

3. CORS Headers

   • Issue: Stormpath API responses may lack Access-Control-Allow-Origin headers if not configured.
   • Fix: Add CORS middleware to Lumen:

     $app->middleware(['cors']);
     

4. Rate Limiting

   • Issue: Stormpath’s free tier has rate limits.
   • Fix: Cache user data locally and implement fallback logic.

Debugging Tips

• Enable Stormpath Logging: Add to .env:

  STORMPATH_CLIENT_LOG_LEVEL=debug
  

• Check Stormpath Console: Monitor API calls and errors in the Stormpath Dashboard.
• Test with Postman: Use the Stormpath API Explorer to validate endpoints.

Extension Points

1. Custom Auth Logic Override the default Authenticate middleware:

   $app->middleware('stormpath.auth', function ($request, $next) {
       // Custom validation logic
       return $next($request);
   });
   

2. Stormpath Client Configuration Extend the client in bootstrap/app.php:

   $app->singleton('stormpath.client', function ($app) {
       $client = new \Stormpath\Client();
       $client->setHttpClient(new \GuzzleHttp\Client([
           'timeout' => 30,
       ]));
       return $client;
   });
   

3. Event Listeners Subscribe to Stormpath events (e.g., user.created):

   Stormpath::on('user.created', function ($event) {
       // Send welcome email
   });
   

Legacy Notes

• Deprecated: This package is archived (last release: 2016). For new projects, consider:
  • Stormpath PHP SDK (active).
  • Modern alternatives like Laravel Sanctum or Passport.
• Migration Path: Export Stormpath users to a local database using the Stormpath Export API.