Download the PHP package kopaing/laravel-cloudflare-kv without Composer

Laravel Cloudflare KV Cache Driver

A Laravel cache store backed by Cloudflare Workers KV, used through Laravel's normal Cache API:

The goal is to feel like Laravel's Redis driver while being upfront about where KV differs. Workers KV is an eventually consistent, globally replicated key-value store. It has no atomic counters, no compare-and-set, no transactions and no locks. This package does not fake any of those. Operations that would need them are rejected, made opt-in with a clear warning, or delegated to a store that supports them.

Contents: License

Requirements

• PHP 8.3 or newer
• Laravel 12 or 13 (Laravel 11.33.2+ also works; see Version compatibility)
• A Cloudflare account with a Workers KV namespace
• A Cloudflare API token with the Workers KV Storage permission

Installation

Laravel package discovery registers the service provider automatically.

If you want to publish the package defaults (optional):

Cloudflare setup

1. Create a KV namespace

Using the dashboard: Storage & Databases → KV → Create namespace.

Or using Wrangler:

Copy the namespace ID (32 hex characters), not its title. Your account ID is on the dashboard overview page and appears in dashboard URLs.

Use a separate namespace for each application and environment (for example myapp-production-cache and myapp-staging-cache). The namespace is the only hard isolation boundary KV gives you.

2. Create an API token

My Profile → API Tokens → Create Token → Create Custom Token:

This is the least privilege the driver needs. Don't use a Global API Key. When this was written, the Workers KV Storage permission covered every namespace in the selected account and could not be limited to one namespace. If you need hard isolation, use a dedicated Cloudflare account.

Laravel configuration

.env

config/cache.php

Add a store. The smallest valid definition is:

Credentials and defaults then come from config/cloudflare-kv.php, which reads the env variables above. You can also set every option directly on the store:

Configuration precedence

The first value that isn't null wins:

1. The store entry in config/cache.php (stores.<name>.<option>)
2. The package defaults in config/cloudflare-kv.php
3. Laravel defaults: cache.prefix (prefix) and app.key (signing key)

retry and flush are merged one level deep, so 'retry' => ['times' => 5] on a store keeps the default sleep. Several stores can share credentials and use different prefixes or namespaces.

The configuration contains no closures, so php artisan config:cache is supported. As with any Laravel config, env() is only read when the config is built or cached.

All options

Usage

With CACHE_STORE=cloudflare you can call Cache::get() and the rest without store().

Eloquent models and collections work out of the box, including on Laravel 13. New Laravel 13 apps set 'serializable_classes' => false in config/cache.php. Laravel's own stores then return objects as __PHP_Incomplete_Class, because anyone who can write to Redis or the database could plant a malicious serialized object. This driver deliberately does not inherit that setting. It only unserializes payloads carrying a valid HMAC signature made with your APP_KEY (or signing_key), so values planted by anyone else are rejected before unserialize() runs. To restrict classes anyway, set this store's serializable_classes to a list of classes or to false.

Locks

KV can't provide mutual exclusion. Delegate locks to a store that can:

Cache::flexible(), ShouldBeUnique jobs and withoutOverlapping() then work too. Values stay in KV; only the lock lives in the other store. Without lock_store, lock() throws CloudflareKVUnsupportedOperationException.

TTL and expiration

Cloudflare KV doesn't accept expirations shorter than 60 seconds (expiration_ttl ≥ 60). Redis does, so this package handles the gap explicitly:

• Each payload stores its own logical expiry, and every read checks it. An expired value is never returned, even if KV still holds it.
• The Cloudflare-side TTL is max(ttl, 60). KV therefore never deletes an entry before Laravel considers it expired, and an entry with a short TTL just stays (unreadable) for up to 60 s.
• TTLs of 60 s and longer go to Cloudflare unchanged, so both clocks agree.
• forever() writes have no Cloudflare TTL unless you set forever_ttl.
• A TTL of zero or less deletes the key, as in Laravel's other stores.
• DateTimeInterface and DateInterval TTLs work, because Laravel's repository converts them to seconds.

Expiry is checked against your application servers' clocks, so keep them NTP-synced.

Supported and unsupported cache APIs

Flush safety

flush() lists only keys that start with this store's prefix. It pages through them 1,000 at a time and deletes in batches of up to 10,000, and it also drops any listed key that doesn't match the prefix before deleting. It refuses to run with an empty prefix unless flush.allow_without_prefix is true, and flush.enabled => false blocks it completely. Because of eventual consistency, keys written in the last ~60 s may be missed, and deleted keys can stay readable at some edge locations for up to ~60 s.

Prefixes nested inside each other (app: and app:v2:) will be flushed together. Give each app its own namespace, or at least prefixes that don't overlap.

Consistency and performance limitations

