Prompts

The Prompt resource lets you fetch, create, list, and update prompts managed in Langfuse. Both text and chat prompt types are supported, including template compilation and fallback handling.

Access

$prompt = $langfuse->prompt();

Fetching prompts

Text prompt

$response = $langfuse->prompt()->text(promptName: 'my-prompt');

echo $response->prompt; // "Hello, {{name}}! Welcome to {{service}}."

Chat prompt

$response = $langfuse->prompt()->chat(promptName: 'my-chat-prompt');

foreach ($response->prompt as $message) {
    echo $message['role'] . ': ' . $message['content'];
}

Fetching a specific version or label

By default, the label configured on the Langfuse constructor is used (defaults to 'latest'). You can override this per call:

// By version number
$response = $langfuse->prompt()->text(promptName: 'my-prompt', version: 3);

// By label
$response = $langfuse->prompt()->chat(promptName: 'my-prompt', label: 'production');

Compiling templates

Both text and chat prompts support {{variable}} placeholders. Use compile() to replace them:

Text prompt

$compiled = $langfuse->prompt()
    ->text(promptName: 'greeting')
    ->compile(['name' => 'Tycho', 'service' => 'Langfuse']);

// "Hello, Tycho! Welcome to Langfuse."

Chat prompt

$compiled = $langfuse->prompt()
    ->chat(promptName: 'assistant')
    ->compile(['topic' => 'PHP']);

// [
//     ['role' => 'system', 'content' => 'You are an expert on PHP.'],
//     ['role' => 'user', 'content' => 'Tell me about PHP.'],
// ]

Fallbacks

If the API is unreachable or the prompt doesn't exist, you can provide a fallback value. This prevents exceptions from disrupting your application.

Text fallback

$response = $langfuse->prompt()->text(
    promptName: 'my-prompt',
    fallback: 'Default prompt text for {{name}}'
);

// Returns a FallbackPrompt that also supports compile()
$compiled = $response->compile(['name' => 'Tycho']);

Chat fallback

$response = $langfuse->prompt()->chat(
    promptName: 'my-chat-prompt',
    fallback: [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user', 'content' => 'Hello'],
    ]
);

When no fallback is provided

If the prompt is not found and no fallback is given, null is returned:

$response = $langfuse->prompt()->text(promptName: 'nonexistent');
// null

Creating prompts

Text prompt

use DIJ\Langfuse\PHP\Enums\PromptType;

$response = $langfuse->prompt()->create(
    promptName: 'greeting',
    prompt: 'Hello, {{name}}!',
    type: PromptType::TEXT,
    labels: ['production', 'latest'],
    config: ['temperature' => 0.7],
    tags: ['onboarding'],
    commitMessage: 'Initial greeting prompt',
);

echo $response->id;      // "clx..."
echo $response->version; // 1

Chat prompt

$response = $langfuse->prompt()->create(
    promptName: 'assistant',
    prompt: [
        ['role' => 'system', 'content' => 'You are a {{role}}.'],
        ['role' => 'user', 'content' => '{{question}}'],
    ],
    type: PromptType::CHAT,
    labels: ['staging'],
);

Listing prompts

list() returns a Generator that automatically paginates through all results. No need to handle pages manually.

foreach ($langfuse->prompt()->list() as $item) {
    echo $item->name;
    echo implode(', ', $item->labels);
    echo implode(', ', $item->versions);
}

Filtering

// Filter by name
foreach ($langfuse->prompt()->list(name: 'greeting') as $item) { ... }

// Filter by tag
foreach ($langfuse->prompt()->list(tag: 'onboarding') as $item) { ... }

// Filter by label
foreach ($langfuse->prompt()->list(label: 'production') as $item) { ... }

// Filter by date range
foreach ($langfuse->prompt()->list(
    fromUpdatedAt: '2025-01-01T00:00:00Z',
    toUpdatedAt: '2025-12-31T23:59:59Z',
) as $item) { ... }

Updating prompt labels

Reassign labels to a specific prompt version:

$response = $langfuse->prompt()->update(
    promptName: 'greeting',
    version: 2,
    labels: ['production', 'latest'],
);

echo $response->labels; // ['production', 'latest']

Error handling

Scenario	Behavior
API unreachable	Returns fallback if provided, null otherwise
Prompt not found	Returns fallback if provided, null otherwise
Wrong prompt type (e.g. fetching text but prompt is chat)	Throws InvalidPromptTypeException

use DIJ\Langfuse\PHP\Exceptions\InvalidPromptTypeException;

try {
    $langfuse->prompt()->text(promptName: 'my-chat-prompt');
} catch (InvalidPromptTypeException $e) {
    // "my-chat-prompt returns a prompt of type chat, but expected text."
}

Method reference

Method	Parameters	Returns
text()	string $promptName, ?int $version, ?string $label, ?string $fallback	TextPromptResponse|FallbackPrompt|null
chat()	string $promptName, ?int $version, ?string $label, ?array $fallback	ChatPromptResponse|FallbackPrompt|null
list()	?string $name, ?int $version, ?string $label, ?string $tag, ?string $fromUpdatedAt, ?string $toUpdatedAt	Generator<PromptListItem>
create()	string $promptName, string|array $prompt, PromptType $type, ?array $labels, ?array $config, ?array $tags, ?string $commitMessage	TextPromptResponse|ChatPromptResponse
update()	string $promptName, int $version, array $labels	TextPromptResponse|ChatPromptResponse