Cache UI Laravel

https://github.com/abr4xas/cache-ui-laravel
Admin
A Laravel package that allows you to list, search, and delete individual cache keys without having...
Tokens:22,524
Snippets:181
Trust Score:8.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### get usage example

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Example of using the get method to retrieve a cached value by key.

```php
$profile = Cache::store('file')->get('user_1_profile');
```

--------------------------------

### Interactive cache management example

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Example output showing the interactive flow of searching and deleting a cache key.

```bash
$ php artisan cache:list

📦 Cache driver: redis
✅ Found 23 cache keys

🔍 Search and select a cache key to delete
> user_1_profile

📝 Key:     user_1_profile

Are you sure you want to delete this cache key? › No / Yes

🗑️  The key 'user_1_profile' has been successfully deleted
```

--------------------------------

### getAllKeys basic usage

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

Examples of retrieving keys from the default store, a specific store, and applying a limit.

```php
use Abr4xas\\\CacheUiLaravel\\\Facades\\\CacheUiLaravel;

$keys = CacheUiLaravel::getAllKeys();            // default store
$redisKeys = CacheUiLaravel::getAllKeys('redis'); // specific store
$limitedKeys = CacheUiLaravel::getAllKeys('redis', 100); // first 100 keys
```

--------------------------------

### Usage examples for cache:list

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-command.md

Shows various invocations of the `cache:list` command with different options.

```bash
php artisan cache:list
php artisan cache:list --store=redis
php artisan cache:list --store=redis --show-value --info --limit=100
php artisan cache:list --export=keys.txt
php artisan cache:list --filter="/^user_/"
```

--------------------------------

### add usage example

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Example of using the add method to store a value only if the key is absent. The first caller wins.

```php
if (Cache::store('file')->add('counter', 1, 60)) {
    // First caller wins.
}
```

--------------------------------

### put usage example

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Example of using the put method via the file cache store. The driver is registered by the package, so the repository wraps store methods.

```php
use Illuminate\Support\Facades\Cache;

// The driver is registered by the package, so the repository wraps store methods:
Cache::store('file')->put('user_1_profile', ['name' => 'Alice'], 3600);
```

--------------------------------

### Install Laravel Boost agent skill

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Installs the cache-store-development agent skill if you are using Laravel Boost.

```bash
php artisan boost:install
```

--------------------------------

### Error handling with forgetKey

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

Example showing how empty keys are rejected and how to handle per-key feedback during batch deletion.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

if (! CacheUiLaravel::forgetKey('')) {
    // Empty key rejected — returns false immediately.
}

// Batch deletion with per-key feedback
$keys = ['a', 'b', 'c'];
foreach ($keys as $key) {
    if (CacheUiLaravel::forgetKey($key, 'redis')) {
        echo "Deleted {$key}\n";
    } else {
        echo "Could not delete {$key}\n";
    }
}
```

--------------------------------

### Configure file store with key-aware-file driver

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-service-provider.md

Example configuration in config/cache.php to use the key-aware-file driver. The driver is registered automatically, so no Cache::extend() call is needed in AppServiceProvider.

```php
'file' => [
    'driver' => 'key-aware-file', // changed from 'file'
    'path' => storage_path('framework/cache/data'),
    'lock_path' => storage_path('framework/cache/data'),
],
```

--------------------------------

### Basic usage of forgetKey

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

Example of deleting a key from the default store and a specific store using the CacheUiLaravel facade.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$deleted = CacheUiLaravel::forgetKey('user_1_profile');             // default store
$deleted = CacheUiLaravel::forgetKey('session_data', 'redis');      // specific store
```

--------------------------------

### Install package via Composer

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Use this command to add the package to your Laravel project.

```bash
composer require abr4xas/cache-ui-laravel
```

--------------------------------

### forever usage example

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Example of storing a value indefinitely using the `forever` method on the file cache store.

```php
Cache::store('file')->forever('settings', $settings);
```

--------------------------------

### Facade error handling with invalid input

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Error handling example showing that delegated methods never throw; invalid input returns false or empty array.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

if (! CacheUiLaravel::forgetKey('')) {
    // Empty key rejected — returns false immediately.
}

