API reference - 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
)

Parameter	Type	Description
`$basePath`	`string`	Base directory where prompt files are stored.
`$extension`	`string`	File extension for prompt templates (e.g. `md`).
`$cache`	`Illuminate\Contracts\Cache\Repository`	Cache store instance.
`$config`	`Illuminate\Contracts\Config\Repository`	Configuration repository.

Methods

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

Load a prompt by name and optional version. Accepts 2, '2', or 'v2'. 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, string|int $version): bool`

Activate a specific version of a prompt. Returns true on success. Accepts the same version formats as get(), so 2, '2', and 'v2' are equivalent. A version that cannot be parsed throws InvalidVersionException.

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

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

`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 = [],
)

Parameter	Type	Description
`$name`	`string`	The prompt name.
`$version`	`int`	The resolved version number.
`$roles`	`array<string, string>`	Role name → raw content map.
`$metadata`	`array`	Prompt metadata from `metadata.json`.

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.

Parameter	Type	Description
`$variables`	`array`	Variables to interpolate into every role.
`$only`	`array\|null`	Limit to these roles (preserves order). `null` = all roles.

$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: the prompt’s root metadata.json merged with the version’s own metadata.json, version-level keys winning. The active_version key is excluded. 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

Method	Returns	Description
`Deck::get(string $name, string\|int\|null $version = null)`	`PromptTemplate`	Load a prompt by name and optional version.
`Deck::active(string $name)`	`PromptTemplate`	Load the active version of a prompt.
`Deck::versions(string $name)`	`array`	List all versions for a prompt.
`Deck::activate(string $name, string\|int $version)`	`bool`	Activate a specific version.
`Deck::track(string $name, int $version, array $data)`	`void`	Record a prompt execution.

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.

Parameter	Type	Description
`$only`	`array\|null`	Limit to specific roles. `null` = all non-system roles.

`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

Attribute	Type	Cast	Description
`name`	`string`	—	Prompt name.
`version`	`int`	`integer`	Version number.
`system_prompt`	`string\|null`	—	System prompt content.
`user_prompt`	`string`	—	User prompt content.
`metadata`	`array\|null`	`array`	Version metadata.
`is_active`	`bool`	`boolean`	Whether this is the active version.

PromptExecution

PromptPHP\Deck\Models\PromptExecution

Attribute	Type	Cast	Description
`prompt_name`	`string`	—	Prompt name.
`prompt_version`	`int`	`integer`	Version number.
`input`	`array\|null`	`array`	Input data (JSON).
`output`	`string\|null`	—	Response text.
`tokens`	`int\|null`	`integer`	Total tokens.
`latency_ms`	`int\|null`	`integer`	Latency in milliseconds.
`cost`	`string\|null`	`decimal:6`	Cost (6 decimal places).
`model`	`string\|null`	—	AI model used.
`provider`	`string\|null`	—	AI provider.
`feedback`	`array\|null`	`array`	Feedback data (JSON).

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.

Factory Method	Description
`named(string $name): self`	Creates exception with message: `"Prompt [{name}] not found."`

InvalidVersionException

PromptPHP\Deck\Exceptions\InvalidVersionException Thrown when a requested version does not exist or no versions are found.

Factory Method	Description
`forPrompt(string $name, int $version): self`	Creates exception with message: `"Version {version} for prompt [{name}] does not exist."`
`noVersions(string $name): self`	Creates exception with message: `"No versions found for prompt [{name}]."`

ConfigurationException

PromptPHP\Deck\Exceptions\ConfigurationException Thrown when Deck configuration is invalid.

Factory Method	Description
`invalidPath(string $path): self`	Creates exception with message: `"Prompts path [{path}] is not a directory or is not writable."`

PromptRenderingException

PromptPHP\Deck\Exceptions\PromptRenderingException Thrown when prompt rendering fails.

Factory Method	Description
`dueToMissingVariable(string $variable, string $promptName): self`	Creates exception with message: `"Cannot render prompt [{promptName}]: missing required variable '{variable}'."`

​PromptManager

​Constructor

​Methods

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

​active(string $name): PromptTemplate

​versions(string $name): array

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

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

​PromptTemplate

​Constructor

​Methods

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

​raw(string $role): string

​has(string $role): bool

​roles(): array

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

​version(): int

​name(): string

​metadata(): array

​toArray(): array

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

​Deck facade

​Available methods

​HasPromptTemplate trait

​Methods

​promptName(): string

​promptVersion(): ?int

​promptVariables(): array

​promptTemplate(): PromptTemplate

​instructions(): Stringable|string

​promptMessages(?array $only = null): array

​forgetPromptTemplate(): static

​TrackPromptMiddleware

​Methods

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

​AfterMakeAgent listener

​Methods

​handle(CommandFinished $event): void

​Models

​PromptVersion

​PromptExecution

​Exceptions

​DeckException

​PromptNotFoundException

​InvalidVersionException

​ConfigurationException

​PromptRenderingException

PromptManager

Constructor

Methods

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

`active(string $name): PromptTemplate`

`versions(string $name): array`

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

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

PromptTemplate

Constructor

Methods

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

`raw(string $role): string`

`has(string $role): bool`

`roles(): array`

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

`version(): int`

`name(): string`

`metadata(): array`

`toArray(): array`

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

Deck facade

Available methods

HasPromptTemplate trait

Methods

`promptName(): string`

`promptVersion(): ?int`

`promptVariables(): array`

`promptTemplate(): PromptTemplate`

`instructions(): Stringable|string`

`promptMessages(?array $only = null): array`

`forgetPromptTemplate(): static`

TrackPromptMiddleware

Methods

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

AfterMakeAgent listener

Methods

`handle(CommandFinished $event): void`

Models

PromptVersion

PromptExecution

Exceptions

DeckException

PromptNotFoundException

InvalidVersionException

ConfigurationException

PromptRenderingException