Client Laravel Package

Technical Evaluation

userbase/client is a thin, framework-agnostic PHP SDK for LinkORB's UserBase identity service. For a Laravel shop it is best understood not as a Laravel package but as a transport-layer dependency: it carries no service provider, no facade, no config publishing, and no Eloquent or guard integration. That is actually the right shape for a client library, but it means all the Laravel-shaped work is ours.

Architecture fit. The package sits at the edge of the domain — it should be reached only through an application-owned adapter (e.g. App\Identity\UserBaseGateway bound to an interface), never called directly from controllers or middleware. If we treat the SDK as an implementation detail behind our own contract, the architecture stays clean and the swap cost if we ever leave UserBase is a single adapter rewrite. If we let it leak into auth guards and middleware, we inherit lock-in to a five-star dependency.

Integration feasibility. Composer-installable, MIT-licensed, PSR-4 autoloaded, and presumptively a straightforward HTTP wrapper (Guzzle or PSR-18). The integration effort is therefore small and predictable: a service provider, a config file driven by env vars, and a binding. The unknown is documentation depth — the repository is sparse on the signals we normally use to size an integration (no dependents, minimal stars), so the honest estimate carries a discovery spike rather than a confident number.

Technical risk. Three concerns dominate. First, bus factor and stewardship: this is a vendor-published client for a vendor-operated service, with effectively no community footprint (5 stars, 0 dependents). We are betting on LinkORB maintaining it, or on our willingness to fork. Second, version and release hygiene: a release dated 2026-09-07 alongside a very low adoption score warrants a check on whether that reflects genuine cadence or metadata drift; a 0.x version string would mean no compatibility promise. Third, runtime coupling: every call is a network hop to a service we do not operate, which turns an external outage into a login outage unless we design for it.

Key questions for the discovery spike. Does it target PSR-18/PSR-17, or pin a specific Guzzle major? Is it synchronous only, and does it expose timeouts and retry hooks? How are credentials and token refresh handled — does it cache tokens or re-authenticate per call? What is the error model (typed exceptions vs. generic HTTP errors)? Is the UserBase service self-hostable or SaaS-only, and what is its SLA? What is the test coverage, and is CI configured? Does it declare a PHP version floor compatible with our target runtime? Is there a changelog and a documented deprecation policy?

Integration Approach

Stack fit. Compatible in principle with any modern Laravel (10/11/12) and PHP 8.1+ codebase, since it imposes no framework requirements. It does not participate in Laravel's package discovery, so nothing registers itself — we own the wiring. The natural home is a small first-party package (packages/identity-userbase) or an app/Services/Identity module, with config in config/userbase.php and secrets in env/secret manager.

Migration path. Two entry scenarios. If we are greenfielding identity onto UserBase, the path is direct: adapter, provider, feature-flagged rollout, then flip the auth surface. If we are migrating off Laravel's native guards or another IdP, the safer path is a strangler pattern — run the SDK alongside existing auth, dual-write or shadow-authenticate a cohort, and cut over per route group rather than per application. The adapter contract should be defined before the SDK is installed, so the contract is shaped by our domain rather than by the client's method signatures.

Compatibility. Pin the SDK version explicitly and treat upgrades as reviewed changes, not composer update drift. Verify its HTTP client constraint against the Guzzle/PSR-18 version Laravel already resolves, to avoid a dependency conflict that forces a framework downgrade. Check PHP floor and any extension requirements. Confirm the release tag actually exists on Packagist and is not a pre-release.

Sequencing. (1) Spike: install, authenticate against a sandbox, exercise error paths — half a day to two days. (2) Contract: define the adapter interface and DTOs; this is the durable artifact. (3) Adapter implementation with explicit timeouts, retries, and typed exceptions. (4) Test harness — contract tests against a recorded/mocked UserBase, plus one live smoke test in CI. (5) Pilot behind a flag on a low-risk surface. (6) Broaden to full auth, with the legacy path retained as fallback until the pilot cohort is clean.

Operational Impact

Maintenance. The client itself is small and should be cheap to keep current; the real maintenance load is the adapter and the contract tests we write. Budget for the possibility of forking — a thin HTTP client is forkable in days, which materially caps the downside, but only if the adapter boundary exists first. Assign an explicit owner; an unowned identity dependency is an on-call liability.

Support. Community support is effectively nil at this adoption level. Escalation is to LinkORB directly, and our leverage as a small consumer is limited. This argues for keeping a fork-ready posture and documenting the fork procedure rather than discovering it during an incident.

Scaling. Synchronous per-request identity calls will not scale past modest traffic. Any auth check on the hot path needs response caching (short TTL, keyed by token/session), connection reuse, and a circuit breaker. Set connect and read timeouts explicitly — defaults on HTTP clients are frequently too generous for a login path. If UserBase publishes rate limits, model them before launch, not after the first 429 cascade.

Failure modes. Remote service unavailability or latency propagating into login failures; token expiry handled mid-request with no refresh; silent swallowing of errors that turns a 500 into an "invalid credentials" message and misroutes support tickets; schema drift in UserBase responses breaking untyped deserialization; and dependency resolution conflicts blocking unrelated framework upgrades. Each maps to a concrete mitigation: breaker plus cached fallback for reads, typed exceptions, contract tests on recorded fixtures, and a pinned version.

Ramp-up. Low. The API surface of a client like this is small — a competent Laravel developer is productive in under a day once the adapter and a sandbox credential exist. The hidden cost is domain ramp-up on UserBase's model (users, groups, permissions, tenancy), which lives in the service, not the client, and is where onboarding time actually goes. Plan for a short internal write-up of the UserBase domain alongside the adapter, or the knowledge will stay with one engineer.