MongoDB\BSON\Javascript — Klasse · PHP-Referenz

Signatur

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, Serializable, JsonSerializable

Beschreibung

Die Klasse MongoDB\BSON\Javascript kapselt JavaScript-Code als BSON-Typ, wie er von MongoDB für gespeicherte Funktionen, Map-Reduce-Operationen oder $where-Abfragen verwendet wird. Der BSON-Typ JavaScript (Code) entspricht dem BSON-Typ 13, während JavaScript mit Scope dem BSON-Typ 15 entspricht.

Wird ein Scope-Objekt übergeben, enthält das resultierende BSON-Dokument sowohl den JavaScript-Code als auch einen fest definierten Variablenkontext. Dies ist nützlich, wenn innerhalb der JavaScript-Ausführung bestimmte PHP-Variablen zur Laufzeit übergeben werden sollen, ohne den JavaScript-Code selbst dynamisch zu verändern.

Ein typischer Anwendungsfall ist die Nutzung bei Map-Reduce-Befehlen oder dem veralteten $where-Operator, bei dem JavaScript-Code serverseitig ausgeführt wird. Da der $where-Operator und Map-Reduce in modernen MongoDB-Versionen als überholt gelten, sollte nach Möglichkeit auf Aggregation-Pipelines zurückgegriffen werden.

Die Klasse ist final und kann nicht erweitert werden. Instanzen sind unveränderlich (immutable); einmal erstellt, können Code und Scope nicht mehr geändert werden.

Parameter

Name	Typ	Default	Beschreibung
$code Pflicht	string		Der JavaScript-Code als Zeichenkette. Muss gültiger JavaScript-Code sein, der von MongoDB serverseitig ausgeführt werden kann.
$scope	array\|object\|null	null	Ein optionaler Gültigkeitsbereich (Scope) als assoziatives Array oder Objekt. Die enthaltenen Schlüssel-Wert-Paare stehen dem JavaScript-Code als Variablen zur Verfügung. Wird `null` oder kein Wert übergeben, wird ein JavaScript-Wert ohne Scope erzeugt (BSON-Typ 13).

Beispiele

JavaScript-Code ohne Scope erstellen

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

$js = new MongoDB\BSON\Javascript('function() { return this.active === true; }');

echo $js->getCode();
// Ausgabe: function() { return this.active === true; }

var_dump($js->getScope()); // NULL, da kein Scope übergeben wurde

function() { return this.active === true; } NULL

JavaScript-Code mit Scope (Map-Reduce)

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

$minAge = 18;

$mapFunction = new MongoDB\BSON\Javascript(
    'function() {
        if (this.age >= minAge) {
            emit(this.country, 1);
        }
    }',
    ['minAge' => $minAge] // Scope: $minAge wird als JS-Variable "minAge" verfügbar
);

$reduceFunction = new MongoDB\BSON\Javascript(
    'function(key, values) {
        return Array.sum(values);
    }'
);

echo $mapFunction->getCode() . PHP_EOL;
print_r($mapFunction->getScope());
// Scope enthält ["minAge" => 18]

function() { if (this.age >= minAge) { emit(this.country, 1); } } stdClass Object ( [minAge] => 18 )

BSON-Serialisierung und JSON-Darstellung

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

$js = new MongoDB\BSON\Javascript('function() { return 42; }');

// JSON-Repräsentation (JsonSerializable)
$json = json_encode($js);
echo $json . PHP_EOL;
// Ausgabe: {"$code":"function() { return 42; }"}

// BSON-Serialisierung und -Deserialisierung
$bson = MongoDB\BSON\fromPHP(['fn' => $js]);
$restored = MongoDB\BSON\toPHP($bson);
echo get_class($restored->fn) . PHP_EOL;
// Ausgabe: MongoDB\BSON\Javascript

{"$code":"function() { return 42; }"} MongoDB\BSON\Javascript

// Wichtig · Fallstricke

Sicherheitshinweis: Die Ausführung von JavaScript auf dem MongoDB-Server (z. B. über $where oder Map-Reduce) ist ein potenzielles Sicherheitsrisiko, wenn Benutzereingaben in den JavaScript-Code eingebettet werden. Dies kann zu JavaScript-Injection führen, ähnlich wie SQL-Injection. Verwende stets den Scope-Parameter, um externe Werte an den JavaScript-Code zu übergeben, anstatt sie direkt in den Code-String zu interpolieren.

Deprecation-Hinweis: Der $where-Operator ist seit MongoDB 4.4 veraltet, und Map-Reduce wurde in MongoDB 5.0 als überholt markiert. Für neue Projekte sollten Aggregation-Pipelines verwendet werden, da diese performanter und sicherer sind.

Der Unterschied zwischen BSON-Typ 13 (Code ohne Scope) und Typ 15 (Code mit Scope) ist relevant für die Interoperabilität mit anderen MongoDB-Treibern und Tools. Ein leeres Scope-Array [] erzeugt dennoch ein Objekt mit Scope (Typ 15), nicht Typ 13.

Siehe auch

MongoDB\BSON\JavascriptInterface MongoDB\BSON\fromPHP MongoDB\BSON\toPHP MongoDB\BSON\Regex