Ory Hydra Bundle Laravel Package

Getting Started

This is the first tagged release (v1.0.0) of scottbass3/OryHydraBundle, and the only artifact published with it is a changelog link — there are no migration notes, no feature list, and no prior assessment to diff against. Treat the release itself as "the package now exists as a stable, installable version" rather than as a source of behavioral detail, and read the repository directly before committing to it.

Before you composer require anything:

1. Check the name. The Bundle suffix and the scottbass3 vendor namespace strongly suggest a Symfony bundle, not a Laravel package. Laravel consumes Symfony components, but it does not have a bundle system, package auto-discovery for bundles, or a Kernel::registerBundles() equivalent. Open composer.json first and look at the require block: if you see symfony/http-kernel, symfony/dependency-injection, or a Symfony\...\Bundle base class, plan on using the underlying service classes manually rather than "installing" the bundle.
2. Read DependencyInjection/Configuration.php. In a Symfony bundle this is where every configuration key and its default lives. It is the most reliable substitute for missing docs, and it tells you exactly which env vars you'll need to map in config/services.php.
3. Identify the Hydra surface area. Ory Hydra exposes two distinct APIs — a public API for OAuth2 flows (authorize, token, userinfo, revoke) and an admin API (client CRUD, consent/logout session management, token introspection). Know which one each service in the package talks to, because they usually run on different ports and have different auth requirements.

Minimal path to first use case:

• Publish or hand-write a config file mapping: Hydra public URL, admin URL, and whatever credentials the admin API expects.
• Point them at a running Hydra instance (docker run the official image, or the quickstart compose file) — you cannot meaningfully evaluate this package against a mocked Hydra.
• Pick the smallest flow that proves the wiring: token introspection is the best first target. It exercises the admin API, requires auth config, and returns a boolean your app can act on immediately.

If step 1 confirms it is Symfony-only, your real first task is writing a Laravel service provider that binds the package's client/service classes into the container with your config — budget for that before anything else.

Implementation Patterns

Adapter service provider. Because there is no Laravel auto-discovery, the standard pattern is a small OryHydraServiceProvider that reads from config/services.php, constructs the package's client object, and registers it as a singleton. Keep the raw package classes out of your application code and inject a thin interface instead — this is your escape hatch if the package stalls at 1.0.0.

HTTP client reuse. If the package wraps Guzzle (likely, given the ecosystem), bind one configured client with base URI, timeouts, and retry middleware, and pass it in. Creating a client per call is the most common cause of slow introspection checks under load.

Introspection as middleware. The day-to-day Laravel integration for Hydra is a route middleware that:

1. Pulls the bearer token from the request.
2. Calls Hydra's introspection endpoint.
3. Checks active, plus scope/aud claims against the route's requirements.
4. Caches the positive result for a few seconds, keyed by a hash of the token.

Cache the decision, never the raw token, and use a TTL shorter than the token's remaining lifetime.

Two distinct roles — don't conflate them. Hydra is an OAuth2/OIDC provider, not a user store. Your app is either (a) the client redirecting users to Hydra's authorize endpoint, or (b) the login/consent provider that Hydra calls back into. Most real deployments need both, and they have different integration points in this package. Decide which one you're building before you start wiring config.

Admin API for provisioning. Client registration and secret rotation belong in an artisan command or a seeded fixture, not in request handlers. Wrap the admin client in a dedicated class used only by console commands.

Testing. Fake at the HTTP boundary (Http::fake() if Laravel's client is used, or Guzzle's MockHandler if you're using the package's own client). Assert on the middleware behavior — active/inactive, expired, wrong scope — rather than on the package's internals, which are the most likely thing to churn in 1.x.

Gotchas and Tips

• The Symfony/Laravel gap is the headline risk. If this is a bundle, there is no composer require-and-go story. No auto-discovery, no publishable config tagged for Laravel, no facade. You are porting, not installing. Verify this first; it changes the effort estimate by an order of magnitude.
• Admin vs public port confusion. Hydra's defaults are 4444 (admin) and 4445 (public). Swapping them produces confusing 404s rather than clean errors. Name your config keys explicitly (hydra.public_url / hydra.admin_url) and assert on them at boot.
• Self-signed TLS in local dev. Hydra's quickstart often runs with a self-signed cert. Guzzle will reject it, and the resulting exception frequently surfaces as a generic connection error. Either trust the cert properly or gate verify => false behind app()->isLocal() — never ship it enabled.
• Config caching will bite you. If the package's constructor reads env() directly, php artisan config:cache silently returns nulls in production. Confirm it reads from config(), and if it doesn't, pass values in explicitly from your service provider.
• No upgrade history to learn from. v1.0.0 is the first tag, so there is no deprecation trail and no signal about how the maintainer handles breaking changes. Pin to ^1.0 at minimum, commit your composer.lock, and check recent commit activity before adopting — a single-tag package with a changelog-only release note is a maintenance-risk signal worth weighing.
• Debug with Hydra's own tooling. hydra CLI and direct curl against the admin API tell you whether a failure is yours or the package's in seconds. Do that before adding logging to the package.
• Version constraint on Symfony components. If you install alongside Laravel, composer may resolve Symfony components to versions that conflict with Laravel's own requirements. If the resolver fights you, that is a real incompatibility, not a temporary hiccup — don't --ignore-platform-reqs your way past it.
• Extension point to look for: a configurable HTTP client and a configurable token/claims decoder. Those two seams let you swap behavior without forking. If neither is exposed, expect to fork for anything non-default.