> ## Documentation Index
> Fetch the complete documentation index at: https://deck.promptphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> All available configuration options for Deck by PromptPHP.

## Introduction

Deck by PromptPHP ships with sensible defaults that work out of the box. Like most Laravel packages, all configuration lives in `config/deck.php` and every option can be overridden via environment variables for deployment flexibility.

## Publishing the configuration

Publish the configuration file using the Artisan command:

```bash theme={null}
php artisan vendor:publish --tag=deck-config
```

This copies the package's default configuration to `config/deck.php` in your application. Once published, you can modify it freely.

## Prompts path

The `path` option determines where your versioned prompt files are stored on disk:

```php theme={null}
'path' => resource_path('prompts'),
```

By default, prompts live in `resources/prompts/`. You can change this to any directory:

```php theme={null}
'path' => base_path('ai/prompts'),
```

The directory is created automatically when you first run `php artisan make:prompt`.

## File extension

The `extension` option controls the file extension used for prompt template files:

```php theme={null}
'extension' => 'md',
```

Markdown (`.md`) is the default and recommended for readability. You can change it to any extension:

| Value       | Result                               |
| ----------- | ------------------------------------ |
| `md`        | `system.md`, `user.md`               |
| `txt`       | `system.txt`, `user.txt`             |
| `blade.php` | `system.blade.php`, `user.blade.php` |
| `prompt`    | `system.prompt`, `user.prompt`       |

<Note>
  Changing the extension only affects newly generated files. Existing prompt
  files are not renamed automatically.
</Note>

## Versioning strategy

The `versioning` option controls how prompt versions are organised:

```php theme={null}
'versioning' => 'directory',
```

Currently, only the `directory` strategy is supported. Each version is stored in its own sub-directory (`v1/`, `v2/`, etc.) within the prompt's folder:

```
resources/prompts/order-summary/
├── metadata.json          # "active_version": 1
├── v1/                    # live
│   ├── metadata.json
│   └── system.md
└── v2/                    # drafted, not serving traffic yet
    ├── metadata.json
    ├── system.md
    └── user.md
```

## Cache

The `cache` section controls prompt caching behaviour. Caching avoids repeated filesystem reads by storing loaded prompts in your configured cache store.

```php theme={null}
'cache' => [
    'enabled' => env('DECK_CACHE_ENABLED', env('APP_DEBUG', false) ? false : true),
    'store'   => env('DECK_CACHE_STORE', 'file'),
    'ttl'     => env('DECK_CACHE_TTL', 3600),
    'prefix'  => env('CACHE_PREFIX', env('DECK_CACHE_PREFIX', 'deck:')),
],
```

### Enabling / disabling

```php theme={null}
'enabled' => env('DECK_CACHE_ENABLED', env('APP_DEBUG', false) ? false : true),
```

By default, caching is **disabled** when `APP_DEBUG=true` (local development) and **enabled** in production. This ensures that file changes are picked up immediately during development.

Override via your `.env`:

```dotenv theme={null}
DECK_CACHE_ENABLED=false   # Always disable caching
DECK_CACHE_ENABLED=true    # Always enable caching
```

### Cache store

```php theme={null}
'store' => env('DECK_CACHE_STORE', 'file'),
```

The cache store to use. Must match a store name defined in your `config/cache.php`. Common values:

| Store       | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `file`      | File-based cache (default). Simple, no extra dependencies.    |
| `redis`     | Redis cache. Fast, shared across workers.                     |
| `memcached` | Memcached. Similar to Redis.                                  |
| `array`     | In-memory only. Cleared on each request (useful for testing). |

### TTL

```php theme={null}
'ttl' => env('DECK_CACHE_TTL', 3600),
```

Cache time-to-live in **seconds**. After this duration, the prompt is re-read from disk on the next access. Default is 3600 seconds (1 hour).

### Cache key prefix

```php theme={null}
'prefix' => env('CACHE_PREFIX', env('DECK_CACHE_PREFIX', 'deck:')),
```

