PHP array_unshift() meistern – Elemente am Anfang von Arrays hinzufügen

Im ersten Abschnitt erfährst du, was das Hinzufügen von Elementen am Anfang eines Arrays bedeutet und wofür du dieses Prinzip in PHP nutzen kannst. So bekommst du direkt einen Überblick, wann sich dieser Ansatz im Programmieralltag auszahlt.

I. Einleitung: Das Wichtigste zu PHP array_unshift() auf einen Blick

A. Was ist array_unshift()?
PHP 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.

B. Warum ist array_unshift() nützlich?
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.

C. Hauptvorteile der Funktion

• Direkte Modifikation des Originals
• Einfache Syntax für mehrere neue Elemente
• Rückgabe der neuen Elementanzahl

II. Die Grundlagen: Syntax und Parameter von array_unshift()

A. Syntax:

/** Fügt Werte am Anfang des Arrays hinzu */ 


int array_unshift(array &$aArray, mixed ...$mWerte) 

• &$aArray: Das zu verändernde Array (per Referenz)
• ...$mWerte: Ein oder mehrere Werte, die am Anfang eingefügt werden sollen
• Rückgabewert: Anzahl der Elemente nach dem Hinzufügen

B. Parameter im Detail:

1. &$aArray
   Das Array wird per Referenz übergeben (das &-Zeichen ist entscheidend). Die Funktion arbeitet also direkt am Original, kein Kopieren!

2. …$mWerte (Variadic Parameter)
   Du kannst beliebig viele Werte als weitere Parameter übergeben – einzeln oder durch Kommas getrennt.

C. Rückgabewert:
array_unshift() liefert einen Integer zurück – das ist die neue Gesamtanzahl der Elemente im Array nach der Operation.
Beispiel:

$iNeu = array_unshift($aMeineListe, "Start"); 

Jetzt enthält $aMeineListe ein neues Element an Index 0 und $iNeu ist die Anzahl der Array-Elemente.

III. array_unshift() in Aktion: Umfassende Code-Beispiele

Im nächsten Beispiel wird gezeigt, wie du einem numerisch indizierten Array gezielt einen neuen Wert am Anfang hinzufügst.

A. Beispiel 1: Einzelnes Element hinzufügen (numerisches Array)

$aTiere = ["Hund", "Katze"]; 


$iAnzahl = array_unshift($aTiere, "Maus"); 


/** $aTiere ist jetzt: ["Maus", "Hund", "Katze"] 
 $iAnzahl ist 3 */ 

Erläuterung:
Alle Indizes werden neu nummeriert. Das neue Element ist jetzt bei 0.

B. Beispiel 2: Mehrere Elemente hinzufügen

$aFarben = ["Blau", "Grün"]; 


$iNeu = array_unshift($aFarben, "Rot", "Gelb"); 


/** $aFarben: ["Rot", "Gelb", "Blau", "Grün"] 
 $iNeu: 4 */ 

Die Reihenfolge bleibt wie angegeben – “Rot” steht vorne.

C. Beispiel 3: Mit assoziativen Arrays

$aDaten = ["name" => "Max", "stadt" => "Berlin"]; 


array_unshift($aDaten, "ID123"); 


/** $aDaten: [0 => "ID123", "name" => "Max", "stadt" => "Berlin"] */ 

Erklärung:
Neue Werte bekommen numerische Schlüssel, bestehende String-Schlüssel bleiben erhalten.

D. Beispiel 4: Ein Array als Wert hinzufügen

$aA = [1, 2, 3]; 


$aB = ["X", "Y"]; 


array_unshift($aA, $aB); 


/** $aA: [0 => ["X", "Y"], 1 => 1, 2 => 2, 3 => 3] */ 

Klarstellung:
Das komplette Array wird als EIN Wert vorne angehängt – KEIN Verschmelzen wie bei array_merge()!

IV. Wichtige Aspekte und Verhalten von array_unshift()

Beim Hinzufügen neuer Elemente am Anfang eines Arrays verändert sich das Verhalten der Schlüssel je nach Array-Typ – vor allem, wenn numerische und assoziative Schlüssel kombiniert auftreten.

A. Schlüsselbehandlung:

• Numerische Schlüssel: Werden immer neu vergeben (beginnend bei 0, 1, 2…)
• String-Schlüssel: Bleiben wie sie sind, erhalten aber höhere Indizes
  Beispiel:

$aMix = ["a" => 9, "b" => 8]; 


array_unshift($aMix, "neu"); 

Jetzt: [0 => "neu", "a" => 9, "b" => 8]