if (CacheUiLaravel::getAllKeys('unknown_store') === []) {
    // Unknown store or no keys — both return [].
}
```

--------------------------------

### refreshIfOwned usage example

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Example of refreshing a lock if owned, normally reached indirectly via `Illuminate\Cache\FileLock::refresh()`.

```php
// Normally only reached indirectly via Illuminate\Cache\FileLock::refresh().
$refreshed = $store->refreshIfOwned('lock:reservation', $ownerToken, 300);
```

--------------------------------

### get method signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Signature of the get method, which retrieves an item from the cache by key. Returns the unwrapped cached value, or null if not found or expired.

```php
public function get($key): mixed
```

--------------------------------

### Strip a cache key prefix with Str::chopStart()

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/resources/boost/skills/cache-store-development/SKILL.md

Use Str::chopStart() on keys read from a prefixed store before handing them to Cache::forget(), so the prefix is not applied twice. It only removes the needle when it is actually at the start and no-ops on an empty needle. Laravel uses the same method internally in DatabaseStore::forgetManyIfExpired().

```php
use Illuminate\Support\Str;

$key = Str::chopStart($storedKey, $store->getPrefix());
```

```php
ltrim('myapp_cache_cart', 'myapp_cache_');   // 'rt'   — wrong
ltrim('myapp_cache_apple', 'myapp_cache_');  // 'le'   — wrong
Str::chopStart('myapp_cache_cart', 'myapp_cache_');  // 'cart'
```

--------------------------------

### get($key): mixed

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Retrieves an item from the cache by key. Returns the unwrapped cached value, or null if not found or expired.

```APIDOC
## `get($key): mixed`

### Description
Retrieve an item from the cache by key.

### Signature
```php
public function get($key): mixed
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$key` | `string` | Yes | — | The cache key |

### Return type
`mixed` — the unwrapped cached value, or `null` if not found / expired.

### Usage example
```php
$profile = Cache::store('file')->get('user_1_profile');
```
```

--------------------------------

### getAllKeys pagination and error handling

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

Demonstrates how the method handles non-existent stores by returning an empty array and how to implement pagination.

```php
use Abr4xas\\\CacheUiLaravel\\\Facades\\\CacheUiLaravel;

$keys = CacheUiLaravel::getAllKeys('nonexistent_store');
if ($keys === []) {
    // Store missing, or no keys — both look the same. Check config if you need to distinguish.
}

// Paginate in batches
$offset = 0;
$limit = 100;
do {
    $batch = CacheUiLaravel::getAllKeys('redis', $limit, $offset);
    // process $batch...
    $offset += $limit;
} while (count($batch) === $limit);
```

--------------------------------

### Run basic cache list command

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Executes the command to list and manage cache keys.

```bash
php artisan cache:list
```

--------------------------------

### Basic facade usage for default store

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Basic usage of the facade to list all keys and delete a key from the default cache store.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$keys = CacheUiLaravel::getAllKeys();                 // default store, all keys
$deleted = CacheUiLaravel::forgetKey('user_1_profile'); // delete from default store
```

--------------------------------

### Facade usage with specific store and pagination

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Using the facade with a specific store, limit, and offset for pagination.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$page = CacheUiLaravel::getAllKeys('redis', 100, 0); // first 100 keys on 'redis'
$deleted = CacheUiLaravel::forgetKey('session_data', 'redis');
```

--------------------------------

### Run package test suite

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Commands to execute the full quality suite, individual testing steps, specific test files, or coverage reports.

```bash
# Run everything: Rector (dry-run) + Pint + PHPStan + Pest
composer test

# Or run each step individually
composer test:refactor   # Rector dry-run
composer test:lint       # Pint code style check
composer test:types      # PHPStan (level 6, via Larastan)
composer test:unit       # Pest test suite

# Run a specific test file
vendor/bin/pest tests/Unit/CacheUiLaravelMethodsTest.php

