Ds\Map — Klasse · PHP-Referenz

Signatur

class Ds\Map implements Ds\Collection

Beschreibung

Ds\Map ist eine geordnete Sammlung von Schlüssel-Wert-Paaren, bei der Schlüssel jeden beliebigen Typ haben dürfen – einschließlich Objekte, Arrays und primitive Typen. Im Gegensatz zu PHPs nativen Arrays, die nur Strings und Integers als Schlüssel unterstützen, ermöglicht Ds\Map deutlich flexiblere Strukturen.

Die Einfügereihenfolge wird immer beibehalten. Beim erneuten Setzen eines vorhandenen Schlüssels bleibt seine Position in der Map erhalten und lediglich der Wert wird aktualisiert. Das macht Ds\Map besonders nützlich, wenn die Reihenfolge der Einträge semantisch wichtig ist.

Intern speichert Ds\Map die Paare in einer geordneten Liste und nutzt Hash-Lookups für schnellen Zugriff. Die Klasse bietet Methoden zum Zusammenführen, Filtern, Sortieren und Transformieren der enthaltenen Paare. Außerdem implementiert sie Ds\Collection sowie ArrayAccess, Countable und IteratorAggregate.

Gegenüber PHP-Arrays hat Ds\Map einen etwas höheren Speicher-Overhead bei kleinen Datensätzen, bietet aber erhebliche Vorteile bei der Typsicherheit der Schlüssel und der Ausdrucksstärke des Codes.

Parameter

Name	Typ	Default	Beschreibung
$values	iterable	[]	Ein optionales iterierbares Objekt oder Array mit initialen Schlüssel-Wert-Paaren. Kann ein assoziatives Array, ein anderes `Ds\Map`-Objekt oder ein Array von `[Schlüssel, Wert]`-Paaren sein.

Beispiele

Grundlegende Verwendung mit Objekt-Schlüsseln

<?php
require 'vendor/autoload.php'; // polyfill oder pecl/ds

$map = new Ds\Map();

$key1 = new stdClass();
$key1->name = 'alpha';

$key2 = new stdClass();
$key2->name = 'beta';

$map->put($key1, 'Wert für Alpha');
$map->put($key2, 'Wert für Beta');

echo $map->get($key1) . PHP_EOL;
echo $map->get($key2) . PHP_EOL;
echo 'Größe: ' . $map->count() . PHP_EOL;

Wert für Alpha Wert für Beta Größe: 2

Initialisierung aus einem Array und Iteration

<?php
require 'vendor/autoload.php';

$map = new Ds\Map([
    'name'  => 'PHP',
    'major' => 8,
    'lts'   => true,
]);

foreach ($map as $key => $value) {
    echo "$key => " . var_export($value, true) . PHP_EOL;
}

// Filtern: nur Einträge mit einem skalaren Wert > 1
$filtered = $map->filter(fn($v) => is_int($v) && $v > 1);
echo '--- gefiltert ---' . PHP_EOL;
foreach ($filtered as $k => $v) {
    echo "$k => $v" . PHP_EOL;
}

name => 'PHP' major => 8 lts => true --- gefiltert --- major => 8

Zusammenführen, Sortieren und Umkehren

<?php
require 'vendor/autoload.php';

$a = new Ds\Map(['x' => 10, 'y' => 30, 'z' => 20]);
$b = new Ds\Map(['y' => 99, 'w' => 5]);

// merge: Schlüssel aus $b überschreiben $a
$merged = $a->merge($b);
echo 'Merged:' . PHP_EOL;
foreach ($merged as $k => $v) {
    echo "  $k => $v" . PHP_EOL;
}

// Sortieren nach Wert
$sorted = $merged->copy();
$sorted->ksort(); // nach Schlüssel
echo 'Nach Schlüssel sortiert:' . PHP_EOL;
foreach ($sorted as $k => $v) {
    echo "  $k => $v" . PHP_EOL;
}

// Nur Schlüssel / nur Werte
$keys   = $merged->keys();   // Ds\Sequence
$values = $merged->values(); // Ds\Sequence
echo 'Schlüssel: ' . implode(', ', $keys->toArray()) . PHP_EOL;
echo 'Werte:     ' . implode(', ', $values->toArray()) . PHP_EOL;

Merged: x => 10 y => 99 z => 20 w => 5 Nach Schlüssel sortiert: w => 5 x => 10 y => 99 z => 20 Schlüssel: x, y, z, w Werte: 10, 99, 20, 5

// Wichtig · Fallstricke

Erweiterung erforderlich: Ds\Map gehört zur PECL-Erweiterung ds. Alternativ steht ein reines PHP-Polyfill (php-ds/php-ds) via Composer bereit. Die native Erweiterung ist deutlich performanter.

Schlüsselgleichheit: Objekte werden per Referenz verglichen – zwei verschiedene Objekte mit identischem Inhalt gelten als unterschiedliche Schlüssel. Integer-artige Strings werden nicht zu Integers konvertiert (anders als bei nativen PHP-Arrays).

Kapazität: Die interne Kapazität wächst automatisch, kann aber mit allocate() vorab gesetzt werden, um Reallocations zu vermeiden.

Serialisierung: Ds\Map ist serialisierbar; Objekt-Schlüssel werden dabei per Referenz serialisiert, was zu unerwarteten Ergebnissen führen kann, wenn die Objekte keine stabile Identität haben.

Siehe auch

Ds\Set Ds\Sequence Ds\Collection Ds\Vector Ds\Deque Ds\Pair