B. Interner Array-Zeiger:
array_unshift() setzt den Array-Zeiger auf das erste Element zurück.
Wichtig für Funktionen wie current(), next(), prev(), die mit dem Element eines Arrays arbeiten.

C. Verhalten bei leeren Arrays:
Ein leeres Array nimmt alle neuen Werte ganz vorne auf, und die Rückgabe ist einfach die Anzahl der hinzugefügten Werte.

D. Änderungen in PHP-Versionen:
Seit PHP 7.3.0 ist auch ein Aufruf ohne weitere Werte möglich (dann wird aber nichts verändert).

V. Praktische Anwendungsfälle für array_unshift()

Bei Warteschlangen fügst du neue Aufgaben am vorderen Ende der Liste hinzu und entfernst sie am hinteren Ende, sodass die Reihenfolge „First In, First Out“ gewahrt bleibt.

A. Warteschlange (Queue – FIFO) mit array_unshift() und array_pop()

$aWarteschlange = ["Job1", "Job2"]; 


array_unshift($aWarteschlange, "Job0"); 


$sAktuell = array_pop($aWarteschlange); 


/** $sAktuell: "Job2" */ 

B. Aufgabenlisten/To-Do-Listen:
Neue Aufgaben kommen ganz oben auf die Liste – das motiviert, Aktuelles zuerst abzuarbeiten.

/** Aufgabenliste als Array */



$aAufgaben = ["Einkaufen", "Mails beantworten"];



/** Neue Aufgabe am Anfang hinzufügen */



array_unshift($aAufgaben, "Kundentelefonat");



/** Aufgabenliste ausgeben */



foreach ($aAufgaben as $sAufgabe) {



 echo $sAufgabe . "n";



}



/** Ausgabe:

Kundentelefonat

Einkaufen

Mails beantworten

*/

C. Logging/Verlauf:
Neueste Einträge immer oben. Beispiel:

$aLog = []; 


array_unshift($aLog, "User hat sich eingeloggt"); 

D. Datenvorbereitung:
Manchmal brauchen Funktionen spezielle Werte ganz vorne im Array, z.B. für Parameterübergabe.

<?php 
/** Ursprüngliches Array mit Parametern */



$aParameter = ["aktion" => "speichern", "id" => 42];





/** Speziellen Wert (z.B. API-Key) am Anfang platzieren */



array_unshift($aParameter, "API-KEY-12345");



/** Übergabe des Arrays an eine Funktion */



fuehreAktionAus($aParameter);





/** Beispielhafte Funktionsdefinition */



function fuehreAktionAus($aDaten) {



 /** Erster Wert: API-Key */



 $sApiKey = $aDaten[0];



 /** Weiterverarbeitung ... */



 print_r($aDaten);



}



/** Array

(

 [0] => API-KEY-12345

 [aktion] => speichern

 [id] => 42

)

*/

VI. Performance-Überlegungen

A. Große Arrays:
Jedes Mal werden alle Indizes verschoben – bei sehr großen Arrays kann das langsam werden.
Praxis-Tipp: Bei Performance-Problemen lieber ans Ende anhängen (array_push()) und bei Bedarf array_reverse() einsetzen.

B. Alternativen:
Für riesige Mengen kann eine andere Datenstruktur (z.B. SPL-Datenstrukturen wie SplQueue) sinnvoller sein.

VII. array_unshift() im Vergleich – ähnliche Array-Funktionen

Kurz-Fazit:
array_unshift() ist das Gegenstück zu array_push().

VIII. Häufige Fehler und Best Practices

A. Das Original-Array wird verändert!
Immer daran denken, dass das Ursprungsarray modifiziert wird.

B. Schlüsselverhalten richtig einschätzen:
Neue Werte werden immer numerisch einsortiert, String-Schlüssel bleiben. Das kann zu unerwarteten Ergebnissen führen.

C. Typ prüfen:
Vor Benutzung sicherstellen, dass wirklich ein Array übergeben wird:

if (is_array($aMeineDaten)) { 
 array_unshift($aMeineDaten, "neu"); 
} 

D. Rückgabewert beachten:
Die Funktion gibt nicht das Array, sondern die Anzahl der Elemente zurück.

IX. Fazit: Wann und warum array_unshift() verwenden?

Nutze array_unshift(), wenn Du schnell und unkompliziert Elemente am Anfang eines Arrays brauchst – etwa bei Warteschlangen, Verlaufsspeicherung oder Aufgabenlisten. Es ist die einfachste Lösung für die meisten Anwendungsfälle, solange die Performance nicht kritisch ist.

Viel Spaß beim Experimentieren mit array_unshift()!