substr_replace()

Introdução

A função substr_replace() substitui parte de uma string por outra string, com base em uma posição numérica em vez de um padrão de busca. Você indica onde começar e quantos caracteres sobrescrever, e ela insere a substituição no lugar. Isso a torna ideal para edições em posições fixas — mascarar os dígitos de um cartão de crédito, trocar um trecho de uma data ou inserir texto em um deslocamento conhecido.

Isso é diferente de str_replace(), que encontra e substitui combinando uma substring. Use substr_replace() quando souber a posição; use str_replace() quando souber o valor.

Sintaxe

substr_replace(
    array|string $string,
    array|string $replace,
    array|int $offset,
    array|int|null $length = null
): string|array

A função retorna a string resultante. Ela não modifica $string no lugar — você deve capturar o valor de retorno.

Exemplo básico

Começando no índice 7 (w), cinco caracteres são removidos e "universe" é inserido no lugar.

Inserindo sem deletar

Passe 0 como comprimento e nada é removido — a substituição é simplesmente inserida antes do deslocamento.

<?php

echo substr_replace("Hello", "ABC", 2, 0); // HeABCllo

Substituindo a partir de um deslocamento negativo

Um $offset negativo conta de volta a partir do final da string, o que é útil quando você não sabe o comprimento antecipadamente.

<?php

echo substr_replace("Hello", "X", -1);     // HellX  (replace the last character)
echo "\n";
echo substr_replace("12345", "X", 1, -1);  // 1X5    (replace from index 1 to 1-before-the-end)

Um exemplo prático: mascarar dígitos

Sobrescrever um trecho conhecido com o mesmo número de caracteres * é um uso comum no mundo real — por exemplo, ocultar parte de um número de cartão.

<?php

$card = "4111111111111111";
echo substr_replace($card, "********", 4, 8); // 4111********1111

Trabalhando com arrays

Se você passar um array de strings, substr_replace() aplica a substituição a cada elemento e retorna um novo array. Você também pode passar arrays para $replace, $offset e $length para usar valores diferentes por elemento.

<?php

$names = ["Alice", "Bob", "Carol"];
$result = substr_replace($names, "***", 1, 2);
print_r($result);
// Array
// (
//     [0] => A***ce
//     [1] => B***
//     [2] => C***ol
// )

Problemas comuns

• Ela retorna uma nova string. substr_replace($s, ...) sozinho não produz nada visível — atribua ou imprima o resultado.
• Os deslocamentos são posições de bytes, não posições de caracteres. Para texto multibyte (UTF-8) não existe mb_substr_replace; calcule os deslocamentos com cuidado ou reconstrua a string com mb_substr().
• Um deslocamento além do final da string acrescenta a substituição em vez de sobrescrever.

Funções relacionadas

• str_replace() — substituir combinando um valor em vez de uma posição.
• substr() — extrair uma parte de uma string.
• strpos() — encontrar a posição para usar em substr_replace().
• str_pad() — preencher uma string até um determinado comprimento.

Conclusão

substr_replace() é o equivalente baseado em posição de str_replace(). Ao lembrar que o deslocamento e o comprimento descrevem um trecho — e que um comprimento de 0 insere enquanto um deslocamento negativo conta a partir do final — ela se torna uma ferramenta precisa para mascarar, unir e editar strings em posições conhecidas.

Prática