README

A powerful and extendable placeholder replacement engine for Laravel that makes working with dynamic templates a breeze. Perfect for generating letters, invoices, certificates, emails, and any document that requires dynamic content injection.

Features

🎯 Context-Aware - Register reusable context mappings for your models
🎨 Custom Formatters - Built-in formatters for dates, currency, numbers, and easy custom formatter registration
⚡ Lazy Evaluation - Defer expensive operations until needed
🔧 Template Modifiers - Support inline formatting like {amount|currency:USD} or {name|upper}
🧩 Extendable - Easily create dedicated context classes for different document types
💬 Fluent API - Chainable methods for clean, readable code
🛡️ Safe Defaults - Built-in fallback values and error handling
📦 Zero Dependencies - Works with plain Laravel, no extra packages required

Installation

composer require cleaniquecoders/placeholdify

Optionally, publish the config file:

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

Quick Start

Simple Replacement

use CleaniqueCoders\Placeholdify\PlaceholderHandler;

$template = "Hello {name}, your order #{orderNo} totaling {amount} has been confirmed.";

$content = PlaceholderHandler::process($template, [
    'name' => 'John Doe',
    'orderNo' => '12345',
    'amount' => '$99.99'
]);

// Output: "Hello John Doe, your order #12345 totaling $99.99 has been confirmed."

Fluent API

$handler = new PlaceholderHandler();

$content = $handler
    ->add('name', $user->name)
    ->addDate('today', now(), 'F j, Y')
    ->addFormatted('total', 1234.56, 'currency', 'MYR')
    ->replace($template);

Using Contexts

// Register context once
$handler->registerContextMapping('user', [
    'name' => 'name',
    'email' => 'email',
    'role' => fn($user) => $user->roles->pluck('name')->join(', '),
]);

// Use anywhere
$content = $handler
    ->useContext('user', $user, 'customer')
    ->replace('Hello {customer.name}, your role is {customer.role}');

Template Modifiers

$template = "Student: {name|upper}, Amount: {fee|currency:MYR}, Date: {created_at|date:d/m/Y}";

$content = $handler
    ->add('name', 'john doe')
    ->add('fee', 150.50)
    ->add('created_at', now())
    ->replaceWithModifiers($template);

// Output: "Student: JOHN DOE, Amount: MYR 150.50, Date: 16/10/2025"

Template Classes

Create dedicated template classes for complex scenarios:

use CleaniqueCoders\Placeholdify\PlaceholdifyBase;

class InvoiceTemplate extends PlaceholdifyBase
{
    protected function configure(): void
    {
        $this->handler->setFallback('N/A');
    }

    public function build($invoice): PlaceholderHandler
    {
        return $this->handler
            ->add('invoice_no', $invoice->invoice_number)
            ->addFormatted('total', $invoice->total, 'currency', 'MYR')
            ->addDate('invoice_date', $invoice->created_at, 'd/m/Y')
            ->useContext('customer', $invoice->customer, 'customer');
    }
}

// Usage
$template = new InvoiceTemplate();
$content = $template->generate($invoice, $templateContent);

Documentation

For comprehensive documentation, examples, and advanced usage:

📖 Complete Documentation - Full documentation index
🚀 Basic Usage - Learn the fundamentals
🎨 Formatters - Built-in and custom formatters
🔄 Context System - Reusable model mappings
⚡ Advanced Features - Lazy evaluation, conditionals, and more
🏗️ Template Classes - Organize your template logic
⚙️ Configuration - Customize default behavior
🛠️ Artisan Commands - Command-line tools
🌍 Real World Examples - Complete implementation examples
📚 API Reference - Complete method documentation

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

cleaniquecoders / placeholdify

Maintainers

Details