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:

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:

'path' => resource_path('prompts'),

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

'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:

'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

Changing the extension only affects newly generated files. Existing prompt files are not renamed automatically.

Versioning strategy

The versioning option controls how prompt versions are organised:

'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.

'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

'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:

DECK_CACHE_ENABLED=false   # Always disable caching
DECK_CACHE_ENABLED=true    # Always enable caching

Cache store

'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

'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

'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.

'tracking' => [
    'enabled'    => env('DECK_TRACKING_ENABLED', false),
    'connection' => env('DECK_DB_CONNECTION'),
],

Enabling / disabling

Tracking is off by default, because it needs database tables that are published in a separate step. Turning it on takes three steps:

1. Publish the migrations

   php artisan vendor:publish --tag=deck-migrations
   
2. Run them

   php artisan migrate
   
3. Enable the flag

   DECK_TRACKING_ENABLED=true
   

When enabled:

• Version activation is recorded in the prompt_versions table as well as metadata.json, and the table takes precedence. See Tracking — Activation precedence.
• Execution tracking via Deck::track() inserts records into the prompt_executions table.

Prompt rendering never depends on tracking. If the tables are missing or the database is unreachable, Deck falls back to metadata.json and logs a warning once, rather than failing. Deck::track() never throws at all — it runs after a completed AI call, and no analytics failure is worth discarding that response.

Database connection

'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:

DECK_DB_CONNECTION=analytics

AI SDK integration

'scaffold_on_make_agent' => env('DECK_SCAFFOLD_ON_MAKE_AGENT', true),

When the Laravel 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 documentation for details.

Set to false to disable automatic scaffolding:

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.