Signatur
Beschreibung
mysql_xdevapi\CollectionAdd ist eine Operationsklasse, die im Rahmen der MySQL X DevAPI für das Einfügen von JSON-Dokumenten in eine Collection zuständig ist. Objekte dieser Klasse werden nicht direkt instanziiert, sondern über die Methode Collection::add() erzeugt. Das ermöglicht das fluente (method-chaining) Aufbauen von Einfüge-Operationen.
Die Klasse unterstützt das Hinzufügen einzelner oder mehrerer Dokumente in einem einzigen Methodenaufruf. Intern werden die Dokumente als JSON-Objekte (PHP-Arrays oder JSON-Strings) übergeben. Bei der Ausführung via execute() werden alle gepufferten Dokumente in die Collection eingefügt. Fehlende Primärschlüssel (_id-Felder) werden dabei automatisch von MySQL generiert.
Diese Klasse ist besonders geeignet, wenn dokumentenorientierte Daten ohne vorher definiertes Schema in einer MySQL-Datenbank gespeichert werden sollen, beispielsweise in modernen NoSQL-Anwendungsfällen innerhalb von MySQL 8+. Die X DevAPI bietet dafür eine objektorientierte Alternative zum klassischen SQL-Interface.
Zu beachten ist, dass die Extension mysql_xdevapi separat installiert werden muss und einen laufenden MySQL-Server mit aktiviertem X Protocol (Port 33060) benötigt.
Beispiele
Ein einzelnes Dokument in eine Collection einfügen
<?php
// Verbindung zur MySQL X DevAPI
$session = mysql_xdevapi\getSession('mysqlx://user:password@localhost');
$schema = $session->getSchema('meine_datenbank');
$collection = $schema->getCollection('benutzer');
// Dokument als assoziatives PHP-Array einfügen
$result = $collection
->add(['name' => 'Anna Müller', 'alter' => 28, 'aktiv' => true])
->execute();
echo 'Eingefügte Dokumente: ' . $result->getAffectedItemsCount() . PHP_EOL;
echo 'Generierte ID: ' . implode(', ', $result->getGeneratedIds()) . PHP_EOL;Mehrere Dokumente auf einmal einfügen (Batch-Insert)
<?php
$session = mysql_xdevapi\getSession('mysqlx://user:password@localhost');
$schema = $session->getSchema('meine_datenbank');
$collection = $schema->getCollection('produkte');
$dokumente = [
['name' => 'Laptop', 'preis' => 999.99, 'lager' => 15],
['name' => 'Maus', 'preis' => 19.95, 'lager' => 200],
['name' => 'Tastatur','preis' => 49.50, 'lager' => 80],
];
// Alle Dokumente in einem Aufruf übergeben
$result = $collection
->add($dokumente)
->execute();
echo 'Eingefügte Dokumente: ' . $result->getAffectedItemsCount() . PHP_EOL;
foreach ($result->getGeneratedIds() as $id) {
echo 'ID: ' . $id . PHP_EOL;
}// Wichtig · Fallstricke
Installationsvoraussetzung: Die Extension mysql_xdevapi muss über PECL installiert und in der php.ini aktiviert sein (extension=mysql_xdevapi). Sie ist nicht im PHP-Kern enthalten.
X Protocol: MySQL muss mit aktiviertem X Plugin laufen (standardmäßig Port 33060). Klassische MySQL-Verbindungen (Port 3306) werden von dieser API nicht unterstützt.
Automatische _id-Vergabe: Wird kein _id-Feld in einem Dokument angegeben, generiert der Server automatisch eine eindeutige ID. Es ist jedoch möglich, eigene IDs zu vergeben, solange sie eindeutig in der Collection sind.
Sicherheit: Da Dokumente als PHP-Strukturen übergeben werden, entfällt das klassische SQL-Injection-Risiko. Dennoch sollten Eingaben aus Benutzereingaben stets validiert werden, bevor sie in die Collection eingefügt werden, um unerwünschte Datenstrukturen zu verhindern.