Stormpath Bundle Laravel Package

Getting Started

Before writing a single line of integration code, confirm that Stormpath itself is still viable for you. Stormpath's API was decommissioned after the Okta acquisition (2017), so any bundle that talks to api.stormpath.com will fail at the HTTP layer regardless of configuration. For most teams the "first step" is therefore an evaluation of whether this belongs in a greenfield project at all — it almost certainly does not, and this is a migration/archaeology exercise rather than a build.

If you are maintaining a legacy Symfony application that already depends on it:

1. Install with composer require redeye/stormpath-bundle (expect it to target Symfony 2.x/3.x — no Flex recipe, no autoconfiguration).
2. Register the bundle manually in app/AppKernel.php: new Redeye\StormpathBundle\StormpathBundle().
3. Open DependencyInjection/Configuration.php first — it is the only reliable documentation for the config tree (api_key, api_secret, application_href, cache settings). The README is thin.
4. Add a stormpath: block to config.yml (credentials ideally sourced from parameters.yml/env vars).
5. First use case: fetch the Stormpath\Resource\Application service, create an account, and request an OAuth token — this validates credentials and the application_href in one shot.

If you have any choice in the matter, start instead with Symfony's native security component (plus lexik/jwt-authentication-bundle or Auth0/Okta SDKs) — see the migration note in Gotchas.

Implementation Patterns

Service injection over static clients. The bundle's main value is wiring the Stormpath SDK into the container. Inject Stormpath\Resource\Application (or the bundle's service alias) into your services/controllers rather than calling Stormpath\Client::getInstance() by hand — this keeps credentials in one place and makes testing possible.

Registration → local identity mapping. On signup, call $application->createAccount(...) (or ->createAccount($account) with a Stormpath\Resource\Account built from a Stormpath\Resource\Account-shaped array), then persist the returned href on your own User entity as stormpath_href. That href is the durable foreign key — never key off email, which is mutable.

Login flow. Authenticate against the application with the password grant ($application->authenticate($username, $password) in older SDK versions), receive the access/refresh token pair, and mint a Symfony session/token from it. If the bundle ships a guard/authenticator or user provider, wire it in security.yml; otherwise implement a custom UserProviderInterface that maps Stormpath accounts to local users by href.

Source-of-truth split. Treat Stormpath as the authority for credentials and group membership, and your local DB as the authority for application data. Keep the mapping table small: local_user_id, stormpath_href, last-synced timestamp.

Role mapping. Map Stormpath groups onto Symfony roles inside getRoles() of your provider rather than scattering checks through controllers — one mapping function, one place to change.

Environment hygiene. Keep api_key/api_secret in environment variables or an untracked parameters.yml; the SDK also honours STORMPATH_API_KEY_ID/STORMPATH_API_KEY_SECRET, which you can plumb through if the bundle's config doesn't forward them.

Multi-tenant. If you run several Stormpath applications, define one service per application_href (service override or child definition) rather than flipping config at runtime.

Gotchas and Tips

• The API is gone. This is the overriding issue: Stormpath's service was shut down, so every call fails. Stars = 5, dependents = 0, score ≈ 0.125 — that matches a dead dependency. Don't build new work on it.
• Symfony version drift. The bundle predates Symfony 4/5 autoconfiguration and PHP 8. Expect manual service registration, deprecated APIs, and possible fatal errors under modern PHP. If you must keep it, pin PHP/Symfony versions and vendor the code.
• application_href confusion. It must be the full REST href (e.g. https://api.stormpath.com/v1/applications/<id>), not the application name. Mismatches surface as confusing 404s.
• Caching traps. The SDK caches resources; after account/group changes you can read stale data. Disable the Stormpath cache (stormpath.cache.enabled or equivalent in the config tree) while debugging, then re-enable.
• Silent timeouts. Default SDK timeouts are long. Call out explicit timeouts in config and wrap calls in try/catch — a dead endpoint often hangs rather than failing fast, which looks like an app freeze.
• Extension point. To customise HTTP behaviour (retry, proxy, logging), override the Stormpath\Client/Application service via a compiler pass or a service alias in services.yml; the bundle doesn't expose a first-class hook.
• Docs are minimal. Read DependencyInjection/Configuration.php and the service XML/YAML definitions as the real reference; the README is incomplete.
• Migration path. The realistic recommendation is to replace this bundle: Okta (Stormpath's acquirer) offered a migration guide, and Auth0 or Symfony's native security + JWT bundle are strong modern alternatives. Budget for a data migration of stormpath_href → new provider IDs rather than a drop-in swap.