Laravel Whmcs Up Laravel Package

Technical Evaluation

Architecture fit

• The package is a Laravel-native bridge to a WHMCS billing/portal instance. v2.0.0 moves it onto Illuminate\Support\Facades\Http, which is the correct architectural direction: outbound calls now inherit Laravel's HTTP middleware, retry hooks, event dispatching, and — critically for us — Http::fake() testability instead of Guzzle mock handlers.
• The CreateSsoToken work is not a feature, it is a survival requirement: AutoAuth was removed in WHMCS 8.1, so any application still depending on getAutoLoginUrl() / redirectAutoLogin() is coupled to a decommissioned upstream API surface. v2.0.0 is the only supported path for a modern WHMCS.
• Implementing rehashPasswordIfRequired() on the UserProvider contract confirms the package integrates at the auth-provider layer, not just as an API wrapper. That means it sits in the login path — high blast radius, and it should be treated as tier-1 infrastructure rather than a convenience library.
• Dropping Lumen is architecturally sound (EOL) but is a hard fork in the road if any service in our estate is still on Lumen.

Integration feasibility

• Feasible for any host app on PHP 8.2+ / Laravel 10+, provided the target WHMCS is 8.1+. The migration guide in the README reduces this to a bounded, enumerable change set: two method renames, one session key default, one URL scheme default, one SSL default, plus env var additions (WHMCS_TIMEOUT).
• The real effort is not the package swap; it is the coordinated platform upgrade (PHP + Laravel + WHMCS) that v2.0.0 implicitly requires.

Technical risk

• Three simultaneous breaking axes. PHP 8.2+, Laravel 10+, and WHMCS 8.1+ must all be true at once. Any one of them being false blocks the upgrade entirely, and each has its own owner, timeline, and test surface.
• Session key default change (user → whmcs_user) is the sneakiest risk. It is a silent behavioural change: users with existing sessions will lose their WHMCS linkage and appear logged out of the portal with no error. Any downstream code reading session('user') directly will break without a stack trace. This needs an explicit transition plan, not a default.
• SSL verification now on by default. Correct for production, but it will immediately break any non-prod, on-prem, or self-signed WHMCS instance. Expect environment-specific failures during rollout that look like "SSO is broken" but are certificate trust issues.
• Deprecation shims emit E_USER_DEPRECATED. Usually benign, but strict error handlers and some observability configurations convert notices to exceptions. Verify handler configuration before shipping the compatibility path.
• Version-matrix claim needs verification. The published compatibility table asserts Laravel 10–13. Laravel 13 is not generally available at time of review; treat that column as a forward-looking claim, not a tested guarantee, and pin to the highest version we can actually run in CI.
• Rollback is essentially unavailable. Because AutoAuth was removed upstream, v1.x cannot be a fallback once WHMCS is on 8.1+. This is a one-way door on the WHMCS axis and should be planned accordingly (see Integration Approach).

Key questions

1. What is the current WHMCS version in each environment, and who owns that upgrade? If WHMCS is already 8.1+, are existing AutoAuth flows already broken in production?
2. Which host applications consume this package, and what is each one's current PHP and Laravel version? Is any of them on Lumen?
3. Does any code read the user session key directly, or persist it, rather than going through the package?
4. Are there non-production WHMCS instances with self-signed or internal-CA certificates? Do we need a sanctioned opt-out, and who approves it?
5. What should WHMCS_TIMEOUT be per environment, and what is the user-facing fallback when the WHMCS call times out on the login path?
6. Do we need sbGetClients() ordering/filtering ($orderby, $status, WHMCS 8.2+)? If so, that raises the minimum WHMCS version from 8.1 to 8.2.
7. Is there a stated support window / release cadence from the maintainer, or are we tracking an individual maintainer's side project?

Integration Approach

Stack fit

• Clean fit for a standard Laravel app: Composer install, publishable config, env-driven base URL and timeout, and a UserProvider implementation that plugs into the existing auth guards. No new infrastructure, no sidecar, no message broker — it is an HTTP client plus an auth adapter.
• The move to the Http facade means our existing outbound-HTTP observability (logging middleware, request IDs, Http::fake() in tests) applies with zero rework. That is a meaningful reduction in integration cost versus v1.x's raw Guzzle.

Migration path

• Treat this as a platform upgrade programme with the package as one workstream, not as a dependency bump.
• Concrete code deltas: getAutoLoginUrl() → getSsoUrl(), redirectAutoLogin() → redirectSso(), WHMCS_URL must be https://, session key must be set explicitly to the legacy value (user) during transition, and WHMCS_TIMEOUT must be set per environment rather than relying on a library default.
• Prefer two releases over one: release 1 pins the session key to user and adopts the deprecated methods' replacements while keeping the old key readable; release 2 flips to whmcs_user after session TTLs have elapsed. Flipping everything at once produces a support-ticket spike that looks like an outage.
• Keep the deprecation shims in place for one release cycle. They are free observability into any call site we missed.

