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:

• <!--ptl: ... -->

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()],
);

Error handling

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

License

MIT