• Eventual consistency. A write or delete can take up to 60 s or more to be visible in other locations, and even the same server can briefly read the old value. In live testing, get() straight after forget() still returned the deleted value. Don't rely on read-your-own-write or read-your-own-delete.
• Write rate. Cloudflare allows about one write per second to the same key. Faster writes get 429 responses, which are retried with backoff.
• API rate limit. The Cloudflare REST API allows 1,200 requests per 5 minutes per user. Once exceeded, calls are blocked for about 5 minutes. Use many/putMany and don't put KV on hot paths that write on every request.
• Latency. Each cache call is an HTTPS request to the Cloudflare API, not a local socket. Expect tens of milliseconds, not microseconds. KV is a good fit for data that is read often and written rarely.
• Sizes. Keys can be up to 512 bytes. Values can be up to 25 MiB after encoding; the php serializer adds about 33% for base64. Oversized keys and values are rejected before any request is made.
• Keys. Keys with whitespace, control characters, invalid UTF-8, or more than 512 bytes are stored as prefix + "~h:" + sha256(key). Every other key is stored as prefix + key.

Error handling

Every exception extends Kopaing\CloudflareKV\Exceptions\CloudflareKVException. The exception is CloudflareKVSerializationException, which extends InvalidArgumentException.

Retries: connection failures, 408, 429 and 5xx get bounded exponential backoff with jitter. All the REST calls the package makes are idempotent, so retrying them can't apply a change twice. Bulk writes and deletes resend only the keys Cloudflare reports as failed. A Retry-After longer than retry.max_sleep fails fast instead of blocking a web request for minutes.

Cache outages: as with Redis, transport errors are thrown, not swallowed. To degrade gracefully, wrap calls yourself or use Laravel's failover cache driver (later Laravel 12 releases and 13).

A 404 means a miss. The values endpoint answers 404 both for missing keys and for some namespace misconfigurations. A wrong namespace_id therefore shows up as permanent misses on reads and as errors on writes.

Instrumentation

When events is enabled, these events are dispatched. They never include keys, values or credentials:

Laravel's own CacheHit, CacheMissed and KeyWritten events are also dispatched as usual.

Security recommendations

• Least privilege: a token with only Workers KV Storage: Edit on one account, ideally with an IP filter and an expiry date.
• No secrets in logs: exception messages and events never contain the API token or cached values. The token is also hidden from dump() output and stack-trace arguments, and the HTTP client's exceptions (which hold the request headers) are not chained.
• Safe deserialization: values are stored in a versioned JSON envelope signed with HMAC-SHA256. The signing key is derived from APP_KEY or signing_key, and the signature covers the storage key and expiry. unserialize() only runs on payloads whose signature checks out. Anyone who can write to the namespace without your key, such as another app, a Worker, or a dashboard user, can't make your app create PHP objects. Their values are just cache misses. That's why every class is allowed by default. If your APP_KEY leaks, rotate it; that also invalidates every cached entry. For defence in depth, restrict serializable_classes to the classes you actually cache.
• The json serializer never instantiates objects at all. Use it if you only cache arrays and scalars.
• Encryption: KV values are readable by anyone with dashboard or API access to the account. If you cache personal or sensitive data, set encrypt => true (AES via Laravel's encrypter), or don't cache that data in KV.
• Key rotation: changing APP_KEY or signing_key turns existing entries into misses. They aren't decrypted with the wrong key; they expire or are flushed normally.
• Isolation: use one namespace per app and environment, and a unique prefix. Account and namespace IDs are validated to keep requests from escaping the namespace path.

Testing

The Feature suite runs the real client against a stateful in-memory imitation of the KV REST API (tests/Fakes/FakeCloudflareKVApi.php) through Http::fake(). It covers the HTTP formats, pagination, partial bulk failures, rate limiting, timeouts and expiry.

Live integration tests are opt-in and must use a dedicated, empty test namespace:

Testing your own app: use the array store in tests (CACHE_STORE=array in phpunit.xml) so your test suite never calls Cloudflare.

Troubleshooting

Version compatibility

CI tests every Laravel and PHP combination above, with both the lowest and the latest allowed dependencies. Verified for this release: Laravel 13.0.0 and 13.34.0, 12.0.1 and 12.69.3, and 11.33.2 and 11.57.0, all on PHP 8.4. PHP 8.3 and 8.5 are covered by the CI matrix.

Contributing

See CONTRIBUTING.md. Please report security issues privately through GitHub Security Advisories, not public issues.

Publishing and upgrading

First publication

1. Create an empty GitHub repository kopaing/laravel-cloudflare-kv. Keep the name in sync with homepage/support in composer.json.

2. Push the code:

3. Wait for the tests workflow to pass.

4. In CHANGELOG.md, rename ## [Unreleased] to ## [1.0.0] - YYYY-MM-DD, commit, then tag. The release workflow runs the full matrix and creates the GitHub release from that changelog section.

5. Submit the repository URL at https://packagist.org/packages/submit. Packagist reads composer.json from GitHub, and its GitHub integration picks up later tags automatically. If it doesn't, add the Packagist webhook under Settings → Webhooks.
6. Check the result from a fresh Laravel app:

Versioning

The package follows Semantic Versioning. The public API is the store's behaviour, the config keys, the exception classes, the events and CloudflareKVClientInterface. Patch releases contain fixes, minor releases add backwards-compatible features, and major releases contain breaking changes. Before 1.0.0, use pre-release tags like v1.0.0-beta.1 (the release workflow marks them as pre-releases).

Upgrading

Read CHANGELOG.md before upgrading. The stored payload has a version field ("v": 1), so a future format change can still read old entries or treat them as misses. It will never misread them.

License

MIT. See LICENSE.