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:

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. ⚖️

rdcstarr / laravel-placeholders

Maintainers

Details