MongoDB\BSON\Regex — Klasse · PHP-Referenz

Signatur

class MongoDB\BSON\Regex implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable

Beschreibung

MongoDB\BSON\Regex kapselt einen regulären Ausdruck, der nativ im BSON-Format gespeichert werden kann. Dies ist nützlich, wenn reguläre Ausdrücke direkt in MongoDB-Dokumenten persistiert oder für Abfragen mit dem $regex-Operator verwendet werden sollen, ohne sie als einfache Zeichenketten speichern zu müssen.

Der Konstruktor erwartet ein Muster (pattern) und optional Flags (z. B. i für case-insensitiv, m für multiline). Das Objekt ist unveränderlich – einmal erstellt, können weder Muster noch Flags geändert werden.

Die Klasse implementiert Stringable, sodass eine Regex-Instanz mit (string) in eine Zeichenkette der Form /Muster/Flags umgewandelt werden kann. Außerdem ist sie JsonSerializable und kann daher sicher in JSON-Kontexten serialisiert werden.

Typische Einsatzfälle sind das Speichern von regulären Ausdrücken als Dokumenteigenschaften sowie das Erstellen von Abfragen, bei denen MongoDB serverseitig einen regulären Ausdruck auswerten soll.

Parameter

Name	Typ	Default	Beschreibung
$pattern Pflicht	string		Das reguläre Ausdrucksmuster ohne Begrenzer (Delimiter). Darf keine Null-Bytes enthalten.
$flags	string	""	Optionale Flags als Zeichenkette, z. B. `"i"` (case-insensitiv), `"m"` (multiline), `"s"` (dotall), `"x"` (extended), `"l"` (locale), `"u"` (unicode). Mehrere Flags können kombiniert werden, z. B. `"im"`.

Beispiele

Regex-Objekt erstellen und in eine Abfrage einsetzen

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

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

// Suche nach allen Nutzern, deren Name case-insensitiv mit "max" beginnt
$regex = new MongoDB\BSON\Regex('^max', 'i');

$cursor = $collection->find(['name' => $regex]);
foreach ($cursor as $user) {
    echo $user['name'] . PHP_EOL;
}

Regex-Objekt als String darstellen und Eigenschaften auslesen

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

$regex = new MongoDB\BSON\Regex('hello\\sworld', 'im');

echo "Pattern : " . $regex->getPattern() . PHP_EOL;
echo "Flags   : " . $regex->getFlags()   . PHP_EOL;
echo "Als String: " . (string) $regex       . PHP_EOL;

// JSON-Serialisierung
echo json_encode(['filter' => $regex], JSON_PRETTY_PRINT) . PHP_EOL;

Pattern : hello\sworld Flags : im Als String: /hello\sworld/im { "filter": { "$regularExpression": { "pattern": "hello\\sworld", "options": "im" } } }

Regex in einem MongoDB-Dokument speichern

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

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

// Regulären Ausdruck direkt im Dokument ablegen
$collection->insertOne([
    'name'    => 'E-Mail-Validierung',
    'pattern' => new MongoDB\BSON\Regex('^[\\w.+-]+@[\\w-]+\\.[a-z]{2,}$', 'i'),
]);

echo "Muster erfolgreich gespeichert." . PHP_EOL;

Muster erfolgreich gespeichert.

// Wichtig · Fallstricke

Achtung: Das Muster darf keine Begrenzer (z. B. /) enthalten – diese werden von MongoDB intern verwendet. Das Übergeben eines Musters mit eingebetteten Null-Bytes (\0) löst eine MongoDB\Driver\Exception\InvalidArgumentException aus.

Die Flags-Zeichenkette wird von MongoDB intern alphabetisch sortiert gespeichert. Die Reihenfolge der übergebenen Flags spielt daher keine Rolle, kann aber beim Vergleich zweier Objekte zu unerwarteten Ergebnissen führen, wenn man die Strings direkt vergleicht.

Für serverseitige Regex-Abfragen nutzt MongoDB die Perl Compatible Regular Expressions (PCRE)-Bibliothek. Sehr komplexe oder nicht indizierte Regex-Abfragen können zu erheblichen Performance-Einbußen führen – ein Index auf dem betreffenden Feld und ein an den Anfang gebundenes Muster (^) verbessern die Abfragegeschwindigkeit erheblich.

Siehe auch

MongoDB\BSON\Type MongoDB\BSON\Document MongoDB\Driver\Query MongoDB\Collection::find() preg_match