Laravel Dashboard Cloudflare Stats Tile Laravel Package

Getting Started

This package is a leaf adapter for spatie/laravel-dashboard — it renders one tile and does nothing on its own. Confirm the host framework is installed, its route renders, and config/dashboard.php exists before touching this package. If you are not already running Laravel Dashboard, the scope decision is wrong and the integration is wrong by extension.

Minimal path, in order:

1. Install and see what you got. composer require owenvoke/laravel-dashboard-cloudflare-stats-tile, then read the package's composer.json — check the illuminate/support, livewire/livewire, and spatie/laravel-dashboard constraints against your actual versions. For a package with this little adoption this is the first real risk check, not the last.
2. Publish assets. php artisan vendor:publish --list to discover the tags, then publish the config (and view if you intend to override the Blade template). The config file is the surface you will actually live in.
3. Provision a scoped token. In Cloudflare, create an API token with Zone → Analytics → Read on a single zone. Grab the zone ID (not the account ID — they are different and the error for mixing them is not obvious). Put both in .env under whatever keys the config file references.
4. Register the tile in config/dashboard.php alongside your existing tiles:

'tiles' => [
    'cloudflare-stats' => [
        'component' => 'cloudflare-stats-tile',
        'position' => ['x' => 0, 'y' => 0, 'width' => 4, 'height' => 4],
        'refreshIntervalInSeconds' => 60,
    ],
],

5. Schedule the fetch. The tile renders from cache; a scheduled command is what populates it. Find the command name with php artisan list dashboard (Spatie's convention is dashboard:fetch-*) and add it to app/Console/Kernel.php:

$schedule->command('dashboard:fetch-cloudflare-stats')
    ->everyFiveMinutes()
    ->withoutOverlapping();

6. First use case: point it at a non-production zone, run the fetch command manually once, and confirm numbers land and that a second manual run updates them. That single loop — fetch → cache → render — is the whole system. If you can observe it end to end, you understand the package.

Verify the scheduler entry with php artisan schedule:list before you call the integration done.

Implementation Patterns

Treat the fetch command as the unit of work and the tile as a read view. Everything that matters happens in the scheduler: it calls the Cloudflare API, normalises the response, and writes into the cache under a key the tile reads. The Livewire component does not talk to Cloudflare — it reads the cache on its refresh interval. This separation is what makes the tile cheap and what makes its failure modes quiet, which is why the next patterns matter.

Wire the fetch cadence to your tolerance for staleness, not to the refresh interval. Five to fifteen minutes is the sane band for a glanceable ops tile. Set withoutOverlapping() so a slow or hanging API call cannot stack runs and eat into Cloudflare rate limits.

Configure through env, never through the config file directly. The config file should reference env('CLOUDFLARE_STATS_TILE_API_TOKEN') and the zone ID. This keeps secrets in your standard secret path and lets you point staging at a different zone without a code change. If the config file hardcodes them, that is a fork-worthy fix, not a workaround.

Multi-zone means multiple tile instances. The tile targets one zone per instance. If you need several zones, add several entries in config/dashboard.php with distinct keys and positions, and confirm the package's config supports per-instance zone overrides — otherwise plan a small subclass rather than editing the package in place. Never modify vendor/.

Develop with the scheduler off. In local dev, disable the scheduled command and seed the cache manually, or run the fetch command by hand when you need fresh numbers. Chasing Livewire polling behaviour against a real Cloudflare zone is a slow feedback loop and burns token quota for no reason.

Test the command, not the view. Use Http::fake() around the fetch command, assert the cache key is populated with the expected shape, and assert that a 403 from Cloudflare results in whatever behaviour you actually want (logged, thrown, or left-stale). That third assertion is the test that matters most in production.

Override the Blade view to surface cache age. Publish the view and add a "last updated" timestamp read from the cache entry's write time. This is the single highest-value modification you can make to this package — it turns a silent-staleness failure mode into a visible one for the person looking at the dashboard.

Position it next to your other site-health tiles — the value is context, not the Cloudflare numbers in isolation. A tile showing requests and bandwidth beside uptime and error-rate tiles shortens triage; the same tile in a random grid slot is decoration.

Gotchas and Tips

Refresh interval is not fetch interval. refreshIntervalInSeconds controls how often Livewire re-reads the cache. If the scheduler has stopped, a short refresh interval just re-renders stale numbers more frequently. Every "the dashboard is broken / the numbers look flat" incident traces back to this confusion.

Silent staleness is the realistic failure mode, not a crash. An expired or revoked token will typically leave the tile empty or serving the last cached value rather than throwing a visible error. Alert on the fetch command's exit status — a failed command is invisible on the dashboard otherwise, and a suspiciously flat chart is not a monitoring strategy.

Check which Cloudflare API the package targets before you commit. Cloudflare's analytics surface moved to GraphQL; legacy REST analytics endpoints are a dead end. Read the HTTP calls in the package source, not the README. If it is still on REST, that is your fork cost and it changes the adoption decision.

A 403 is not always a 403. Insufficient token scope and a wrong zone ID both often surface as an empty tile rather than an explicit error. When debugging, curl the Cloudflare API with your token and zone ID directly — this distinguishes credentials, scoping, and zone-context problems in one step and takes a minute.

Pin the package and the dashboard framework together. Update one without the other and you get a Livewire or dashboard-version incompatibility that looks like a broken tile. If the tile caps at an older Laravel than you run, the usual fix is a widened illuminate/support constraint plus a test pass — cheap, but do it on a branch and confirm the transitive Cloudflare client still behaves.

Cache backend matters if the scheduler and the web nodes are different hosts. A file cache means the scheduler writes to one node's disk and the tile on another node reads nothing. Use a shared store (Redis, database) in any multi-node deployment. This is the most common "works locally, blank in production" cause.

Fork cost is low, so keep it low. The package is MIT and small; the worst case is owning it. Keep the fork path cheap by subclassing the component and overriding the view instead of copying files, and by keeping your local changes on a short, documented list. If upstream goes stale, you want a git diff you can read in a minute.

Extension point order: config → published view override → subclassed component → forked package. Work down that list only as far as you need to. Most teams stop at the view override for cache-age display, and the config for zone and cadence.