Introduction

Deck by PromptPHP helps you organise your AI Agents instructions as structured, version-controlled files, making it easy to iterate, compare, and activate prompt versions across your Laravel / PHP application.

It provides variable interpolation, performance tracking, A/B testing, and optional seamless integration with the Laravel AI SDK.

Quick start

Get up and running with Deck in minutes.

Installation guide

Install, configure, and verify Deck in your Laravel project.

Quick usage

Creating a prompt

After installing (installation guide), use the Artisan command to create a versioned prompt:

php artisan make:prompt order-summary

This creates the following structure:

resources/prompts/
└── order-summary/
    ├── v1/
        └── system.md
    └── metadata.json

Edit resources/prompts/order-summary/v1/system.md with your prompt content. Use {{ $variable }} syntax for dynamic values:

You are a {{ $tone }} customer service agent.
Summarise the following order for the customer: {{ $order }}.

Using a prompt

Load and render prompts with the Deck facade:

use PromptPHP\Deck\Facades\Deck;

// Load the active version of a prompt.
$prompt = Deck::get('order-summary');

// Render a role with variables.
$prompt->system(['tone' => 'friendly', 'order' => $orderDetails]);
// "You are a friendly customer service agent. Summarise the following order..."

// Build a messages array ready for any chat-completion API.
$messages = $prompt->toMessages(['tone' => 'friendly', 'order' => $orderDetails]);
// [['role' => 'system', 'content' => '...']]

Versioning

Create a new version of an existing prompt:

php artisan make:prompt order-summary
# Automatically creates v2, v3, etc.

Activate a specific version:

php artisan prompt:activate order-summary v2

# or

php artisan prompt:activate order-summary 2

Or load a specific version programmatically:

$prompt = Deck::get('order-summary', 'v2');

Laravel AI SDK integration

If you use the Laravel AI SDK, add the HasPromptTemplate trait to your agents. This way, you do not need to define the instructions() method as it is provided automatically.

use PromptPHP\Deck\Concerns\HasPromptTemplate;

class OrderAgent extends Agent
{
    use HasPromptTemplate;

    // instructions() and promptMessages() are provided automatically.
}

Running make:agent will also auto-scaffold a matching prompt directory.

Key features

Versioned prompts

Store prompts as files on disk with directory-based versioning. Load, render, and switch between versions effortlessly.

Prompt generator

Scaffold versioned, role-based prompt structures with the make:prompt Artisan command.

Variable interpolation

Use {{ $variable }} syntax in prompt templates for dynamic content rendering.

AI API messages

Convert prompts to messages arrays ready for OpenAI, Anthropic, and other chat-completion APIs.

Laravel AI SDK

First-class integration with Laravel AI SDK — auto-scaffolding, traits, and middleware.

Performance tracking

Log executions with token usage, latency, cost, and feedback for A/B testing and monitoring.

Explore the docs

Configuration

Customise caching, tracking, and file settings.

Artisan commands

Five commands for managing prompts from the CLI.

Testing

Strategies and examples for testing prompts.