adachsoft/prompt-template-lib

PHP library for rendering function-based prompt templates with extensible SPI and safe file access

v0.2.1 2025-12-24 18:22 UTC

Requires

• php: >=8.3
• adachsoft/normalized-safe-path: ^0.1.0

Requires (Dev)

• adachsoft/php-code-style: ^0.2.1
• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0

MIT

• Arkadiusz Adach

• php
• template
• tags
• prompt
• spi
• llm

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