How to Replace Key/Value Pairs in Strings Using the swap Helper Method in PHP

When working with strings in PHP, replacing placeholders with actual values is a common task. For example, you might want to personalize an email template by replacing placeholders like [name] with a recipient’s name. While PHP offers traditional string replacement methods, they can sometimes behave unexpectedly.

In this article, we’ll explore a better way to replace placeholders using the swap helper method from Laravel’s string utilities.

What is the swap Helper Method?

The swap helper method is a function in Laravel that allows you to replace key/value pairs within a string. It ensures that placeholders are replaced only as intended, avoiding issues that might arise with traditional string replacement methods.

Why Do We Need the swap Helper Method?

Let’s say we have the following email template:

<?php
 
$emailTemplate = <<<TEMPLATE
Hello [name],
 
Thank you for reaching out! We are working to process your request;
in the meantime, you may find the following resources helpful:
[resources]
 
Sincerely,
[sender]
TEMPLATE;

This template includes placeholders like [name], [resources], and [sender]. Our goal is to replace these placeholders with real data, such as the recipient’s name, a link to resources, and the sender’s name.

The Traditional Approach: Using Str::replace()

To replace placeholders, we can use the Str::replace() method from Laravel. Here’s how we might write a function to personalize the email template:

<?php
 
use Illuminate\Support\Str;
 
function renderEmailTemplate($template, $name, $resources, $sender) {
    return Str::replace(
        ['[name]', '[resources]', '[sender]'],
        [$name, $resources, $sender],
        $template
    );
}

When we call this function:

<?php
 
renderEmailTemplate(
    $emailTemplate,
    'Alice',
    'https://example.com/resources',
    'Core Team'
);

The output is:

Hello Alice,
 
Thank you for reaching out! We are working to process your request;
in the meantime, you may find the following resources helpful:
https://example.com/resources
 
Sincerely,
Core Team

The Problem with Str::replace()

The Str::replace() method works well in most cases, but there’s a problem: it can unintentionally replace parts of the inserted text if the input contains placeholders.

For example, consider the following input:

<?php
 
renderEmailTemplate(
    $emailTemplate,
    '[resources] Director',
    'https://example.com/resources',
    'Core Team'
);

The output is:

Hello https://example.com/resources Director,
 
Thank you for reaching out! We are working to process your request;
in the meantime, you may find the following resources helpful:
https://example.com/resources
 
Sincerely,
Core Team

The [resources] placeholder in the recipient’s name was replaced unexpectedly. This behavior can cause bugs or lead to incorrect outputs.

The Solution: Using Str::swap()

The swap helper method solves this problem by ensuring placeholders are replaced only where they appear in the original template. Here’s how we can rewrite the function:

<?php
 
use Illuminate\Support\Str;
 
function renderEmailTemplate($template, $name, $resources, $sender) {
    return Str::swap(
        [
            '[name]' => $name,
            '[resources]' => $resources,
            '[sender]' => $sender,
        ],
        $template
    );
}

Now, if we call the function with the same problematic input:

<?php
 
renderEmailTemplate(
    $emailTemplate,
    '[resources] Director',
    'https://example.com/resources',
    'Core Team'
);

The output is as expected:

Hello [resources] Director,
 
Thank you for reaching out! We are working to process your request;
in the meantime, you may find the following resources helpful:
https://example.com/resources
 
Sincerely,
Core Team

Fluent Strings with swap

The swap method is also available on fluent string instances, which can make your code more readable. Here’s the same function written with fluent strings:

<?php
 
function renderEmailTemplate($template, $name, $resources, $sender) {
    return str($template)->swap([
        '[name]' => $name,
        '[resources]' => $resources,
        '[sender]' => $sender,
    ])->toString();
}

Key Order in swap

The swap helper processes replacements based on the length of the keys, starting with the longest. This ensures predictable behavior. For example, the following two calls produce the same result:

<?php
 
use Illuminate\Support\Str;
 
Str::swap([
    '[name]' => $name,
    '[sender]' => $sender,
    '[resources]' => $resources,
], $template);
 
Str::swap([
    '[resources]' => $resources,
    '[sender]' => $sender,
    '[name]' => $name,
], $template);

Conclusion

The swap helper method is a reliable way to replace placeholders in strings without unexpected side effects. It’s especially useful when working with templates that may contain overlapping or user-provided data. By using swap, you can avoid common pitfalls and ensure your string replacements behave as intended.