# Run with coverage
vendor/bin/pest --coverage
```

--------------------------------

### Specify cache store for list command

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Use the --store option to target a specific cache store when multiple are configured.

```bash
php artisan cache:list --store=redis
```

--------------------------------

### Configure key-aware-file driver

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Update your config/cache.php file to use the key-aware-file driver for the file store.

```php
// ... existing code ...

    'stores' => [

        // ... existing stores ...

        'file' => [
            'driver' => 'key-aware-file', // Changed from 'file' to 'key-aware-file'
            'path' => storage_path('framework/cache/data'),
            'lock_path' => storage_path('framework/cache/data'),
        ],

// ... existing code ...
```

--------------------------------

### handle method signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-command.md

The entry point of the command, injected with a `CacheUiLaravel` instance by the container.

```php
public function handle(CacheUiLaravel $cacheUiLaravel): int
```

--------------------------------

### Command signature and description

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-command.md

Defines the `cache:list` command signature with options for store, show-value, export, filter, info, and limit, and a description.

```php
public $signature = 'cache:list
                    {--store= : The cache store to use}
                    {--show-value : Show cache value before deletion}
                    {--export= : Export keys list to file}
                    {--filter= : Filter keys by regex pattern}
                    {--info : Show additional information (size, expiration)}
                    {--limit= : Limit number of keys to display}';

public $description = 'List and delete individual cache keys';
```

--------------------------------

### getAllKeys(?string $store = null, ?int $limit = null, int $offset = 0): array

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

Lists all cache keys from a specified store, with optional limit and offset for pagination. Returns an array of key names, or an empty array on failure.

```APIDOC
## getAllKeys(?string $store = null, ?int $limit = null, int $offset = 0): array

### Description
Get all available cache keys from the specified store. This method lists cache keys across Redis, File, and Database cache drivers without purging the whole cache.

### Signature
```php
public function getAllKeys(?string $store = null, ?int $limit = null, int $offset = 0): array
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$store` | `?string` | No | `null` (falls back to `config('cache.default')`) | The cache store to use. Empty values fall through to the default store. |
| `$limit` | `?int` | No | `null` (falls back to `config('cache-ui-laravel.keys_limit')`) | Maximum number of keys to return. `null` = unlimited. Negative values are coerced to `null`. |
| `$offset` | `int` | No | `0` | Number of keys to skip before returning results (for pagination). Negative values are coerced to `0`. |

### Return Type
`array<string>` — a list of cache key names (re-indexed with `array_values`), already stripped of any store/connection prefixes. Returns an empty array when the store is invalid, does not exist, cannot be resolved, or when an error occurs.

### Throws / Rejects
Does not throw. All failure paths log (only when `enable_logging` is on) and return an empty array.

### Behavior by Driver
- **Redis** (`RedisStore`): uses `SCAN` (cursor-based, non-blocking) with a `count` of 100, matching `prefix.*`. Falls back to `KEYS prefix.*` if SCAN yields nothing or fails. Strips the concatenated connection + store prefix from each key before applying offset/limit.
- **File** (`FileStore`, including `KeyAwareFileStore`): lazily walks cache files, reads the real key from the wrapped payload when present, otherwise falls back to the hashed filename. Expired and unreadable entries are skipped before paging.
- **Database** (`DatabaseStore`): reads the `key` column from the store's cache table, applying offset/limit at the query level, and strips the store prefix from each key.

When `config('cache-ui-laravel.hide_internal_keys')` is truthy (default), keys beginning with the internal prefix `illuminate:cache:flexible:created:` are filtered out afterwards (making `$limit` a *soft cap* in that case).

### Usage Examples
Basic — get all keys from the default store:

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$keys = CacheUiLaravel::getAllKeys();            // default store
$redisKeys = CacheUiLaravel::getAllKeys('redis'); // specific store
$limitedKeys = CacheUiLaravel::getAllKeys('redis', 100); // first 100 keys
```

Pagination / error handling — a non-existent store degrades to an empty array rather than throwing:

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$keys = CacheUiLaravel::getAllKeys('nonexistent_store');
if ($keys === []) {
    // Store missing, or no keys — both look the same. Check config if you need to distinguish.
}

// Paginate in batches
$offset = 0;
$limit = 100;
do {
    $batch = CacheUiLaravel::getAllKeys('redis', $limit, $offset);
    // process $batch...
    $offset += $limit;
} while (count($batch) === $limit);
```
```

--------------------------------

### Perform Batch Operations on Cache Keys

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Demonstrates filtering keys by pattern and performing bulk deletion using the CacheUiLaravel facade.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

// Get all keys matching a pattern
$allKeys = CacheUiLaravel::getAllKeys('redis');
$userKeys = array_filter($allKeys, fn($key) => str_starts_with($key, 'user_'));

// Delete multiple keys
foreach ($userKeys as $key) {
    CacheUiLaravel::forgetKey($key, 'redis');
}
```

--------------------------------

### Resolve cache store and dispatch on its class

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/resources/boost/skills/cache-store-development/SKILL.md

Resolve the store once with Cache::store($storeName)->getStore(), then use a match expression to dispatch on the resolved class (RedisStore, FileStore, DatabaseStore). Subclasses of FileStore are handled by the FileStore branch. This avoids hardcoding config paths and works even when the store name differs from the driver name.

```php
$baseStore = Cache::store($storeName)->getStore();

$keys = match (true) {
    $baseStore instanceof RedisStore => $this->fromRedis($baseStore),
    // Subclasses land here too, so a custom file store needs no extra branch.
    $baseStore instanceof FileStore => $this->fromFile($baseStore),
    $baseStore instanceof DatabaseStore => $this->fromDatabase($baseStore),
    default => [],
};
```

--------------------------------

### Register a custom cache driver with Cache::extend()

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/resources/boost/skills/cache-store-development/SKILL.md

Register a custom cache driver with Cache::extend(). The closure receives the application and config array, and must build the full store and repository, mirroring the matching create*Driver() method in Illuminate\Cache\CacheManager. Pass $config to Cache::repository() so the store name and events flag are preserved. Register inside an $this->app->booting() callback so the driver exists before other providers' boot() reads from the cache.

```php
Cache::extend('key-aware-file', fn (Application $app, array $config): Repository => Cache::repository(
    new KeyAwareFileStore(
        $app->make(Filesystem::class),
        $config['path'],
        $config['permission'] ?? null,
        // Dropping this silently disables the allowed_classes restriction on
        // unserialize() that cache.serializable_classes is there to enforce.
        $app['config']['cache.serializable_classes'] ?? null,
    )->setLockDirectory($config['lock_path'] ?? null),
    // Without $config the repository loses its store name, so cache events are
    // dispatched without it and the `events` flag is ignored.
    $config,
));
```

--------------------------------

### CacheUiLaravelServiceProvider boot() signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-service-provider.md

Declares the boot method signature. It is called during service provider booting and registers config publishing and the console command.

```php
public function boot(): void
```

--------------------------------

### Optimize Performance with Pagination

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Uses the limit and offset parameters to process large cache datasets in batches.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

// Get first 100 keys (useful for pagination)
$firstBatch = CacheUiLaravel::getAllKeys('redis', 100);

// Process in batches with pagination
$offset = 0;
$limit = 100;
do {
    $keys = CacheUiLaravel::getAllKeys('redis', $limit, $offset);
    // Process keys...
    $offset += $limit;
} while (count($keys) === $limit);
```

--------------------------------

### Publish cache-ui-laravel config

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-service-provider.md

Publishes the package configuration file to the application's config directory. Use this command to customize the package settings.

```bash
php artisan vendor:publish --tag="cache-ui-laravel-config"
```

--------------------------------

### Configure package settings

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Customize package behavior by modifying the returned array in the published configuration file.

```php
return [
    // Default cache store to use
    'default_store' => env('CACHE_UI_DEFAULT_STORE', null),

    // Character limit in value preview
    'preview_limit' => env('CACHE_UI_PREVIEW_LIMIT', 100),

    // Number of visible items in scroll
    'search_scroll' => env('CACHE_UI_SEARCH_SCROLL', 15),

    // Maximum number of keys to retrieve (null = unlimited)
    'keys_limit' => env('CACHE_UI_KEYS_LIMIT', null),

    // Enable error logging for cache operations
    'enable_logging' => env('CACHE_UI_ENABLE_LOGGING', false),

    // Timeout in seconds for cache operations (0 = no timeout)
    'operation_timeout' => env('CACHE_UI_OPERATION_TIMEOUT', 0),

    // Hide Laravel's internal cache keys (e.g. Cache::flexible() bookkeeping)
    'hide_internal_keys' => env('CACHE_UI_HIDE_INTERNAL_KEYS', true),
];
```

--------------------------------

### CacheUiLaravel::getAllKeys

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Retrieves all cache keys from a specified store, with optional limit and offset for pagination. Returns an array of keys.

```APIDOC
## CacheUiLaravel::getAllKeys

### Description
Retrieves all cache keys from a specified store, with optional limit and offset for pagination. Returns an array of keys.

### Method
`getAllKeys`

### Signature
php
public function getAllKeys(?string $store = null, ?int $limit = null, int $offset = 0): array


### Parameters
- **store** (?string) - Optional - The cache store name. Defaults to the default store.
- **limit** (?int) - Optional - Maximum number of keys to return.
- **offset** (int) - Optional - Number of keys to skip for pagination. Defaults to 0.

### Returns
- **array** - List of cache keys. Returns an empty array if the store is unknown or has no keys.

### Example
php
$keys = CacheUiLaravel::getAllKeys(); // default store, all keys
$page = CacheUiLaravel::getAllKeys('redis', 100, 0); // first 100 keys on 'redis'

```

--------------------------------

### Advanced cache command options

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Various flags to customize the output, filtering, and management of cache keys.

```bash
# Show cache value before deletion
php artisan cache:list --show-value

# Export keys list to a file
php artisan cache:list --export=keys.txt

# Filter keys by regex pattern
php artisan cache:list --filter="/^user_/"

# Show additional information (size, type, expiration)
php artisan cache:list --info

# Limit number of keys displayed (useful for large caches)
php artisan cache:list --limit=50

# Combine multiple options
php artisan cache:list --store=redis --show-value --info --limit=100
```

--------------------------------

### Programmatic usage: CacheUiLaravel facade

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/README.md

Use the CacheUiLaravel facade to retrieve all cache keys and delete a specific key. The getAllKeys method takes a store name, limit, and offset; forgetKey deletes a key by name and store.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$keys = CacheUiLaravel::getAllKeys('redis', 100, 0);
$deleted = CacheUiLaravel::forgetKey('user_1_profile', 'redis');
```

--------------------------------

### touch($key, $seconds): bool

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Adjusts the expiration time of a cached item.

```APIDOC
## `touch($key, $seconds): bool`

### Description
Adjust the expiration time of a cached item.

### Signature

```php
public function touch($key, $seconds): bool
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$key` | `string` | Yes | — | The cache key |
| `$seconds` | `int` | Yes | — | Number of seconds until the new expiration |

### Return type

`bool` — `false` if no payload exists; otherwise the result of re-`put`ting the unwrapped value.

### Behavior

Overridden because the parent re-stores `$payload['data']` verbatim, which for this store is the wrapper array and would end up double-wrapped. Reads the payload under the prefixed key, unwraps, and re-puts with the new TTL.
```

--------------------------------

### Analyze Cache Key Distribution

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Groups cache keys by their prefix to visualize key distribution patterns.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$keys = CacheUiLaravel::getAllKeys('redis');
$patterns = [];

foreach ($keys as $key) {
    $prefix = explode('_', $key)[0] ?? 'unknown';
    $patterns[$prefix] = ($patterns[$prefix] ?? 0) + 1;
}

arsort($patterns);
print_r($patterns); // Shows key distribution by prefix
```

--------------------------------

### Register key-aware-file cache driver

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-service-provider.md

Registers the 'key-aware-file' cache driver using Cache::extend(). It is wrapped in an application booting callback so it is available before other providers boot. The driver uses KeyAwareFileStore with configurable path, permission, lock directory, and serializable classes.

```php
Cache::extend('key-aware-file', fn (Application $app, array $config): Repository => Cache::repository(
    new KeyAwareFileStore(
        $app->make(Filesystem::class),
        $config['path'] ?? storage_path('framework/cache/data'),
        $config['permission'] ?? $config['file_permission'] ?? null,
        $app['config']['cache.serializable_classes'] ?? null,
    )->setLockDirectory($config['lock_path'] ?? null),
    $config
));
```

--------------------------------

### getAllKeys method signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

The signature for the public getAllKeys method used to retrieve cache keys.

```php
public function getAllKeys(?string $store = null, ?int $limit = null, int $offset = 0): array
```

--------------------------------

### getFacadeAccessor return statement

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Returns the class name of the singleton binding that the facade resolves.

```php
return \Abr4xas\CacheUiLaravel\CacheUiLaravel::class;
```

--------------------------------

### Artisan command: php artisan cache:list

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/README.md

Interactive command to list cache keys with options for store, value display, export, filter, info, and limit. Exit code 0 indicates success; exit code 1 indicates failure.

```bash
php artisan cache:list [--store=] [--show-value] [--export=] [--filter=] [--info] [--limit=]
```

--------------------------------

### key-aware-file driver configuration in config/cache.php

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/configuration.md

Configuration for the custom 'key-aware-file' driver inside config/cache.php. The driver is registered by the service provider and consumes the 'path' and 'lock_path' keys.

```php
// config/cache.php
'file' => [
    'driver' => 'key-aware-file',
    'path' => storage_path('framework/cache/data'),
    'lock_path' => storage_path('framework/cache/data'),
],
```

--------------------------------

### Scan Redis keys with termination on cursor '0' or ''

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/resources/boost/skills/cache-store-development/SKILL.md

Match SCAN on $prefix.'*' to stay inside the store's keyspace. Terminate on the cursor Redis reports (0 for phpredis 6.1+) and also exit when the scan returns a non-array, because PhpRedisConnection::scan() returns false when the cursor comes back zero with nothing left.

```php
do {
    $scanResult = $connection->scan($cursor, ['match' => $prefix.'*', 'count' => 100]);

    if (! is_array($scanResult)) {
        break;
    }

    [$cursor, $scannedKeys] = $scanResult;
    // ...collect $scannedKeys...
} while (! in_array((string) $cursor, ['0', ''], true));
```

--------------------------------

### CacheUiLaravelServiceProvider register() signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-service-provider.md

Declares the register method signature. It binds the main class as a singleton and registers the custom cache driver.

```php
public function register(): void
```

--------------------------------

### Hide internal Cache::flexible keys

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Demonstrates how the package automatically hides internal bookkeeping keys generated by Cache::flexible() when listing all keys.

```php
use Abr4xas\\\CacheUiLaravel\\\Facades\\\CacheUiLaravel;
use Illuminate\\\Support\\\Facades\\\Cache;

Cache::flexible('users', [5, 10], fn () => User::all());

CacheUiLaravel::getAllKeys();
// ['users']  ← the "illuminate:cache:flexible:created:users" companion is hidden
```

--------------------------------

### put($key, $value, $seconds): bool

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Stores an item in the cache for a specified number of seconds. Returns true if the file was written and permissions were ensured, false otherwise.

```APIDOC
## `put($key, $value, $seconds): bool`

### Description
Store an item in the cache for a given number of seconds.

### Signature
```php
public function put($key, $value, $seconds): bool
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$key` | `string` | Yes | — | The cache key |
| `$value` | `mixed` | Yes | — | The value to store |
| `$seconds` | `int` | Yes | — | Number of seconds until expiration |

### Return type
`bool` — `true` if the file was written (`$result !== false && $result > 0`) and permissions were ensured, `false` otherwise.

### Usage example
```php
use Illuminate\Support\Facades\Cache;

// The driver is registered by the package, so the repository wraps store methods:
Cache::store('file')->put('user_1_profile', ['name' => 'Alice'], 3600);
```
```

--------------------------------

### forgetKey method signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

The method signature for forgetKey, showing the parameters and return type.

```php
public function forgetKey(string $key, ?string $store = null): bool
```

--------------------------------

### Monitor Cache Size

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Calculates the total size of cached items in megabytes by iterating through keys with a specified limit.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;
use Illuminate\Support\Facades\Cache;

// Use limit parameter for better performance on large caches
$keys = CacheUiLaravel::getAllKeys('redis', 1000);
$totalSize = 0;

foreach ($keys as $key) {
    $value = Cache::get($key);
    if ($value !== null) {
        $totalSize += strlen(serialize($value));
    }
}

echo "Total cache size: " . number_format($totalSize / 1024 / 1024, 2) . " MB";
```

--------------------------------

### Environment variables for cache-ui-laravel configuration

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/configuration.md

Environment variables for configuring the package. All options except supported_drivers can be set this way.

```env
CACHE_UI_DEFAULT_STORE=redis
CACHE_UI_PREVIEW_LIMIT=150
CACHE_UI_SEARCH_SCROLL=20
CACHE_UI_KEYS_LIMIT=1000
CACHE_UI_ENABLE_LOGGING=true
CACHE_UI_OPERATION_TIMEOUT=30
CACHE_UI_HIDE_INTERNAL_KEYS=true
```

--------------------------------

### Programmatic usage of CacheUiLaravel

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Directly interact with the cache using the CacheUiLaravel facade to retrieve or delete keys.

```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

// Get all cache keys from default store
$keys = CacheUiLaravel::getAllKeys();

// Get all cache keys from a specific store
$redisKeys = CacheUiLaravel::getAllKeys('redis');

// Get limited number of keys (useful for large caches)
$limitedKeys = CacheUiLaravel::getAllKeys('redis', 100);

// Delete a specific key from default store
$deleted = CacheUiLaravel::forgetKey('user_1_profile');

// Delete a key from a specific store
$deleted = CacheUiLaravel::forgetKey('session_data', 'redis');

// The methods include validation:
// - Empty or invalid store names will use the default store
// - Empty keys will return false
// - Non-existent stores will throw an exception (if logging is enabled, errors are logged)
```

--------------------------------

### Bind CacheUiLaravel singleton

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-service-provider.md

Binds CacheUiLaravel as a singleton in the container. This is the accessor resolved by the CacheUiLaravel facade and injected into the command's handle().

```php
$this->app->singleton(CacheUiLaravel::class, fn (): CacheUiLaravel => new CacheUiLaravel);
```

--------------------------------

### Compute Redis store and connection prefixes for SCAN

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/resources/boost/skills/cache-store-development/SKILL.md

SCAN and KEYS return fully prefixed keys, which include both the store prefix and any connection-level global prefix. This snippet computes the connection prefix for PhpRedis and Predis and concatenates it with the store's prefix, exactly as RedisStore::currentTags() does.

```php
$connection = $store->connection();

$connectionPrefix = match (true) {
    $connection instanceof PhpRedisConnection => $connection->_prefix(''),
    $connection instanceof PredisConnection => (string) ($connection->getOptions()->prefix ?: ''),
    default => '',
};

$prefix = $connectionPrefix.$store->getPrefix();
```

--------------------------------

### add($key, $value, $seconds): bool

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Stores an item in the cache only if the key does not already exist. Returns true if the item was stored, false if the key already exists or the lock could not be acquired.

```APIDOC
## `add($key, $value, $seconds): bool`

### Description
Store an item in the cache only if the key does not already exist.

### Signature
```php
public function add($key, $value, $seconds): bool
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$key` | `string` | Yes | — | The cache key |
| `$value` | `mixed` | Yes | — | The value to store |
| `$seconds` | `int` | Yes | — | Number of seconds until expiration |

### Return type
`bool` — `true` if the item was stored, `false` if the key already exists (or the exclusive lock could not be acquired within the lock timeout).

### Behavior
Uses a `LockableFile` opened in `'c+'` mode with an exclusive lock. Reads the existing 10-character expiration header: writes the wrapped payload only when the header is empty or already expired.

### Usage example
```php
if (Cache::store('file')->add('counter', 1, 60)) {
    // First caller wins.
}
```
```

--------------------------------

### Register CacheUiLaravelCommand

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel-service-provider.md

Registers the CacheUiLaravelCommand with the Laravel console. This is called inside the boot method.

```php
$this->commands([CacheUiLaravelCommand::class]);
```

--------------------------------

### Disable internal key filtering

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Shows how to disable the default filtering behavior in the configuration file to inspect internal keys, followed by the resulting output.

```php
// config/cache-ui-laravel.php
'hide_internal_keys' => false,
```

```php
CacheUiLaravel::getAllKeys();
// ['users', 'illuminate:cache:flexible:created:users']
```

--------------------------------

### getFacadeAccessor method signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Signature of the getFacadeAccessor method that returns the container binding for the facade.

```php
protected static function getFacadeAccessor(): string
```

--------------------------------

### Test round-trip key deletion with Cache::forget()

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/resources/boost/skills/cache-store-development/SKILL.md

Use this test to verify that a key returned by the inspector's getAllKeys survives a round trip through forgetKey and is actually removed from the cache store. It asserts that forgetKey returns true and that the cached value for 'user_1_profile' becomes null after the operation.

```php
$listed = $inspector->getAllKeys('database');

expect($inspector->forgetKey($listed[0], 'database'))->toBeTrue()
    ->and(Cache::store('database')->get('user_1_profile'))->toBeNull();
```

--------------------------------

### put method signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Signature of the put method, which stores an item in the cache for a given number of seconds. Returns true if the file was written and permissions were ensured, false otherwise.

```php
public function put($key, $value, $seconds): bool
```

--------------------------------

### touch($key, $seconds) signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Signature of the `touch` method, which adjusts the expiration time of a cached item. Returns `false` if no payload exists; otherwise re-puts the unwrapped value with the new TTL.

```php
public function touch($key, $seconds): bool
```

--------------------------------

### getFacadeAccessor

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Returns the container binding that the facade resolves. This is the accessor for the singleton binding created in the service provider.

```APIDOC
## getFacadeAccessor

### Description
Returns the container binding that the facade resolves. This is the accessor for the singleton binding created in the service provider.

### Method
`getFacadeAccessor`

### Signature
php
protected static function getFacadeAccessor(): string


### Returns
- **string** - The class name of the underlying singleton: `\Abr4xas\CacheUiLaravel\CacheUiLaravel`

### Example
php
return \Abr4xas\CacheUiLaravel\CacheUiLaravel::class;

```

--------------------------------

### add method signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Signature of the add method, which stores an item only if the key does not already exist. Returns true if stored, false if the key exists or the lock could not be acquired.

```php
public function add($key, $value, $seconds): bool
```

--------------------------------

### forever($key, $value): bool

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Stores an item in the cache indefinitely.

```APIDOC
## `forever($key, $value): bool`

### Description
Store an item in the cache indefinitely.

### Signature

```php
public function forever($key, $value): bool
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$key` | `string` | Yes | — | The cache key |
| `$value` | `mixed` | Yes | — | The value to store |

### Return type

`bool` — delegates to `put($key, $value, 0)`.

### Usage example

```php
Cache::store('file')->forever('settings', $settings);
```
```

--------------------------------

### Configure Error Logging

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/README.md

Enables error logging in the configuration file to track cache operation failures in Laravel logs.

```php
// In config/cache-ui-laravel.php or .env
'enable_logging' => true,

// Errors will be logged to Laravel's log file
// Example log entry:
// [2024-01-01 12:00:00] local.WARNING: Cache UI: Failed to retrieve keys from store 'redis': Connection timeout
```

--------------------------------

### forever($key, $value) signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Signature of the `forever` method, which stores an item in the cache indefinitely. It delegates to `put($key, $value, 0)`.

```php
public function forever($key, $value): bool
```

--------------------------------

### forgetKey(string $store, string $key): bool

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/cache-ui-laravel.md

Deletes a single cache key from the specified store. Returns a boolean indicating success.

```APIDOC
## forgetKey(string $store, string $key): bool

### Description
Deletes a single cache key from the specified store. Returns `true` on success, `false` on failure or if the key does not exist.

### Signature
```php
public function forgetKey(string $store, string $key): bool
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$store` | `string` | Yes | - | The cache store to use. |
| `$key` | `string` | Yes | - | The cache key to delete. |

### Return Type
`bool` — `true` if the key was successfully forgotten, `false` otherwise.

### Throws / Rejects
Does not throw. All failure paths log (only when `enable_logging` is on) and return `false`.

### Usage Example
```php
use Abr4xas\CacheUiLaravel\Facades\CacheUiLaravel;

$deleted = CacheUiLaravel::forgetKey('redis', 'my-key');
if ($deleted) {
    // Key was deleted
} else {
    // Key not found or deletion failed
}
```
```

--------------------------------

### refreshIfOwned($key, $expectedOwner, $seconds) signature

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Signature of the `refreshIfOwned` method, which atomically refreshes the expiration of a cache key if it matches the expected owner. Used by `FileLock::refresh()`.

```php
public function refreshIfOwned($key, $expectedOwner, $seconds): bool
```

--------------------------------

### refreshIfOwned($key, $expectedOwner, $seconds): bool

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/key-aware-file-store.md

Atomically refreshes the expiration of a cache key if it matches the expected owner.

```APIDOC
## `refreshIfOwned($key, $expectedOwner, $seconds): bool`

### Description
Atomically refresh the expiration of a cache key **if** it matches the expected owner. Used by `FileLock::refresh()`.

### Signature

```php
public function refreshIfOwned($key, $expectedOwner, $seconds): bool
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$key` | `string` | Yes | — | The cache key |
| `$expectedOwner` | `mixed` | Yes | — | The owner the lock must currently belong to |
| `$seconds` | `int` | Yes | — | Number of seconds until the refreshed expiration |

### Return type

`bool` — `true` if the lock was refreshed (owned by `$expectedOwner` and not expired), `false` otherwise (wrong owner, expired, lock timeout, or unreadable payload).

### Behavior

Reads the payload under an exclusive `LockableFile` lock, compares the **unwrapped** owner against `$expectedOwner` (the parent compares the raw wrapper array, which never matches), and re-writes the payload re-wrapped if ownership matches.

### Usage example

```php
// Normally only reached indirectly via Illuminate\Cache\FileLock::refresh().
$refreshed = $store->refreshIfOwned('lock:reservation', $ownerToken, 300);
```
```

--------------------------------

### CacheUiLaravel::forgetKey

Source: https://github.com/abr4xas/cache-ui-laravel/blob/master/_autodocs/api-reference/facade-cache-ui-laravel.md

Deletes a specific cache key from a specified store. Returns a boolean indicating success.

```APIDOC
## CacheUiLaravel::forgetKey

### Description
Deletes a specific cache key from a specified store. Returns a boolean indicating success.

### Method
`forgetKey`

### Signature
php
public function forgetKey(string $key, ?string $store = null): bool


### Parameters
- **key** (string) - Required - The cache key to delete.
- **store** (?string) - Optional - The cache store name. Defaults to the default store.

### Returns
- **bool** - `true` on success, `false` if the key is empty or deletion fails.

### Example
php
$deleted = CacheUiLaravel::forgetKey('user_1_profile'); // delete from default store
$deleted = CacheUiLaravel::forgetKey('session_data', 'redis');

```
Tokens:
Raw