The prefix prepended to all cache keys. The final cache key follows the pattern: `{prefix}{name}.v{version}`.

For example, with the default prefix:

```
deck:order-summary.v2
```

## Database tracking

The `tracking` section controls whether prompt versions and executions are logged to the database.

```php theme={null}
'tracking' => [
    'enabled'    => env('DECK_TRACKING_ENABLED', env('APP_DEBUG', false) ? false : true),
    'connection' => env('DECK_DB_CONNECTION'),
],
```

### Enabling / disabling

```php theme={null}
'enabled' => env('DECK_TRACKING_ENABLED', env('APP_DEBUG', false) ? false : true),
```

Like caching, tracking is **disabled** in debug mode and **enabled** in production by default. When enabled:

* **Version activation** is stored in the `prompt_versions` database table (instead of `metadata.json`).
* **Execution tracking** via `Deck::track()` inserts records into the `prompt_executions` table.

<Warning>
  You must publish and run the migrations before enabling tracking. See
  [Installation — Publishing
  migrations](/getting-started/installation#publishing-migrations).
</Warning>

### Database connection

```php theme={null}
'connection' => env('DECK_DB_CONNECTION'),
```

The database connection to use for tracking tables. Set to `null` (the default) to use your application's default connection. Set to a named connection from `config/database.php` if you want tracking data stored on a separate database:

```dotenv theme={null}
DECK_DB_CONNECTION=analytics
```

## AI SDK integration

```php theme={null}
'scaffold_on_make_agent' => env('DECK_SCAFFOLD_ON_MAKE_AGENT', true),
```

When the [Laravel AI SDK](https://laravel.com/docs/ai-sdk) is installed and this option is `true`, Deck automatically creates a matching prompt directory whenever you run `php artisan make:agent`. See the [AI SDK Integration](/integrations/ai-sdk) documentation for details.

Set to `false` to disable automatic scaffolding:

```dotenv theme={null}
DECK_SCAFFOLD_ON_MAKE_AGENT=false
```

## Full configuration reference

| Key                      | Type           | Default                         | Description                                   |
| ------------------------ | -------------- | ------------------------------- | --------------------------------------------- |
| `path`                   | `string`       | `resource_path('prompts')`      | Base directory where prompt files are stored. |
| `extension`              | `string`       | `md`                            | File extension for prompt template files.     |
| `versioning`             | `string`       | `directory`                     | Versioning strategy (`directory`).            |
| `cache.enabled`          | `bool`         | `true` (prod) / `false` (debug) | Enable prompt caching.                        |
| `cache.store`            | `string`       | `file`                          | Cache store name.                             |
| `cache.ttl`              | `int`          | `3600`                          | Cache TTL in seconds.                         |
| `cache.prefix`           | `string`       | `deck:`                         | Cache key prefix.                             |
| `tracking.enabled`       | `bool`         | `true` (prod) / `false` (debug) | Enable database tracking.                     |
| `tracking.connection`    | `string\|null` | `null`                          | Database connection name.                     |
| `scaffold_on_make_agent` | `bool`         | `true`                          | Auto-scaffold prompts on `make:agent`.        |

## Environment variables reference

| Variable                      | Default | Description                       |
| ----------------------------- | ------- | --------------------------------- |
| `DECK_CACHE_ENABLED`          | Dynamic | Enable/disable caching.           |
| `DECK_CACHE_STORE`            | `file`  | Cache store to use.               |
| `DECK_CACHE_TTL`              | `3600`  | Cache TTL in seconds.             |
| `DECK_CACHE_PREFIX`           | `deck:` | Cache key prefix.                 |
| `DECK_TRACKING_ENABLED`       | Dynamic | Enable/disable database tracking. |
| `DECK_DB_CONNECTION`          | `null`  | Database connection for tracking. |
| `DECK_SCAFFOLD_ON_MAKE_AGENT` | `true`  | Auto-scaffold on `make:agent`.    |