Skip to main content

​
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="c6cb"

​
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="1ccc"

​
Config Resolution

When a prompt resolves its template engine config, it follows this priority:
  1. Instance config — set via withConfig() on the prompt instance
  2. templateDir compatibility — if $templateDir is set on the class, a Twig config with that resource path is created
  3. 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="8928"
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="cbdc"
You can also provide a specific base path: 
$config = TemplateEngineConfig::fromPreset('custom', basePath: __DIR__ . '/config');
// @doctest id="de7c"

​
Quick Reference

MethodPurpose
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