Ds\Hashable — Interface · PHP-Referenz

Signatur

interface Ds\Hashable

Beschreibung

Ds\Hashable ist ein Interface aus der Data Structures-Erweiterung (ext-ds). Es erlaubt Objekten, eine eigene Hash-Funktion und eine Gleichheitsprüfung zu definieren, sodass sie als Schlüssel in Ds\Map und als Elemente in Ds\Set genutzt werden können.

Standardmäßig können PHP-Objekte in Ds\Map und Ds\Set nur per Objektidentität (also per Referenz) verglichen werden. Implementiert ein Objekt Ds\Hashable, kann es stattdessen über einen selbst berechneten Hash-Wert und eine benutzerdefinierte Gleichheitsprüfung eingeordnet werden – ähnlich wie hashCode() und equals() in Java.

Das Interface schreibt zwei Methoden vor: hash() liefert einen skalaren Wert (z. B. einen String oder Integer), der als Grundlage für die interne Bucket-Auswahl dient. equals() prüft, ob zwei Objekte als gleich betrachtet werden sollen. Beide Methoden sollten konsistent implementiert werden: Wenn equals() true zurückgibt, müssen beide Objekte denselben Hash-Wert liefern.

Dieses Interface ist besonders nützlich, wenn Objekte mit gleichen Inhaltsdaten (aber unterschiedlicher Identität) als identische Schlüssel oder Set-Elemente behandelt werden sollen – ein typisches Szenario in domänengetriebener Entwicklung mit Value Objects.

Beispiele

Value Object als Schlüssel in Ds\Map

<?php
require 'vendor/autoload.php'; // oder ext-ds nativ laden

class Koordinate implements Ds\Hashable
{
    public function __construct(
        public readonly int $x,
        public readonly int $y
    ) {}

    public function hash(): string
    {
        return $this->x . ',' . $this->y;
    }

    public function equals(mixed $obj): bool
    {
        return $obj instanceof self
            && $obj->x === $this->x
            && $obj->y === $this->y;
    }
}

$karte = new Ds\Map();

$k1 = new Koordinate(3, 5);
$k2 = new Koordinate(3, 5); // Gleicher Inhalt, anderes Objekt

$karte->put($k1, 'Startpunkt');

// Da equals() und hash() übereinstimmen, wird $k2 als gleicher Schlüssel erkannt
echo $karte->get($k2); // Startpunkt

Startpunkt

Ds\Set mit benutzerdefinierten Gleichheitskriterien

<?php
class Farbe implements Ds\Hashable
{
    public function __construct(
        public readonly string $hex
    ) {}

    public function hash(): string
    {
        return strtolower($this->hex);
    }

    public function equals(mixed $obj): bool
    {
        return $obj instanceof self
            && strtolower($obj->hex) === strtolower($this->hex);
    }
}

$set = new Ds\Set();
$set->add(new Farbe('#FF0000'));
$set->add(new Farbe('#ff0000')); // Gleich nach equals(), wird nicht doppelt eingefügt

echo $set->count(); // 1

1

// Wichtig · Fallstricke

Konsistenzregel: Wenn equals() für zwei Objekte true zurückgibt, müssen beide denselben Wert von hash() liefern. Wird diese Regel verletzt, führt dies zu undefiniertem Verhalten in Ds\Map und Ds\Set (z. B. doppelte Einträge oder nicht auffindbare Schlüssel).

Achtung: Der Rückgabewert von hash() muss ein skalarer PHP-Wert sein (String, Integer, Float oder Boolean). Objekte oder Arrays sind nicht erlaubt.

Dieses Interface ist nicht Teil der PHP-Standardbibliothek, sondern erfordert die PECL-Erweiterung ext-ds oder das Composer-Paket php-ds/php-ds.

Siehe auch

Ds\Map Ds\Set Ds\Collection spl_object_id