README

Small PHP library for rendering function-based prompt templates.

It lets you define template tags that call PHP functions (SPI implementations) with arguments.

Requirements

PHP >= 8.3
Composer

Installation

composer require adachsoft/prompt-template-lib

Basic usage

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AdachSoft\PromptTemplateLib\PublicApi\PromptEngineFactory;
use AdachSoft\PromptTemplateLib\Spi\PromptFunctionInterface;

$engine = PromptEngineFactory::createDefault(__DIR__);

$engine->registerFunction(new class implements PromptFunctionInterface {
    public function getName(): string
    {
        return 'user_name';
    }

    public function execute(array $arguments): string
    {
        return 'Example User';
    }
});

echo $engine->render("Hello <user_name>, today is <datetime('Y-m-d')>.");

Function tag syntax

By default the engine uses angle bracket tags like <user_name>.

To avoid conflicts with other markup (for example <role>...</role>), you can change the syntax using FunctionTagSyntax:

<function_name(...)> (default)
[function_name(...)]
{{function_name(...)}}

use AdachSoft\PromptTemplateLib\PublicApi\FunctionTagSyntax;
use AdachSoft\PromptTemplateLib\PublicApi\PromptEngineFactory;

$engine = PromptEngineFactory::createDefault(
    __DIR__,
    FunctionTagSyntax::SquareBrackets,
);

$template = '<role>system</role> Hello [user_name].';
echo $engine->render($template);

PTL directive comments (stripped)

You can add internal comments to your templates using PTL directive comments:

These comments are stripped before parsing and rendering. This means any function tags placed inside a PTL comment will not be executed.

Examples:

<!--ptl: This comment will be removed -->
Hello <user_name>!

Inline:

Hello <!--ptl: hidden note --> <user_name>!

Multi-line:

<!--ptl: hidden note
second line
third line -->
Hello <user_name>!

Standard functions

PromptEngineFactory::createDefault() registers standard functions:

datetime
- <datetime> or <datetime('Y-m-d')>
file_read
- <file_read('relative/path.txt')>
include
- <include('relative/path.txt')>
- Reads the file and renders its content as a template.
- Protects against recursive includes and enforces a max include depth.

Overriding standard functions

You can override any standard function (datetime, file_read, include) by passing your own implementations to the factory. When a custom function has the same name, the standard one is not registered.

use AdachSoft\PromptTemplateLib\PublicApi\FunctionTagSyntax;
use AdachSoft\PromptTemplateLib\PublicApi\PromptEngineFactory;

$engine = PromptEngineFactory::createDefault(
    __DIR__,
    FunctionTagSyntax::AngleBrackets,
    [new MyCustomDateTimeFunction()],
);

Context Management

The library supports a rendering context (key-value store) that can be accessed by custom functions.

Setting context

You can pass an initial context when creating the engine:

$engine = PromptEngineFactory::createDefault(
    __DIR__,
    initialContext: ['user_id' => 123, 'env' => 'production']
);

Or update it later:

$engine->setContextValue('user_id', 456);
$engine->setContext(['user_id' => 789, 'role' => 'admin']);

Accessing context in functions

To access the context inside a custom function, implement PromptEngineAwareFunctionInterface. The engine will automatically inject itself into your function.

use AdachSoft\PromptTemplateLib\PublicApi\PromptEngineInterface;
use AdachSoft\PromptTemplateLib\Spi\PromptEngineAwareFunctionInterface;

class MyContextAwareFunction implements PromptEngineAwareFunctionInterface
{
    private ?PromptEngineInterface $engine = null;

    public function setPromptEngine(PromptEngineInterface $engine): void
    {
        $this->engine = $engine;
    }

    public function getName(): string
    {
        return 'get_user_id';
    }

    public function execute(array $arguments): string
    {
        return (string) $this->engine->getContextValue('user_id', 'guest');
    }
}

Error handling

The library exposes dedicated exceptions in AdachSoft\PromptTemplateLib\PublicApi\Exception (for example UnknownFunctionException, TemplateSyntaxException, FunctionExecutionException).

License

MIT

adachsoft / prompt-template-lib

Maintainers

Details