Configuration

By default, xprompt uses Twig with $templateDir paths set on individual prompt classes. For centralized control — shared resource paths, cache directories, or preset-based configuration — use TemplateEngineConfig.

Per-Prompt Config

The withConfig() method returns a clone of the prompt with the given config applied:

use Cognesy\Template\Config\TemplateEngineConfig;

$config = TemplateEngineConfig::twig(
    resourcePath: __DIR__ . '/prompts',
    cachePath: '/tmp/twig-cache',
);

$prompt = Analyze::make()->withConfig($config);
echo $prompt->render(content: $doc);
// @doctest id="8437"

Registry-Wide Config

Pass config to the PromptRegistry constructor. Every prompt retrieved via get() will have this config applied:

use Cognesy\Xprompt\PromptRegistry;
use Cognesy\Template\Config\TemplateEngineConfig;

$config = TemplateEngineConfig::twig(resourcePath: __DIR__ . '/prompts');

$registry = new PromptRegistry(config: $config);
$registry->register('analyze', Analyze::class);

$prompt = $registry->get('analyze');
// Uses the registry's config for template resolution
// @doctest id="801e"

Config Resolution

When a prompt resolves its template engine config, it follows this priority:

Instance config — set via withConfig() on the prompt instance
templateDir compatibility — if $templateDir is set on the class, a Twig config with that resource path is created
Default Twig — bare TemplateEngineConfig::twig() with no resource path

This means existing prompts with $templateDir continue to work unchanged.

Presets

Load configuration from YAML preset files using fromPreset():

$config = TemplateEngineConfig::fromPreset('my-templates');
// @doctest id="c876"

This searches for my-templates.yaml in the standard preset directories:

config/prompt/presets/
packages/templates/resources/config/prompt/presets/
vendor/cognesy/instructor-php/packages/templates/resources/config/prompt/presets/
vendor/cognesy/instructor-templates/resources/config/prompt/presets/
// @doctest id="ceaa"

You can also provide a specific base path:

$config = TemplateEngineConfig::fromPreset('custom', basePath: __DIR__ . '/config');
// @doctest id="ba2c"

Quick Reference

Method	Purpose
`TemplateEngineConfig::twig($resourcePath, $cachePath)`	Twig engine with paths
`TemplateEngineConfig::fromPreset($name)`	Load from YAML preset file
`TemplateEngineConfig::fromArray($data)`	Create from array
`$config->withOverrides($values)`	Merge overrides into existing config
`$prompt->withConfig($config)`	Clone prompt with config

06 variants and registry

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

07 configuration

Configuration

Per-Prompt Config

Registry-Wide Config

Config Resolution

Presets

Quick Reference

​Configuration

​Per-Prompt Config

​Registry-Wide Config

​Config Resolution

​Presets

​Quick Reference

Configuration

Per-Prompt Config

Registry-Wide Config

Config Resolution

Presets

Quick Reference