Compatibility

• PHP 8.2+ / Laravel 10+ / WHMCS 8.1+ is the supported box. Build the CI matrix to the intersections we actually run, not to the full published table — Laravel 13 should be added only when it is GA and we have a reason to adopt it.
• Lumen is out. If any service is on Lumen, that service either stays on v1.x (and is therefore locked out of WHMCS 8.1+) or gets ported. Get that decision made early because it is the longest-lead item.
• sbGetClients() with $orderby / $status requires WHMCS 8.2+. Decide now whether we need it; if not, we keep optionality at 8.1 and reduce coupling.

Sequencing

1. Inventory — enumerate every consumer of the package, its PHP/Laravel version, and its WHMCS version; grep for getAutoLoginUrl, redirectAutoLogin, and direct reads of the user session key.
2. Verify upstream — confirm WHMCS ≥ 8.1 everywhere; confirm TLS trust in every environment; confirm whether AutoAuth flows are already dead in production (if so, this is an incident, not a roadmap item).
3. Upgrade the platforms first — PHP to 8.2+, Laravel to 10+, on each consumer, with the package still on v1.x where possible. Separating platform churn from package churn is the single biggest de-risking lever here.
4. Adopt v2.0.0 in staging — SSL verification on, timeout set, session key explicitly pinned to user, deprecation logging enabled so any missed call site surfaces.
5. Cut over SSO — validate getSsoUrl() / createSsoToken() end-to-end against the real WHMCS instance, including token expiry and re-entry. Add Http::fake()-based contract tests so future releases do not silently change request shape.
6. Flip the session key — after session TTLs elapse, in a low-traffic window, with a rollback config toggle that restores the old key name.
7. Remove the shims — one release later, delete deprecated call sites and drop the compatibility logging.

Operational Impact

Maintenance

• Low steady-state footprint: no schema, no migrations, no background workers, no cache to warm. The surface is an HTTP client, a config file, and an auth provider binding.
• Maintenance risk concentrates in the version-matrix treadmill. With a supported range of PHP 8.2+, Laravel 10–13, and WHMCS 8.1+, the package must track three independent upstream lifecycles. Budget a recurring review per Laravel major and per WHMCS minor, and confirm the maintainer's release latency before we depend on it for a login path.
• The v2.0.0 changelog is substantial and well-structured (explicit breaking-change section, compatibility table, migration guide pointer). That is a positive health signal, but it is one data point — check the cadence between v1.1.0 and v2.0.0 and whether issues get triaged.

Support

• First-line support needs a short runbook covering the failure signatures that all look identical to end users ("can't get into billing"): TLS trust failure, timeout, expired SSO token, session key mismatch, and WHMCS-side auth rejection. Without that, every one of these becomes an escalation to engineering.
• E_USER_DEPRECATED output gives us a cheap "who is still calling the old methods" report — route it somewhere queryable rather than letting it scroll past.

Scaling

• Scaling characteristics follow WHMCS, not Laravel. Every SSO redirect and every sbGetClients() call is a synchronous dependency on the WHMCS instance. Horizontal scaling of the Laravel tier adds concurrent load to a system we do not control.
• Configure WHMCS_TIMEOUT deliberately and set it low on the interactive login path. A generous default turns a WHMCS slowdown into a hung login page rather than a fast, understandable error.
• sbGetClients() with new $orderby / $status parameters may allow server-side narrowing, which is a scaling win if we currently pull and filter client-side. Confirm before assuming.

Failure modes

• WHMCS unreachable / slow — login path degrades. Requires an explicit user-facing error and a decision on whether password-only login should still succeed.
• TLS verification failure — hard failure on every call, environment-wide, with a generic error. Most likely during initial rollout against non-prod instances.
• Session key mismatch — silent, no exception: users appear logged out of the WHMCS linkage. Highest diagnostic cost, lowest signal.
• Expired or single-use SSO token — user lands on WHMCS with an error page; looks like an auth bug but is usually a latency or redirect-chain issue.
• rehashPasswordIfRequired() regression — sits in the credential path; a defect here locks users out rather than degrading a feature. Needs explicit regression coverage alongside the SSO tests.
• Deprecation-as-exception — misconfigured error handlers turn a warning into a 500 on the login route. Cheap to prevent, expensive to diagnose in production.

Ramp-up

• Engineer ramp-up is modest: one README read plus the migration guide covers the API. Half a day to a day for someone already familiar with Laravel auth.
• Organisational ramp-up is the real cost: this release forces a coordinated upgrade across PHP, Laravel, and WHMCS with no rollback on the WHMCS axis. Sequence it as a programme with named owners per axis, and gate the final session-key flip behind a config toggle so that the only irreversible step is also the only one we can turn off in seconds.