> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/cache/adapters.md).

# Adapters

Quantum's cache package exposes one API across four backends. Pick the adapter based on where cache state must live and what scope `clear()` is allowed to affect.

## Choosing an adapter

* Use `file` for a simple local cache on one machine.
* Use `database` when you want cache state in an application database table.
* Use `memcached` for an external shared cache server.
* Use `redis` for an external shared cache database.

## File adapter

Use the file adapter when local disk storage is enough.

```php
$cache = cache('file');
$cache->set('reports.monthly', $data, 600);
```

### Config contract

`FileAdapter` reads these keys from `cache.file`:

* `path` - directory where cache files are stored
* `ttl` - default TTL in seconds
* `prefix` - string included in the hashed key namespace

### Runtime behavior

* values are serialized into files under `path`
* expiry is stored in the file modification time
* expired files are deleted when `has()` or `get()` checks them
* unreadable or invalid serialized content is deleted and treated as a cache miss

### Caveats

* `clear()` deletes every file under the configured directory, not just files for the current prefix
* missing keys return `false` from `delete()`
* an empty cache directory makes `clear()` return `false`

## Database adapter

Use the database adapter when you want cache state in a table managed by the Database and Model packages.

```php
$cache = cache('database');
$cache->set('dashboard.stats', $stats, 300);
```

### Config contract

`DatabaseAdapter` reads these keys from `cache.database`:

* `table` - table name used for cache rows
* `ttl` - default TTL in seconds
* `prefix` - string included in the hashed key namespace

### Table contract

The adapter reads and writes these fields:

* `key`
* `value`
* `ttl`

A practical schema is:

```sql
CREATE TABLE cache (
    id INTEGER PRIMARY KEY,
    key VARCHAR(255) UNIQUE,
    value TEXT,
    ttl INTEGER
);
```

### Runtime behavior

* each cache key is stored as one row
* existing rows are updated in place
* expiry is checked against the stored Unix timestamp in `ttl`
* expired rows are deleted lazily when checked

### Caveats

* this adapter depends on the Model package being able to create a dynamic model for the configured table
* the package does not create the table for you
* `clear()` deletes rows through the model's bulk delete operation for the whole table

## Memcached adapter

Use the Memcached adapter when multiple workers or servers must share cache state through Memcached.

```php
$cache = cache('memcached');
$cache->set('feed.home', $html, 120);
```

### Config contract

`MemcachedAdapter` reads these keys from `cache.memcached`:

* `host`
* `port`
* `ttl` - default TTL in seconds
* `prefix` - string included in the hashed key namespace

### Runtime behavior

* the adapter opens one Memcached client and adds the configured server
* if `getStats()` fails, adapter construction throws a cache exception
* values are stored as serialized strings with the normalized TTL

### Caveats

* `clear()` calls `flush()` on the Memcached server, so it is not prefix-scoped
* the built-in adapter only configures one host and one port
* network and extension-level failures surface from the Memcached client

## Redis adapter

Use the Redis adapter when you want shared cache state in Redis.

```php
$cache = cache('redis');
$cache->set('api.schema', $schema, 3600);
```

### Config contract

`RedisAdapter` reads these keys from `cache.redis`:

* `host`
* `port`
* `ttl` - default TTL in seconds
* `prefix` - string included in the hashed key namespace

### Runtime behavior

* the adapter connects directly to the configured host and port
* values are stored as serialized strings with the normalized TTL
* `delete()` maps to Redis `DEL`

### Caveats

* `clear()` calls `flushdb()`, so it clears the entire selected Redis database
* the built-in adapter does not configure authentication, database selection, or other Redis options
* Redis connection and command failures bubble as Redis client exceptions

## Shared adapter behavior

All built-in adapters share these contracts:

* stored keys are namespaced through `sha1($prefix . $key)`
* `get()` returns the provided default when the key is missing, expired, or contains invalid serialized data
* `getMultiple()`, `setMultiple()`, and `deleteMultiple()` require arrays and throw `InvalidArgumentException` for other iterables
* `DateInterval` TTL values are converted to seconds at call time


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/cache/adapters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.