README

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

License

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

serhiilabs / inscribe

Maintainers

Package info

Statistics

Security

README

Why Inscribe?

Quick Example

Requirements

Installation

Configuration

Usage

Basic Usage

Dot Notation

Context (Placeholders)

Raw Text

Custom Separators

Using the Facade

API Reference

Exceptions

Artisan Commands

List Templates

Validate Templates

Testing

Changelog

Contributing

Security

Credits

License