Prompt Deck Laravel Package

title: "API reference" description: "Complete class and method reference for Deck by PromptPHP."

PromptManager

PromptPHP\Deck\PromptManager

The core service class responsible for loading, caching, versioning, and tracking prompts. Registered as a singleton in the service container.

Constructor

public function __construct(
    string $basePath,
    string $extension,
    Cache $cache,
    Config $config
)

Methods

get(string $name, ?int $version = null): PromptTemplate

Load a prompt by name and optional version. If version is null, the active version is resolved automatically. Returns a PromptTemplate instance.

Caches the loaded prompt if caching is enabled.

Throws: PromptNotFoundException if the prompt does not exist. InvalidVersionException if the specified version does not exist.

$prompt = $manager->get('order-summary');       // active version
$prompt = $manager->get('order-summary', 2);    // specific version

active(string $name): PromptTemplate

Load the active version of a prompt. Equivalent to calling get($name) without a version.

$prompt = $manager->active('order-summary');

versions(string $name): array

List all versions for a prompt. Returns an array of version info sorted in ascending order.

Throws: PromptNotFoundException if the prompt directory does not exist.

$versions = $manager->versions('order-summary');
// [
//     ['version' => 1, 'path' => '/path/to/v1', 'metadata' => [...]],
//     ['version' => 2, 'path' => '/path/to/v2', 'metadata' => [...]],
// ]

activate(string $name, int $version): bool

Activate a specific version of a prompt. Returns true on success.

• With tracking enabled: Updates the prompt_versions database table.
• Without tracking: Writes to metadata.json in the prompt directory.

$manager->activate('order-summary', 2);

track(string $promptName, int $version, array $data): void

Record a prompt execution for tracking. No-op if tracking is disabled.

$manager->track('order-summary', 2, [
    'input'    => ['message' => 'Hello'],
    'output'   => 'Hi there!',
    'tokens'   => 50,
    'latency'  => 120.5,
    'cost'     => 0.001,
    'model'    => 'gpt-4o',
    'provider' => 'openai',
    'feedback' => ['rating' => 5],
]);

PromptTemplate

PromptPHP\Deck\PromptTemplate

Represents a loaded prompt with its roles, metadata, and interpolation capabilities. Implements Illuminate\Contracts\Support\Arrayable.

Constructor

public function __construct(
    protected string $name,
    protected int $version,
    protected array $roles = [],
    protected array $metadata = [],
)

Methods

role(string $role, array $variables = []): string

Render a role's content with variable interpolation. Returns an empty string if the role does not exist.

$content = $prompt->role('system', ['tone' => 'friendly']);

raw(string $role): string

Get the raw content for a role without interpolation. Returns an empty string if the role does not exist.

$template = $prompt->raw('system');

has(string $role): bool

Check whether a specific role exists in this prompt.

if ($prompt->has('assistant')) {
    // ...
}

roles(): array

Get all available role names.

$prompt->roles(); // ['system', 'user', 'assistant']

toMessages(array $variables = [], ?array $only = null): array

Build a messages array for AI API consumption. Returns an array of ['role' => '...', 'content' => '...'] entries.

$messages = $prompt->toMessages(['tone' => 'concise'], ['system', 'user']);

version(): int

Get the resolved version number.

$prompt->version(); // 2

name(): string

Get the prompt name.

$prompt->name(); // 'order-summary'

metadata(): array

Get the prompt metadata. Returns an empty array if no metadata is defined.

$prompt->metadata(); // ['description' => '...', 'variables' => [...]]

toArray(): array

Convert the prompt to an array (implements Arrayable).

$prompt->toArray();
// ['name' => '...', 'version' => 2, 'roles' => [...], 'metadata' => [...]]

__call(string $method, array $parameters): string

Dynamic role access via method call. Any method name is treated as a role name.

$prompt->system(['tone' => 'friendly']);   // renders 'system' role
$prompt->assistant(['context' => '...']);  // renders 'assistant' role
$prompt->custom_role();                    // renders 'custom_role' role

Deck facade

PromptPHP\Deck\Facades\Deck

Static proxy to the PromptManager singleton.

Available methods

HasPromptTemplate trait

PromptPHP\Deck\Concerns\HasPromptTemplate

Trait for integrating Deck templates with Laravel AI SDK agents.

Methods

promptName(): string

Get the prompt name. Defaults to the kebab-cased class name (e.g. SalesCoach → sales-coach). Override to use a custom name.

promptVersion(): ?int

Get the prompt version to load. Returns null by default (active version). Override to pin to a specific version.

promptVariables(): array

Get variables for prompt template interpolation. Returns an empty array by default. Override to provide dynamic context.

promptTemplate(): PromptTemplate

Get the loaded PromptTemplate instance. Cached for the lifetime of the object.

instructions(): Stringable|string

Get the system instructions from the prompt template. Loads the system role and interpolates promptVariables(). Satisfies the AI SDK Agent contract.

promptMessages(?array $only = null): array

Get prompt roles as messages. By default returns all roles except system. Returns Message[] when the AI SDK is installed, or raw ['role' => '...', 'content' => '...'] arrays otherwise.

forgetPromptTemplate(): static

Clear the cached PromptTemplate, forcing a fresh load on next access. Returns $this for fluent chaining.

TrackPromptMiddleware

PromptPHP\Deck\Ai\TrackPromptMiddleware

Laravel AI SDK agent middleware that automatically tracks prompt executions.

Methods

handle(mixed $prompt, Closure $next): mixed

Handle the incoming agent prompt. Measures latency and records execution data using PromptManager::track() after the response completes.

Only tracks agents that use the HasPromptTemplate trait (i.e. agents with a promptName() method).

AfterMakeAgent listener

PromptPHP\Deck\Listeners\AfterMakeAgent

Listens for the Laravel AI SDK's make:agent command and automatically scaffolds a corresponding Deck prompt.

Methods

handle(CommandFinished $event): void

Handle the CommandFinished event. Only acts on successful make:agent commands. Converts the agent name to kebab-case and runs make:prompt if the prompt doesn't already exist.

Models

PromptVersion

PromptPHP\Deck\Models\PromptVersion

PromptExecution

PromptPHP\Deck\Models\PromptExecution

Exceptions

All Deck exceptions extend the base DeckException class.

DeckException

PromptPHP\Deck\Exceptions\DeckException

Abstract base exception for all Deck errors. Extends PHP's Exception class.

PromptNotFoundException

PromptPHP\Deck\Exceptions\PromptNotFoundException

Thrown when a prompt directory does not exist.

InvalidVersionException

PromptPHP\Deck\Exceptions\InvalidVersionException

Thrown when a requested version does not exist or no versions are found.

ConfigurationException

PromptPHP\Deck\Exceptions\ConfigurationException

Thrown when Deck configuration is invalid.

PromptRenderingException

PromptPHP\Deck\Exceptions\PromptRenderingException

Thrown when prompt rendering fails.