Cpanel Whm Laravel Package

Getting Started

• Install with composer require and publish the config (php artisan vendor:publish --tag=whm-config). Set WHM_HOST, WHM_USERNAME, and either WHM_TOKEN or WHM_PASSWORD in .env, plus the cache store used for cached reads.
• Look first at config/whm.php (connection, cache, and timeout options) and the Whm facade's method list. The facade is the primary entry point; most day-to-day work is a single call like Whm::listAccounts() or Whm::createAccount(...).
• First use case: read a list of accounts (cached) for a dashboard widget, then create or suspend an account from a queued job. This exercises both the read cache and the mutation path that drops cached reads.

Implementation Patterns

• Reads through the cache. Listing/lookup calls are cached, so repeated dashboard or reporting reads are cheap. Tune the cache TTL and store in config rather than wrapping calls yourself.
• Mutations invalidate reads automatically. Create/suspend/terminate-style calls drop the cached reads afterwards. You generally do not need to call Whm::flushCache() yourself unless something changed outside the package (e.g. another integration, or a manual WHM action).
• Queue long-running mutations. Account operations are slow and benefit from jobs. Because a cache-flush failure no longer aborts the mutation (v0.5.2), completed changes won't be retried just because the cache store hiccupped.
• Explicit flushes. After out-of-band changes, call Whm::flushCache() — but wrap it in try/catch, since the direct call still throws (see Gotchas).
• Testing. Swap the underlying HTTP client / use Laravel's HTTP fakes so tests don't hit WHM. Assert on the request payloads for mutations and seed the cache to test read paths.

Gotchas and Tips

• v0.5.2 behavior change. A cache-store failure while dropping cached reads after a mutation is now reported through the exception handler instead of thrown. This stops queue jobs from retrying a change that already succeeded and repeating side effects. Make sure your exception handler actually reports/logs these — otherwise the failure is silent.
• Whm::flushCache() still throws. If you call it directly (e.g. in a scheduled command or after an out-of-band change), catch the exception; it is not covered by the new swallow-and-report behavior.
• Cache invalidation is best-effort. If the cache store is down, reads may be stale even though the mutation succeeded. Don't treat cache state as a correctness signal; confirm against WHM for critical flows.
• Keep mutations idempotent where possible. Even with the fix, retries can still occur for other reasons (timeouts, 5xx). Design account operations so a repeat is safe or detectable.
• Use a reliable cache store for production. The failure path is now non-fatal, but a flaky store still means stale reads and noisy exception reports — point the package at a store you monitor.
• Extension points: the cache store and TTL are config-driven; reporting goes through Laravel's exception handler, so a custom handler or a monitored reporting channel is the place to surface flush failures.