MongoDB\BSON\MaxKey — Klasse · PHP-Referenz

Signatur

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\Type, Serializable, JsonSerializable

Beschreibung

MongoDB\BSON\MaxKey ist ein spezieller BSON-Typ ohne eigentlichen Datenwert. Er wird verwendet, um in MongoDB-Abfragen und -Indizes einen Wert darzustellen, der konzeptionell größer als jeder andere speicherbare BSON-Wert ist. Dies macht ihn ideal als obere Schranke in Bereichsabfragen oder zum Markieren von Dokumenten, die immer am Ende einer sortierten Ausgabe erscheinen sollen.

Ein typischer Anwendungsfall ist die Kombination mit MinKey in Shard-Key-Boundaries oder in Abfragen wie $lt: MaxKey, um alle Dokumente bis zur absoluten Obergrenze zu erfassen. Da MaxKey keinen Inhalt hat, besitzt er auch keinen Konstruktor-Parameter — die Instanziierung erfolgt schlicht mit new MongoDB\BSON\MaxKey().

Die Klasse implementiert Serializable und JsonSerializable, sodass Instanzen über PHP-Serialisierung sowie json_encode() (als {"$maxKey": 1}) korrekt abgebildet werden. Beim Lesen von MongoDB-Dokumenten über den PHP-Treiber werden MaxKey-Felder automatisch als Instanzen dieser Klasse zurückgegeben.

Beispiele

MaxKey als obere Schranke in einer Bereichsabfrage

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

$client     = new MongoDB\Client('mongodb://localhost:27017');
$collection = $client->testdb->events;

// Alle Dokumente, deren 'priority'-Feld kleiner als der absolute Maximalwert ist
$cursor = $collection->find([
    'priority' => ['$lt' => new MongoDB\BSON\MaxKey()]
]);

foreach ($cursor as $doc) {
    echo $doc['name'] . PHP_EOL;
}

MaxKey serialisieren und als JSON ausgeben

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

$maxKey = new MongoDB\BSON\MaxKey();

// PHP-Serialisierung
$serialized = serialize($maxKey);
echo $serialized . PHP_EOL;

$restored = unserialize($serialized);
var_dump($restored instanceof MongoDB\BSON\MaxKey); // bool(true)

// JSON-Repräsentation (Extended JSON)
$json = json_encode(['bound' => $maxKey]);
echo $json . PHP_EOL;

O:24:"MongoDB\BSON\MaxKey":0:{} bool(true) {"bound":{"$maxKey":1}}

Dokument mit MaxKey-Feld in MongoDB speichern und auslesen

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

$client     = new MongoDB\Client('mongodb://localhost:27017');
$collection = $client->testdb->ranges;

// Dokument mit MaxKey als obere Grenze einfügen
$collection->insertOne([
    'label'    => 'Obergrenze',
    'boundary' => new MongoDB\BSON\MaxKey(),
]);

// Dokument wieder auslesen
$doc = $collection->findOne(['label' => 'Obergrenze']);
var_dump($doc['boundary'] instanceof MongoDB\BSON\MaxKey); // bool(true)

bool(true)

// Wichtig · Fallstricke

Unveränderlichkeit: MaxKey-Instanzen sind unveränderlich und besitzen keine öffentlichen Eigenschaften oder Methoden außer denen, die durch die implementierten Interfaces vorgeschrieben werden.

Vergleichsverhalten: In MongoDB-Abfragen übertrifft MaxKey in der BSON-Vergleichsreihenfolge alle anderen Typen, einschließlich null, Zahlen, Strings, Arrays und Objekte. Sein Gegenstück für die untere Schranke ist MongoDB\BSON\MinKey.

Extended JSON: In der Canonical Extended JSON-Darstellung wird MaxKey als {"$maxKey": 1} repräsentiert. Bei der Deserialisierung über MongoDB\BSON\Document::fromJSON() oder ähnliche Methoden wird dieser Wert automatisch wieder in eine MaxKey-Instanz umgewandelt.

Siehe auch

MongoDB\BSON\MinKey MongoDB\BSON\Type MongoDB\BSON\ObjectId MongoDB\BSON\Document