> ## Documentation Index
> Fetch the complete documentation index at: https://deck.promptphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> 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

```php theme={null}
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](/core/prompts#version-resolution-order) 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.

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
$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

```php theme={null}
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.

```php theme={null}
$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.

```php theme={null}
$template = $prompt->raw('system');
```

#### `has(string $role): bool`

Check whether a specific role exists in this prompt.

```php theme={null}
if ($prompt->has('assistant')) {
    // ...
}
```

#### `roles(): array`

Get all available role names.

```php theme={null}
$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. |

```php theme={null}
$messages = $prompt->toMessages(['tone' => 'concise'], ['system', 'user']);
```

#### `version(): int`

Get the resolved version number.

```php theme={null}
$prompt->version(); // 2
```

#### `name(): string`

Get the prompt name.

```php theme={null}
$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.

```php theme={null}
$prompt->metadata(); // ['description' => '...', 'variables' => [...]]
```

#### `toArray(): array`

Convert the prompt to an array (implements `Arrayable`).

```php theme={null}
$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.

```php theme={null}
$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}'."` |