Inscribe

A fluent template builder for composing text from reusable parts. Build AI prompts, email bodies, notifications, and any structured text by combining modular template files.

Why Inscribe?

Building complex text output often means concatenating strings, managing conditionals, and losing track of what goes where. Inscribe solves this by letting you:

• Compose text from reusable parts - Write each section once, use it everywhere
• Keep templates in separate files - Easy to find, edit, and version control
• Use placeholders with context - Global defaults with local overrides
• Build fluently - Chain methods for readable, maintainable code

Perfect for:

• AI Prompts - Combine system instructions, context, and user input
• Email Templates - Mix headers, bodies, and signatures
• Notifications - Assemble messages from reusable blocks
• Any structured text - Documentation, reports, messages

Quick Example

Instead of this:

$prompt = "You are a helpful assistant.\n\n";
$prompt .= "Context: The user is asking about {$topic}.\n\n";
$prompt .= "User question: {$question}\n\n";
$prompt .= "Please provide a detailed answer.";

You write templates:

<!-- resources/inscribe/ai/system.md -->
You are a helpful assistant.

<!-- resources/inscribe/ai/context.md -->
Context: The user is asking about {{topic}}.

<!-- resources/inscribe/ai/instruction.md -->
Please provide a detailed answer.

And compose them:

use SerhiiLabs\Inscribe\Facades\Inscribe;

$prompt = Inscribe::make()
    ->context(['topic' => 'Laravel'])
    ->include('ai.system')
    ->include('ai.context')
    ->raw('User question: {{question}}', ['question' => $userInput])
    ->include('ai.instruction')
    ->build();

Clean, readable, and each piece is reusable.

Requirements

• PHP 8.3+
• Laravel 12.x

Installation

composer require serhiilabs/inscribe

The package auto-registers with Laravel. No additional setup required.

Configuration

Publish the config file (optional):

php artisan vendor:publish --tag=inscribe-config

Usage

Basic Usage

Create template files in your templates directory:

<!-- resources/inscribe/email/header.md -->
Hello, {{name}}!

<!-- resources/inscribe/email/footer.md -->
Best regards,
{{sender}}

Build your text:

use SerhiiLabs\Inscribe\Contracts\TemplateBuilderInterface;

class EmailService
{
    public function __construct(
        private TemplateBuilderInterface $templates,
    ) {}

    public function buildEmail(string $name): string
    {
        return $this->templates->make()
            ->context(['sender' => 'Support Team'])
            ->include('email.header', ['name' => $name])
            ->include('email.footer')
            ->build();
    }
}

Dot Notation

Template names map to file paths:

email.header              -> resources/inscribe/email/header.md
email.campaigns.welcome   -> resources/inscribe/email/campaigns/welcome.md
notifications.alert       -> resources/inscribe/notifications/alert.md

Template names must:

• Start with a letter or underscore
• Contain only alphanumeric characters, underscores, hyphens
• Use dots as path separators

Context (Placeholders)

Use {{placeholder}} syntax in templates. Provide values via context.

Global context only - applies to all parts:

$text = Inscribe::make()
    ->context(['name' => 'John', 'company' => 'Acme'])
    ->include('greeting')   // Has access to name and company
    ->include('signature')  // Has access to name and company
    ->build();

Local context only - per-part values:

$text = Inscribe::make()
    ->include('greeting', ['name' => 'John'])
    ->include('signature', ['name' => 'Support Team'])
    ->build();

Combined - global defaults with local overrides:

$text = Inscribe::make()
    ->context(['name' => 'Guest', 'date' => 'today'])
    ->include('greeting')                         // name=Guest, date=today
    ->include('greeting', ['name' => 'John'])     // name=John, date=today
    ->include('farewell', ['date' => 'tomorrow']) // name=Guest, date=tomorrow
    ->build();

Priority: Local context always wins over global for the same key.

Raw Text

Add text without a template file:

$text = Inscribe::make()
    ->include('email.header')
    ->raw('PS: {{note}}', ['note' => 'Thanks for reading!'])
    ->include('email.footer')
    ->build();

Custom Separators

Control how parts are joined:

// Double newline between paragraphs
$text = Inscribe::make()
    ->separator("\n\n")
    ->include('intro')
    ->include('body')
    ->include('conclusion')
    ->build();

// No separator (direct concatenation)
$text = Inscribe::make()
    ->separator('')
    ->include('prefix')
    ->include('suffix')
    ->build();

Using the Facade

use SerhiiLabs\Inscribe\Facades\Inscribe;

$text = Inscribe::make()
    ->include('template.name')
    ->build();

API Reference

Method	Description
make()	Create a new builder instance
context(array $data)	Set global context for all parts
separator(string $sep)	Set separator between parts (default: \n)
include(string $name, array $context = [])	Add a template by dot-notation name
raw(string $text, array $context = [])	Add raw text with optional placeholders
build()	Compile and return the final string

Exceptions

Exception	When
TemplateNotFoundException	Template file not found
UnboundPlaceholderException	Placeholder in template but not in context
InvalidArgumentException	Invalid template name format

All exceptions extend InscribeException for easy catching.

Artisan Commands

List Templates

php artisan inscribe:list
php artisan inscribe:list --all  # Show all without limit

Displays available templates as a tree:

Available templates:

├── email/
│   ├── header
│   └── footer
└── notifications/
    └── alert

Total: 3 template(s)

Validate Templates

php artisan inscribe:validate

Checks placeholder syntax in all templates. Detects:

• Spaces in braces: {{ name }} (should be {{name}})
• Invalid starting characters: {{123name}}
• Invalid characters: {{user.name}}, {{user@name}}

Testing

composer test

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover a security vulnerability, please email serhiilabs@gmail.com instead of using the issue tracker.

Credits

• Serhii Bondarenko
• All Contributors

License

The MIT License (MIT). Please see License File for more information.