Cachent Laravel Package

Getting Started

Before anything else, verify what you are installing. The package's one-line description ("a secure, open source torrent cache") does not match the detailed feature list (a fluent Laravel client for the Cachet status page API: components, incidents, metrics, schedules, facade + DI, API token/basic auth). Check composer.json and the src/ tree after install and confirm the namespace is OwenVoke\Cachent. Everything below assumes the Cachet-client interpretation, which is the one the documented surface area supports.

1. Install at the patched version.

   composer require owenvoke/cachent:^2.2.1
   composer dump-autoload -o
   

   Do not pin 2.2.0 — v2.2.1 exists solely to fix a file that was missing from that distribution.

2. Publish the config and read it end to end.

   php artisan vendor:publish --provider="OwenVoke\Cachent\CachentServiceProvider"
   

   Run it interactively the first time so you can see the real tag names; then note the actual filenames and keys in config/. The keys you care about are the base URL of your Cachet instance, the credential (API token preferred, basic auth as fallback), and any timeout/retry setting.

3. Keep credentials in .env only. Whatever the published keys are named, mirror them into env vars and reference them via env() in the config file. Never commit a token; a status page token is a write credential over your public incident history.

4. Confirm the binding before writing application code. Resolve the client from the container in php artisan tinker and hit a read-only endpoint (list components). This proves URL, auth, TLS, and network egress from your environment in one step, before you build any logic on top.

Where to look first: the published config, then the service provider (to see how the client is bound and whether it is a singleton), then the resource classes for components/incidents — those tell you the exact method names and payload shapes, which are the only API you actually need.

First use case: a deploy- or health-check-driven incident. A scheduled command (or a failed-job handler) opens an incident on your Cachet page when a health probe fails, and resolves it once the probe passes. This is the highest-value, lowest-risk integration: it is read-mostly, it fails safely, and it is immediately visible to stakeholders.

Implementation Patterns

• Never call the facade from controllers. Write one thin StatusPage wrapper class that takes the client via constructor injection, exposes domain methods (openIncident(), resolveIncident(), pushMetric()), and swallows/translates exceptions. Controllers, jobs, and commands all depend on your wrapper, not the package. This is your seam for testing and for swapping the package out later.
• Make it toggleable. A STATUS_PAGE_ENABLED flag checked at the top of the wrapper, defaulting to false locally and in CI. You do not want a developer's test run creating incidents on the production status page.
• Model the incident lifecycle explicitly. Cachet incidents move through statuses (investigating → identified → watching → fixed). Store the returned incident ID (a small settings table or a cache key like status:incident:{service}) so later updates target the same incident instead of opening a new one.
• Deduplicate aggressive monitors. A health check running every minute will open sixty incidents during an outage. Guard the open path with Cache::lock() or a "current incident" record check; only open when there is no open incident for that component.
• Map your domain onto theirs with enums. Keep a config or enum map from your internal severity/health states to Cachet component statuses and incident statuses. When the mapping lives in one place, a mis-set status is a one-line fix rather than a grep across the codebase.
• Queue all writes. Put incident creation/updates and metric pushes on a queue job with tries/backoff. A slow or unreachable status page must never add latency to a deploy or a request. Use ShouldBeUnique on the job to collapse duplicate pushes.
• Fail open, log loudly. Wrap every call in try/catch (\Throwable), log with context (component, incident ID, response status), and return a null/false result. The status page is a reporting channel; it is never allowed to be the reason a deploy fails.
• Metrics as a scheduled push. Have a scheduled command sample your metrics (queue depth, failed job count, error rate) and push a point with an explicit timestamp. Keep timestamps UTC and monotonically increasing — out-of-order points render badly on the graph.
• Testing. In phpunit.xml set the enabled flag to false and bind a fake implementation of your wrapper in the container. For the wrapper's own tests, mock the HTTP layer (Laravel's Http::fake() if the client is built on the HTTP client; otherwise the underlying Guzzle mock handler) and assert the outgoing payload, not just that a method was called.
• Reconciliation command. A nightly status:sync command that pushes your real component states is cheap insurance against drift caused by manual edits in the Cachet UI.

Gotchas and Tips

• Package identity is ambiguous. The one-liner says torrent cache; the docs say Cachet client. Read the source before designing around it, and check composer.json for the supported PHP/Laravel matrix — don't assume your version is in range.
• The 2.2.1 "missing file" fix is a packaging bug, not a runtime one. If the fault persists after upgrading, the cause is almost always a stale artifact: composer clear-cache, delete vendor/owenvoke/cachent, reinstall, composer dump-autoload -o, php artisan optimize:clear. Also confirm your deploy pipeline isn't caching the vendor directory or skipping package discovery.
• Stale published config. A bootstrap/cache/config.php generated before the upgrade will mask changed defaults. Always php artisan optimize:clear before comparing behaviour before/after. And do not blanket vendor:publish --force in production — diff the config, merge deliberately, then config:cache.
• Don't let a status page outage cascade. Set an explicit short timeout on the HTTP client and treat timeouts as a no-op, not an exception that bubbles into the deploy path.
• Duplicate incidents from retries. A queued job that times out after the API actually succeeded will retry and open a second incident. Make the write path idempotent via your stored incident ID, and check state before creating.
• Token scope and rotation. Use a dedicated token per application, not a shared admin token. Rotating one app's token should not require touching the others, and should never require a code change — env var only.
• Long-lived workers (Octane, Horizon). If the service provider registers the client as a singleton holding config, be cautious: after a config change or token rotation, workers keep the old value until restarted. Resolve per-request or restart workers on deploy.
• Timezone and display drift. Send UTC timestamps explicitly rather than relying on server defaults, and format user-facing incident text in your app's locale before sending.
• Never edit vendor/. If you need different key/URL/status mapping behaviour, extend your own wrapper or rebind an implementation in a service provider. Anything patched in vendor/ disappears on the next composer update — that class of mistake is exactly what a "missing file" patch release exposes in a dependency.
• Debugging toolkit. php artisan about and php artisan tinker for a live client check, Http::fake()/mock handler for payload inspection, php artisan config:show after publishing, and structured logging of request/response on every outbound call during rollout. Log the incident ID on both create and update so you can trace a lifecycle end to end.
• Exit plan. The surface area is small: if maintenance stalls, your wrapper class is the only thing your app depends on, and reimplementing the handful of endpoints you use against the Cachet REST API is a contained piece of work. Keeping that boundary clean is the whole reason to have the wrapper.