Von einer Kreditkartennummer sollen nur die letzten vier Stellen sichtbar bleiben, eine E-Mail-Adresse im Supportlog nur der erste Buchstabe. Solche Aufgaben haben eines gemeinsam: Die Stelle, an der etwas ersetzt werden soll, ist bekannt, der Inhalt dagegen egal. Genau dafür gibt es in PHP eine eigene Funktion, die positionsbasiert arbeitet statt nach einem Muster zu suchen. Dieses Tutorial zeigt ihre vier Parameter, negative Indizes, den Array-Modus und mehrere Maskierungs-Beispiele aus der Praxis.
Was macht die Funktion PHP substr_replace()?
Wer in PHP einen Teil eines Strings an einer bestimmten Position überschreiben möchte, ohne den Rest anzutasten, greift zu PHP substr_replace. Die Funktion arbeitet positionsbasiert: Sie nimmt einen Original-String, einen Ersatz-String, eine Startposition und optional eine Länge und liefert das Ergebnis als neuen String zurück. Damit ist sie das richtige Werkzeug für Aufgaben wie das Maskieren von Kreditkartennummern, das Anonymisieren von E-Mail-Adressen oder das Korrigieren fester Datensatzbreiten. Das Tutorial zeigt dazu mehrere praxisnahe Beispiele.
Bevor Syntax, negative Indizes und der Multi-String-Modus im Detail folgen, ein wichtiger Unterschied zu str_replace, der die Einsatzgebiete klar abgrenzt.
Im Gegensatz zu str_replace, das ein gesuchtes Pattern ersetzt, weiß PHP substr_replace genau, an welcher Position die Ersetzung passieren soll. Das macht sie zu einer sehr präzisen Funktion, die ohne Suchen direkt schreibt. Wer mit Fixed-Width-Daten, Banknummern, Hashes oder positionsbasierten Codes arbeitet, kommt um sie kaum herum.
Syntax und die vier Parameter
Die Signatur erwartet einen Original-String, einen Ersatz-String, eine Position und optional eine Länge. Alle vier Parameter können sowohl als Skalar als auch als Array übergeben werden, was die Funktion für Batch-Operationen besonders interessant macht.
<?php
substr_replace(
array|string $string,
array|string $replace,
array|int $offset,
array|int|null $length = null
): array|string
Wer einen Skalar-String übergibt, bekommt einen Skalar-String zurück. Wer ein Array übergibt, bekommt ein Array zurück. Im Multi-String-Modus lässt sich PHP substr_replace also auch direkt auf eine Liste von Strings anwenden, ohne eine eigene Schleife zu schreiben.
Position und Length im Detail
Im Standardfall ersetzt PHP substr_replace ab der angegebenen Position genau $length Zeichen mit dem Replace-String. Die Anzahl der eingefügten Zeichen muss dabei nicht mit der Anzahl der ersetzten übereinstimmen, der String kann also während der Operation kürzer oder länger werden.
<?php
$text = 'PHP ist toll';
echo substr_replace($text, 'super', 4, 3) . "\n";
/* PHP super toll - 'ist' (3 Zeichen) wird durch 'super' (5 Zeichen) ersetzt */
echo substr_replace($text, 'X', 4, 3) . "\n";
/* PHP X toll - 'ist' wird durch 'X' (1 Zeichen) ersetzt */
Damit ist PHP substr_replace flexibler als ein einfaches Überschreiben mit fester Länge. Wer eine exakte Länge erhalten will, muss die Länge des Replace-Strings entsprechend selbst beachten oder mit str_pad() nacharbeiten.
Negative Indizes vom Ende her zählen
Sowohl Offset als auch Length akzeptieren negative Werte. Negative Offsets zählen vom Ende des Strings, was die Funktion für "die letzten N Zeichen ersetzen"-Aufgaben praktisch macht. Ein negativer Length-Wert bedeutet "bis N Zeichen vor dem Ende".
<?php
$nummer = '4321987612345678';
echo substr_replace($nummer, '****', -8, 4) . "\n";
/* 432198761234**** - vom 8. Zeichen von rechts, 4 Zeichen ersetzt */
echo substr_replace($nummer, '....', 4, -4) . "\n";
/* 4321........5678 - ab Pos 4 bis 4 Zeichen vor dem Ende */
Diese Notation ist besonders elegant, wenn nicht die Gesamtlänge, sondern nur die Endsicht-Information bekannt ist. Eine Telefonnummer maskieren ohne genau zu wissen, wie lang sie ist, geht mit Negative-Werten als Einzeiler.
Einfügen statt Ersetzen mit Length 0
Eine oft übersehene Eigenschaft: Wenn $length = 0 ist, wird nichts gelöscht, sondern der Replace-String an der angegebenen Position eingefügt. Damit lassen sich Substrings einfach in einen bestehenden String einbauen.
<?php
$text = 'PHP toll';
echo substr_replace($text, 'ist ', 4, 0);
/* PHP ist toll - 'ist ' wird an Position 4 eingefuegt */
Diese Variante ist die Antwort auf die häufige Frage, wie man "an einer bestimmten Position einen String einschiebt". Sie ist deutlich sauberer als Manipulation per substr() und Konkatenation und reduziert die Logik auf einen Funktionsaufruf.
Multi-String-Modus mit Arrays
Eine Besonderheit von PHP substr_replace ist die Fähigkeit, Arrays zu verarbeiten. Wer eine Liste von Strings hat, die alle an derselben Position dieselbe Änderung bekommen sollen, kann das ohne eigene Schleife tun.
<?php
$strings = ['ABCDEF', 'GHIJKL', 'MNOPQR'];
$ersetzt = substr_replace($strings, 'XX', 2, 2);
print_r($ersetzt);
/* [ABXXEF, GHXXKL, MNXXQR] */
/* auch Replace-String, Offset und Length koennen Arrays sein */
$strings = ['ABCDEF', 'GHIJKL'];
$replaces = ['1', '22'];
$ersetzt = substr_replace($strings, $replaces, [0, 1], [2, 3]);
print_r($ersetzt);
/* [1CDEF, G22KL] - jeder Eintrag mit eigenen Werten */
Im Backend-Alltag ist diese Variante praktisch für Batch-Operationen auf Datenbankzeilen, Log-Files oder konfigurierbare Datensätze. Wer häufig mit Arrays von Banknummern oder festen Codes arbeitet, kann sich damit eine deutliche Code-Vereinfachung holen.
Praxisbeispiel Kreditkarte maskieren
Das wohl häufigste Anwendungsbeispiel ist die Maskierung sensibler Daten. Eine Kreditkartennummer soll im UI nur mit den letzten 4 Stellen sichtbar sein, der Rest wird durch Sterne ersetzt.
<?php
function maskiereKarte(string $nummer): string
{
$sichtbar = 4;
$laenge = strlen($nummer);
return substr_replace(
$nummer,
str_repeat('*', $laenge - $sichtbar),
0,
$laenge - $sichtbar
);
}
echo maskiereKarte('4321987612345678');
/* ************5678 */
Diese Variante hält sich an PCI-DSS-Vorgaben und ist mit zwei Funktionsaufrufen (PHP substr_replace plus str_repeat()) komplett. Die Logik ist gut testbar und kann ohne Änderungen auch für Telefonnummern oder IBAN-Codes verwendet werden.
Ähnlich funktioniert das Anonymisieren einer E-Mail-Adresse:
<?php
function maskiereMail(string $email): string
{
$at = strpos($email, '@');
if ($at === false || $at < 3) {
return $email;
}
return substr_replace($email, '***', 1, $at - 1);
}
echo maskiereMail('max.mustermann@example.com');
/* m***@example.com */
Mit dieser Helfer-Funktion lassen sich Logs, Reports oder Support-Anfragen DSGVO-freundlich darstellen, ohne den ganzen String zu zerlegen und neu zusammenzubauen.
substr_replace vs str_replace
Im PHP-Alltag werden PHP substr_replace und str_replace() gerne verwechselt. Der Unterschied ist fundamental: substr_replace arbeitet positionsbasiert, str_replace patternbasiert.
<?php
$text = 'PHP ist toll, PHP rockt';
/* str_replace: ersetzt das Pattern UEBERALL */
echo str_replace('PHP', 'PERL', $text) . "\n";
/* PERL ist toll, PERL rockt */
/* substr_replace: ersetzt nur an einer Position */
echo substr_replace($text, 'PERL', 0, 3) . "\n";
/* PERL ist toll, PHP rockt - nur das erste Vorkommen */
Faustregel: Wenn die Position des zu ersetzenden Bereichs bekannt ist, ist PHP substr_replace die richtige Wahl. Wenn ein Pattern an beliebigen Stellen ersetzt werden soll, ist str_replace die richtige Wahl. Beide Funktionen ergänzen sich und werden im selben Projekt oft kombiniert.
Welchen Weg die Funktion je nach Length-Wert nimmt, zeigt der folgende Ablauf.
flowchart TD
A[Original-String] --> B[Position offset bestimmen]
B --> C{Length = 0?}
C -->|ja| D[Einfuegen]
C -->|nein| E[Bereich ersetzen]
E --> F{Length = null?}
F -->|ja| G[Bis Ende ersetzen]
F -->|nein| H[N Zeichen ersetzen]
D --> I[Neuer String]
G --> I
H --> I
Fazit
Mit PHP substr_replace steht ein präziser Helfer für positionsbasierte Stringoperationen bereit. Die Funktion ersetzt Bereiche, fügt mit length=0 Strings ein und arbeitet mit Negative-Indizes vom Ende her. Im Multi-String-Modus mit Arrays lassen sich Batch-Operationen ohne eigene Schleife formulieren. Die Maskierung von Kreditkarten, E-Mails und IBAN-Codes wird mit zwei Zeilen Code DSGVO- und PCI-konform. Wer den Unterschied zu str_replace verstanden hat, weiß bei jedem Code-Review sofort, welche der beiden Funktionen die passende ist. Damit gehört PHP substr_replace zum festen Repertoire jeder Anwendung, die mit Fixed-Width-Daten, sensiblen Strings oder positionsbasierten Codes arbeitet.
