Signatur
Beschreibung
oci_new_collection erstellt ein neues PHP-Objekt vom Typ OCICollection, das einen Oracle-Collection-Datentyp (VARRAY oder Nested Table) repräsentiert. Oracle-Collections ermöglichen es, mehrere Werte desselben Typs in einer einzigen Datenbankspalte oder als PL/SQL-Parameter zu speichern.
Die Funktion benötigt eine aktive Oracle-Datenbankverbindung sowie den Namen des Oracle-Typs (Type Descriptor Object, kurz TDO), der in der Datenbank definiert ist. Optional kann ein Schema-Name angegeben werden, dem der Typ gehört. Wird kein Schema angegeben, wird der aktuelle Datenbankbenutzer verwendet.
Das zurückgegebene OCICollection-Objekt kann anschließend mit den zugehörigen Methoden wie append(), getElem(), assignElem() oder free() bearbeitet werden. Typischerweise wird es als Bind-Variable an eine SQL-Anweisung oder einen PL/SQL-Block gebunden.
Nach der Verwendung sollte das Collection-Objekt mit OCICollection::free() freigegeben werden, um Ressourcen zu schonen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection Pflicht | resource | Eine gültige Oracle-Verbindungsressource, die z. B. mit oci_connect() oder oci_pconnect() erzeugt wurde. |
|
| $tdo Pflicht | string | Der Name des Oracle-Typs (Type Descriptor Object), z. B. 'MY_VARRAY_TYPE'. Groß-/Kleinschreibung wird von Oracle in der Regel ignoriert. |
|
| $schema | string | null | Der Schemaname, dem der Typ gehört. Wird null oder ein leerer String übergeben, wird der aktuelle Datenbankbenutzer als Schema verwendet. |
Rückgabewert
OCICollection-Objekt zurück. Im Fehlerfall (z. B. unbekannter Typ oder ungültige Verbindung) wird false zurückgegeben.Beispiele
Einfaches Anhängen von Werten an eine Oracle-Collection
<?php
// Verbindung zur Oracle-Datenbank herstellen
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Neues Collection-Objekt für einen VARRAY-Typ anlegen
// Annahme: CREATE TYPE MY_NUM_ARRAY AS VARRAY(10) OF NUMBER;
$collection = oci_new_collection($conn, 'MY_NUM_ARRAY');
if ($collection === false) {
$e = oci_error($conn);
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Werte anhängen
$collection->append(42);
$collection->append(100);
$collection->append(7);
echo "Anzahl Elemente: " . $collection->size() . PHP_EOL;
echo "Element 0: " . $collection->getElem(0) . PHP_EOL;
// Ressourcen freigeben
$collection->free();
oci_close($conn);
Collection als Bind-Variable in einem PL/SQL-Block verwenden
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Collection-Objekt erstellen und befüllen
// Annahme: CREATE TYPE STR_LIST AS TABLE OF VARCHAR2(100);
$col = oci_new_collection($conn, 'STR_LIST', 'HR');
$col->append('Alice');
$col->append('Bob');
$col->append('Charlie');
// PL/SQL-Block, der die Collection verarbeitet
$sql = "BEGIN
FOR i IN 1 .. :names.COUNT LOOP
DBMS_OUTPUT.PUT_LINE(:names(i));
END LOOP;
END;";
$stmt = oci_parse($conn, $sql);
// Collection als SQLT_NTY (Named Type) binden
oci_bind_by_name($stmt, ':names', $col, -1, SQLT_NTY);
oci_execute($stmt);
echo "PL/SQL-Block erfolgreich ausgeführt." . PHP_EOL;
$col->free();
oci_free_statement($stmt);
oci_close($conn);
// Wichtig · Fallstricke
Voraussetzung: Die OCI8-Erweiterung muss aktiviert sein (extension=oci8 in der php.ini). Außerdem muss der referenzierte Oracle-Typ in der Datenbank tatsächlich existieren und für den verbundenen Benutzer zugänglich sein.
Ressourcen freigeben: Vergessene free()-Aufrufe können zu Speicherlecks führen, besonders in lang laufenden Skripten oder Schleifen. Daher immer OCICollection::free() aufrufen, wenn das Objekt nicht mehr benötigt wird.
SQLT_NTY: Beim Binden einer Collection an SQL- oder PL/SQL-Statements muss der Typ-Bezeichner SQLT_NTY verwendet werden, nicht die üblichen Typen wie SQLT_CHR.