Wenn neue Einträge in einem Array an erster Stelle stehen sollen, ist array_unshift() die richtige Funktion. Ob Warteschlangen, Aufgabenlisten oder Protokolle: Dieses Tutorial zeigt dir, wie du Elemente gezielt am Anfang einfügst und welche Alternativen es in modernem PHP gibt.
Das Wichtigste zu array_unshift() auf einen Blick
array_unshift() setzt ein oder mehrere Werte an den Anfang eines Arrays und verschiebt alle vorhandenen Elemente nach hinten. Die Funktion arbeitet direkt am Originalarray, weil sie dieses per Referenz übergibt.
Du kannst array_unshift() überall da einsetzen, wo neue Einträge zuerst verarbeitet werden sollen, zum Beispiel bei Warteschlangen (Queues), Aufgabenlisten oder für Protokolle, in denen das Neueste immer ganz oben stehen soll.
Hauptvorteile:
- Direkte Modifikation des Originals
- Einfache Syntax für mehrere neue Elemente
- Rückgabe der neuen Elementanzahl
Syntax und Parameter von array_unshift()
Bevor du mit array_unshift() arbeitest, solltest du Syntax, Parameter und Rückgabewert kennen.
Syntax
<?php
/* Fügt Werte am Anfang des Arrays hinzu */
int array_unshift(array &$aArray, mixed ...$mWerte)
&$aArray: Das zu verändernde Array (per Referenz, das &-Zeichen ist entscheidend)...$mWerte: Ein oder mehrere Werte, die am Anfang eingefügt werden sollen- Rückgabewert: Anzahl der Elemente nach dem Hinzufügen (int)
Du kannst beliebig viele Werte als weitere Parameter übergeben, einzeln oder durch Kommas getrennt. Seit PHP 7.3.0 ist auch ein Aufruf ohne weitere Werte möglich (dann wird nichts verändert).
Beispiel:
<?php
$aMeineListe = ["Eins", "Zwei"];
$iNeu = array_unshift($aMeineListe, "Start");
/* $aMeineListe = ["Start", "Eins", "Zwei"] */
/* $iNeu = 3 */
array_unshift() in Aktion: Code-Beispiele
Im nächsten Beispiel wird gezeigt, wie du einem numerisch indizierten Array gezielt einen neuen Wert am Anfang hinzufügst.
Einzelnes Element hinzufügen
<?php
$aTiere = ["Hund", "Katze"];
$iAnzahl = array_unshift($aTiere, "Maus");
/* $aTiere = ["Maus", "Hund", "Katze"] */
/* $iAnzahl = 3 */
Alle numerischen Indizes werden neu nummeriert. Das neue Element steht bei Index 0.
Mehrere Elemente hinzufügen
<?php
$aFarben = ["Blau", "Grün"];
$iNeu = array_unshift($aFarben, "Rot", "Gelb");
/* $aFarben = ["Rot", "Gelb", "Blau", "Grün"] */
/* $iNeu = 4 */
Die Reihenfolge der neuen Elemente bleibt wie angegeben. „Rot“ steht vorne.
Mit assoziativen Arrays
<?php
$aDaten = ["name" => "Max", "stadt" => "Berlin"];
array_unshift($aDaten, "ID123");
/* $aDaten = [0 => "ID123", "name" => "Max", "stadt" => "Berlin"] */
Neue Werte bekommen numerische Schlüssel, bestehende String-Schlüssel bleiben erhalten.
Ein Array als Wert hinzufügen
<?php
$aA = [1, 2, 3];
$aB = ["X", "Y"];
array_unshift($aA, $aB);
/* $aA = [0 => ["X", "Y"], 1 => 1, 2 => 2, 3 => 3] */
Das komplette Array wird als ein einziger Wert vorne eingefügt, nicht verschmolzen. Wenn du die Elemente einzeln einfügen willst, nutze den Spread-Operator:
<?php
$aA = [1, 2, 3];
$aB = ["X", "Y"];
$aErgebnis = [...$aB, ...$aA];
/* $aErgebnis = ["X", "Y", 1, 2, 3] */
Schlüsselverhalten und wichtige Aspekte
Beim Hinzufügen neuer Elemente am Anfang eines Arrays verändert sich das Verhalten der Schlüssel je nach Array-Typ.
Schlüsselbehandlung
- Numerische Schlüssel: Werden immer neu vergeben (beginnend bei 0, 1, 2 usw.)
- String-Schlüssel: Bleiben unverändert erhalten
<?php
$aMix = ["a" => 9, "b" => 8];
array_unshift($aMix, "neu");
/* [0 => "neu", "a" => 9, "b" => 8] */
Interner Array-Zeiger
array_unshift() setzt den Array-Zeiger auf das erste Element zurück. Das ist wichtig für Funktionen wie current(), next() und prev().
Leere Arrays
Ein leeres Array nimmt alle neuen Werte ganz vorne auf. Die Rückgabe ist die Anzahl der hinzugefügten Werte.
Praktische Anwendungsfälle
Hier siehst du typische Szenarien, in denen array_unshift() seine Stärken ausspielt.
Warteschlange (Queue, FIFO)
Eine FIFO-Queue (First In, First Out) lässt sich in PHP auf zwei Wegen umsetzen:
<?php
/* Variante 1: unshift + pop */
$aQueue = ["Job1", "Job2"];
array_unshift($aQueue, "Job0"); // Vorne einfügen
$sNaechster = array_pop($aQueue); // Hinten entnehmen
/* $sNaechster = "Job2" */
/* Variante 2: push + shift (ueblicher!) */
$aQueue2 = ["Job1", "Job2"];
$aQueue2[] = "Job3"; // Hinten anfügen
$sNaechster2 = array_shift($aQueue2); // Vorne entnehmen
/* $sNaechster2 = "Job1" */
Beide Varianten ergeben eine FIFO-Queue. Die zweite Variante mit array_push()/[] und array_shift() ist in PHP gängiger und etwas performanter, da array_push() keine Indizes neu vergeben muss.
Aufgabenliste: Neue Aufgaben ganz oben
<?php
$aAufgaben = ["Einkaufen", "Mails beantworten"];
array_unshift($aAufgaben, "Kundentelefonat");
foreach ($aAufgaben as $sAufgabe) {
echo $sAufgabe . "\n";
}
/* Ausgabe:
Kundentelefonat
Einkaufen
Mails beantworten */
Logging: Neueste Einträge oben
<?php
$aLog = [];
array_unshift($aLog, date('H:i:s') . " User eingeloggt");
array_unshift($aLog, date('H:i:s') . " Seite aufgerufen");
/* Neuester Eintrag steht immer bei Index 0 */
Breadcrumb-Navigation: Startseite voranstellen
Ein typischer Anwendungsfall: Die Breadcrumb-Navigation wird dynamisch aufgebaut, aber „Startseite“ soll immer am Anfang stehen:
<?php
$aBreadcrumbs = ["Tutorials", "PHP Grundlagen", "Arrays"];
/* Startseite immer vorne */
array_unshift($aBreadcrumbs, "Startseite");
echo implode(" > ", $aBreadcrumbs);
/* Startseite > Tutorials > PHP Grundlagen > Arrays */
Spread-Operator als moderne Alternative
Seit PHP 7.4 kannst du den Spread-Operator ... verwenden, um Elemente am Anfang eines Arrays einzufügen. Der entscheidende Unterschied: Es wird ein neues Array erzeugt, das Original bleibt unverändert.
<?php
$aOriginal = ["Hund", "Katze"];
/* Mit array_unshift (verändert das Original) */
array_unshift($aOriginal, "Maus");
/* $aOriginal = ["Maus", "Hund", "Katze"] */
/* Mit Spread-Operator (neues Array) */
$aOriginal2 = ["Hund", "Katze"];
$aNeu = ["Maus", ...$aOriginal2];
/* $aNeu = ["Maus", "Hund", "Katze"] */
/* $aOriginal2 bleibt ["Hund", "Katze"] */
Wann welche Variante? Verwende array_unshift(), wenn du das Array direkt verändern willst (z.B. in Schleifen). Der Spread-Operator eignet sich, wenn du das Original behalten und ein neues Array erzeugen möchtest, also einen funktionalen Programmierstil bevorzugst.
Performance-Überlegungen
array_unshift() muss intern alle numerischen Indizes neu zuweisen, weil jedes bestehende Element einen Platz nach hinten rückt. Das macht die Operation bei großen Arrays langsamer als array_push(), das einfach am Ende anhängt. Technisch gesprochen ist array_unshift() eine O(n)-Operation (die Laufzeit wächst linear mit der Array-Größe), während array_push() O(1) ist (konstant schnell).
Praxis-Tipp: Bei Performance-kritischen Szenarien mit zehntausenden Elementen kannst du stattdessen am Ende anfügen und bei Bedarf array_reverse() einsetzen. Für echte Queue-Datenstrukturen bietet PHP außerdem SplDoublyLinkedList oder SplQueue, die für Einfügen an beiden Enden optimiert sind.
array_unshift() im Vergleich
Die folgende Tabelle zeigt, wie sich array_unshift() von verwandten Array-Funktionen unterscheidet.
| Funktion | Zweck | Position | Schlüsselverhalten |
|---|
| array_unshift() | Am Anfang einfügen | Anfang | Neu: numerisch, alt: bleibt |
| array_push() | Am Ende einfügen | Ende | Nächster numerischer Index |
| array_shift() | Anfang entfernen | Anfang | Verschiebt alles nach vorne |
| array_pop() | Ende entfernen | Ende | Entfernt letztes Element |
| array_merge() | Arrays kombinieren | Nach Reihenfolge | Schlüssel werden angepasst |
| array_splice() | Beliebige Position | Frei wählbar | Indizes neu vergeben |
array_unshift() ist das Gegenstück zu array_push(). Wenn du Elemente an einer beliebigen Position einfügen willst (nicht nur am Anfang), ist array_splice() die richtige Wahl:
<?php
$aListe = ["A", "B", "D"];
/* "C" an Position 2 einfügen */
array_splice($aListe, 2, 0, ["C"]);
/* $aListe = ["A", "B", "C", "D"] */
Häufige Fehler und Best Practices
Einige Stolperfallen tauchen bei der Arbeit mit array_unshift() immer wieder auf.
Das Original-Array wird verändert: Immer daran denken, dass das Ursprungsarray modifiziert wird. Wenn du das Original behalten willst, nutze den Spread-Operator.
Schlüsselverhalten richtig einschätzen: Neue Werte werden immer numerisch einsortiert. String-Schlüssel bleiben bestehen. Das kann zu unerwarteten Ergebnissen führen, wenn du bestimmte Keys erwartest.
TypeError seit PHP 8.0: Wenn du kein Array übergibst, wirft PHP 8.0 einen TypeError. In PHP 7.x wurde nur eine Warnung ausgegeben. Prüfe daher den Typ oder fange den Fehler ab:
<?php
/* Sichere Variante mit Typprüfung */
if (is_array($aMeineDaten)) {
array_unshift($aMeineDaten, "neu");
}
/* Oder mit try-catch (PHP 8.0+) */
try {
array_unshift($mVariable, "neu");
} catch (TypeError $e) {
echo "Kein Array übergeben!";
}
Rückgabewert beachten: Die Funktion gibt nicht das Array zurück, sondern die Anzahl der Elemente. Schreibe also nicht $a = array_unshift($a, "x"), sonst überschreibst du dein Array mit einer Zahl.
FAQ: Häufig gestellte Fragen
Hier findest du Antworten auf die häufigsten Fragen rund um array_unshift().
Warum ändern sich meine Array-Schlüssel nach array_unshift()?
Numerische Schlüssel werden bei array_unshift() immer neu vergeben, beginnend bei 0. String-Schlüssel bleiben unverändert. Wenn du die numerischen Keys beibehalten musst, nutze den Spread-Operator oder array_merge().
Kann ich mit array_unshift() einen bestimmten Key setzen?
Nein. Neue Elemente bekommen immer automatisch numerische Schlüssel. Wenn du einen bestimmten String-Key am Anfang brauchst, nutze den Union-Operator: $aNeu = ["meinKey" => "Wert"] + $aAlt;
Was passiert bei einem leeren Array?
array_unshift() funktioniert problemlos mit leeren Arrays. Die neuen Werte werden einfach eingefügt und bilden das Array.
Was ist schneller: array_unshift() oder der Spread-Operator?
Bei kleinen Arrays ist der Unterschied vernachlässigbar. array_unshift() ändert das Array direkt (in-place), der Spread-Operator erzeugt eine Kopie. Für große Arrays kann array_unshift() daher speichereffizienter sein, ist aber durch die Index-Neuvergabe langsamer.
Gibt es einen TypeError wenn die Variable kein Array ist?
Ja, seit PHP 8.0 wird ein TypeError geworfen. In PHP 7.x gab es nur eine Warnung. Prüfe den Typ vorher mit is_array() oder fange den Fehler mit try-catch ab.
Fazit
Nutze array_unshift(), wenn du schnell und unkompliziert Elemente am Anfang eines Arrays brauchst. Für Warteschlangen, Verlaufsspeicherung oder Aufgabenlisten ist es die einfachste Lösung. In modernem PHP (ab 7.4) bietet der Spread-Operator [...$neu, ...$alt] eine elegante Alternative, die das Original unverändert lässt. Bei großen Arrays und Performance-kritischen Szenarien lohnt sich ein Blick auf SplQueue.
