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

By Dinesh Uprety
Published: 2025-01-18
Updated: 2025-01-19
Canonical: https://laranepal.com/blog/how-to-replace-keyvalue-pairs-in-strings-using-the-swap-helper-method-in-php

# 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](https://laravel.com/docs/11.x/strings#method-str-swap) 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
<?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
<?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
<?php

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

```

The output is:

```textmate
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
<?php

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

```

The output is:

```textmate
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
<?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
<?php

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

```

The output is as expected:

```textmate
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
<?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
<?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.