README

A powerful Laravel package for managing dynamic placeholders in your strings with support for multiple transformations, date/time helpers, and custom values.

Features

• 🔄 Case Transformations: Automatic uppercase, lowercase, and title case support
• 📅 Date & Time Placeholders: Built-in support for dates, times, and timestamps
• 🎨 Custom Placeholders: Define your own placeholders globally or per-usage
• 🔒 Auto-Protection: Values containing {{}} are automatically protected
• ⚡ Closure Support: Use closures for advanced placeholder transformations
• 🎯 Stringable Objects: Handle custom objects (Money, Date, etc.) seamlessly
• 🌐 Laravel Integration: Inspired by Laravel's Translator for familiar patterns

Installation

You can install the package via composer:

composer require rdcstarr/laravel-placeholders

Automatic Installation (Recommended)

Run the install command to publish and run the migrations:

php artisan placeholders:install

Manual Installation

Alternatively, you can install manually:

1. Publish the config file:

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

Usage

Basic Usage

use Rdcstarr\Placeholders\Facades\Placeholders;

// Simple replacement
$text = "Hello {{name}}!";
$result = Placeholders::parse($text, ['name' => 'John']);
// Output: "Hello John!"

// Or using the helper function
$result = placeholders("Hello {{name}}!", ['name' => 'John']);
// Output: "Hello John!"

Case Transformations

The package supports automatic case transformations:

$text = "User: {{name}}, Email: {{Email}}, ID: {{ID}}";
$result = placeholders($text, [
    'name' => 'john doe',
    'email' => 'JOHN@EXAMPLE.COM',
    'id' => 'abc123'
]);
// Output: "User: john doe, Email: John@example.com, ID: ABC123"

Available Formats

• {{key}} - exact value (lowercase)
• {{Key}} - first letter uppercase
• {{KEY}} - all uppercase

Default Placeholders

The package provides built-in date, time, and application placeholders:

$text = "Today is {{date}} at {{time}}";
$result = placeholders($text);
// Output: "Today is 2025-11-26 at 14:30"

Available Default Placeholders

Date:

• {{year}} - 2025
• {{month}} - 11
• {{day}} - 26
• {{date}} - 2025-11-26

Time:

• {{hour}} - 14
• {{minute}} - 30
• {{time}} - 14:30
• {{datetime}} - 2025-11-26 14:30:00

Application:

• {{app_name}} - Your app name
• {{app_url}} - Your app URL

Custom Placeholders

Using Config

Define placeholders in your config/placeholders.php:

return [
    'placeholders' => [
        'company_name' => 'Acme Corp',
        'support_email' => 'support@acme.com',
        'phone' => '+1234567890',
    ],
];

Using Helper Functions

// Set a single placeholder
set_placeholder('user_name', 'John Doe');

// Set multiple placeholders
set_placeholder([
    'company' => 'Acme Corp',
    'year' => 2025,
]);

Using the Facade

use Rdcstarr\Placeholders\Facades\Placeholders;

Placeholders::addCustomPlaceholder('company', 'Acme Corp');
Placeholders::setCustomPlaceholders([
    'email' => 'info@acme.com',
    'phone' => '+1234567890',
]);

Closure Support

Use closures for advanced transformations with <tag>content</tag> syntax:

$text = "The <bold>title</bold> is important";
$result = placeholders($text, [
    'bold' => function($content) {
        return "<strong>{$content}</strong>";
    }
]);
// Output: "The <strong>title</strong> is important"

Stringable Objects

Handle custom objects seamlessly by registering handlers:

use App\ValueObjects\Money;
use Rdcstarr\Placeholders\Facades\Placeholders;

// Register handler for Money objects
Placeholders::stringable(Money::class, function($money) {
    return $money->format();
});

// Or use the helper
stringable_placeholder(Money::class, fn($money) => $money->format());

// Now Money objects work automatically
$text = "Total: {{price}}";
$result = placeholders($text, ['price' => new Money(1000, 'USD')]);
// Output: "Total: $10.00"

Auto-Protection

Values containing {{}} are automatically protected from being interpreted as placeholders:

$userContent = "My template uses {{price}} syntax";
$result = placeholders("User says: {{content}}", [
    'content' => $userContent
]);
// Output: "User says: My template uses {{price}} syntax"
// The {{price}} in user content is preserved!

Managing Custom Placeholders

use Rdcstarr\Placeholders\Facades\Placeholders;

// Get all custom placeholders
$all = Placeholders::getCustomPlaceholders();

// Clear all custom placeholders
Placeholders::clearCustomPlaceholders();

Advanced Examples

Email Template

$template = "Dear {{Name}},\n\n"
    . "Thank you for contacting {{company_name}}.\n"
    . "We received your message on {{date}} at {{time}}.\n\n"
    . "Our team will respond to {{email}} within 24 hours.\n\n"
    . "Best regards,\n{{company_name}} Team";

set_placeholder('company_name', 'Acme Corp');

$result = placeholders($template, [
    'name' => 'john doe',
    'email' => 'john@example.com',
]);

Dynamic Content

$content = "Welcome to {{app_name}}! Today is {{date}}.";
$result = placeholders($content);
// Output: "Welcome to Laravel! Today is 2025-11-26."

API Response Messages

$message = "Resource '{{resource}}' created successfully at {{datetime}}";
$result = placeholders($message, ['resource' => 'users']);
// Output: "Resource 'users' created successfully at 2025-11-26 14:30:00"

API Reference

Helper Functions

• placeholders(string $text, array $placeholders = []): string - Parse and replace placeholders
• set_placeholder(string|array $key, mixed $value = ''): void - Add custom placeholder(s)
• stringable_placeholder(string $class, callable $handler): void - Register object handler

Facade Methods

Parsing:

• Placeholders::parse(string $text, array $placeholders = []): string

Custom Placeholders:

• Placeholders::setCustomPlaceholders(array $placeholders): void
• Placeholders::addCustomPlaceholder(string $key, mixed $value): void
• Placeholders::clearCustomPlaceholders(): void
• Placeholders::getCustomPlaceholders(): array

Stringable Handlers:

• Placeholders::stringable(string $class, callable $handler): void
• Placeholders::getStringableHandlers(): array
• Placeholders::clearStringableHandlers(): void

Testing

composer test

📖 Resources

• Changelog for more information on what has changed recently. ✍️

👥 Credits

• Rdcstarr 🙌

📜 License

• License for more information. ⚖️

laravel-placeholders