Installation

Requirements, setup, and environment configuration for Deck by PromptPHP.

Requirements

Deck by PromptPHP has the following requirements:

Dependency	Version
PHP	^8.2
Laravel	^11.0 ++

The sebastian/diff package is required and is used for the prompt:diff command. It may conflict with your PHPUnit/Pest PHP installation so you may need to upgrade these dependencies to the latest version.

Optional dependencies

Package	Purpose
laravel/ai	Enables deep integration with Laravel AI SDK agents to support automatic instructions loading, prompt version tracking in conversations, and auto-scaffolding prompts when creating agents.

Installing Deck by PromptPHP

Install the package via Composer:

composer require promptphp/deck

If you have disabled auto-discovery, you will need to manually register the service provider and facade. See the Manual discovery section for details.

Publishing the configuration

Publish the configuration file to customise Deck’s behaviour:

php artisan vendor:publish --tag=deck-config

This creates config/deck.php in your application. See the Configuration documentation for a full reference of all available options.

Publishing migrations

If you plan to use database tracking for prompt versions and execution logging, publish and run the migrations:

php artisan vendor:publish --tag=deck-migrations
php artisan migrate

This creates two tables:

Table	Purpose
prompt_versions	Stores prompt version records and tracks which version is active.
prompt_executions	Logs individual prompt executions with tokens, latency, cost, and feedback data.

Database tracking is optional. Deck works fully without it as version activation falls back to metadata.json files, and execution tracking is simply disabled.

If you prefer, you may publish both the configuration and migration files by running a single command:

php artisan vendor:publish --provider="PromptPHP\Deck\Providers\DeckServiceProvider"

Environment variables

Add the following to your .env file to configure Deck’s runtime behaviour:

# Cache
DECK_CACHE_ENABLED=true          # Enable/disable prompt caching (default: true in production, false when APP_DEBUG=true)
DECK_CACHE_STORE=file            # Cache store to use (file, redis, memcached, etc.)
DECK_CACHE_TTL=3600              # Cache time-to-live in seconds
DECK_CACHE_PREFIX=prompt-deck:   # Cache key prefix

# Database Tracking
DECK_TRACKING_ENABLED=true       # Enable/disable database tracking (default: true in production, false when APP_DEBUG=true)
DECK_DB_CONNECTION=              # Database connection name (null for default)

# AI SDK Integration
DECK_SCAFFOLD_ON_MAKE_AGENT=true # Auto-create prompt when running `make:agent`

All environment variables are optional as sensible defaults are provided.

Verifying the installation

After installation, verify everything is working:

# Create your first prompt.
php artisan make:prompt hello-world

# List all prompts.
php artisan prompt:list

# Test the prompt.
php artisan prompt:test hello-world

You should see the scaffolded prompt structure in resources/prompts/hello-world/.

Manual discovery

The package uses Laravel’s auto-discovery, so the service provider and facade are registered automatically. No manual registration is needed.

If you have disabled auto-discovery, add the provider and facade to your bootstrap/providers.php (Laravel 11+) or config/app.php:

// bootstrap/providers.php (Laravel 11+)
return [
    // ...
    PromptPHP\Deck\Providers\DeckServiceProvider::class,
];

Or for config/app.php:

'providers' => [
    // ...
    PromptPHP\Deck\Providers\DeckServiceProvider::class,
],

'aliases' => [
    // ...
    'Deck' => PromptPHP\Deck\Facades\Deck::class,
],

What’s next?

Configuration

Customise Deck’s behaviour.

Creating prompts

Learn the full make:prompt command.

Working with prompts

Load, render, and manage prompts in your code.

Laravel AI SDK

Use prompts with AI agents.