ocinewcollection — Funktion · PHP-Referenz

Signatur

ocinewcollection(resource $connection, string $tdo, string $schema = null): OCI-Collection|false

Beschreibung

ocinewcollection ist ein Alias der Funktion oci_new_collection und dient dazu, ein neues OCI-Collection-Objekt für Oracle-Datenbanken zu erstellen. Collections sind Oracle-spezifische Datentypen, die es ermöglichen, mengenartige Strukturen (z. B. VARRAYs oder verschachtelte Tabellen) in der Datenbank zu speichern und abzurufen.

Die Funktion wird typischerweise verwendet, wenn man Oracle-PL/SQL-Prozeduren aufruft, die Collection-Parameter erwarten, oder wenn man Collection-Daten aus der Datenbank auslesen und in PHP weiterverarbeiten möchte. Das zurückgegebene Objekt bietet Methoden wie append(), getElem(), assignElem() und free().

Hinweis: Da es sich um einen veralteten Alias handelt, sollte in neuem Code stets die Originalfunktion oci_new_collection verwendet werden. Der Alias existiert aus Gründen der Abwärtskompatibilität.

Voraussetzung für die Nutzung ist eine aktive Oracle-Datenbankverbindung sowie die OCI8-Erweiterung für PHP.

Parameter

Name	Typ	Beschreibung
$connection Pflicht	resource	Eine gültige Oracle-Verbindungsressource, wie sie z. B. von `oci_connect()`, `oci_pconnect()` oder `oci_new_connect()` zurückgegeben wird.
$tdo Pflicht	string	Der Name des Oracle-Typs (Type Descriptor Object), z. B. `'MY_VARRAY_TYPE'`. Muss ein gültiger, in der Oracle-Datenbank definierter Collection-Typ sein.
$schema	string	Das Schema, in dem der Typ definiert ist. Wird dieser Parameter weggelassen oder ist `null`, wird das Schema des aktuell verbundenen Benutzers verwendet.

Rückgabewert

Typ

OCI-Collection|false

Beschreibung

Gibt bei Erfolg ein OCI-Collection-Objekt zurück, mit dem Collection-Elemente gelesen und geschrieben werden können. Im Fehlerfall wird false zurückgegeben.

Beispiele

Collection erstellen und Elemente hinzufügen

<?php
// Verbindung zur Oracle-Datenbank herstellen
$conn = oci_connect('benutzer', 'passwort', 'meine_db');

if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

// Neues Collection-Objekt für einen definierten Oracle-VARRAY-Typ erstellen
$collection = ocinewcollection($conn, 'MY_NUM_ARRAY', 'SCOTT');

if ($collection === false) {
    $e = oci_error($conn);
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

// Elemente zur Collection hinzufügen
$collection->append(10);
$collection->append(20);
$collection->append(30);

echo 'Anzahl Elemente: ' . $collection->size() . PHP_EOL;

// Erstes Element ausgeben (Index 0)
$element = $collection->getElem(0);
echo 'Erstes Element: ' . $element . PHP_EOL;

// Ressourcen freigeben
$collection->free();
oci_close($conn);
?>

Anzahl Elemente: 3 Erstes Element: 10

Collection an PL/SQL-Prozedur übergeben

<?php
$conn = oci_connect('benutzer', 'passwort', 'meine_db');

// Collection-Objekt erstellen
$collection = ocinewcollection($conn, 'MY_STR_VARRAY');
$collection->append('alpha');
$collection->append('beta');
$collection->append('gamma');

// PL/SQL-Anweisung, die eine Collection entgegennimmt
$sql = 'BEGIN process_names(:names); END;';
$stmt = oci_parse($conn, $sql);

// Collection als Bind-Variable übergeben
oci_bind_by_name($stmt, ':names', $collection, -1, OCI_B_NTY);
oci_execute($stmt);

echo 'PL/SQL-Prozedur erfolgreich aufgerufen.' . PHP_EOL;

$collection->free();
oci_free_statement($stmt);
oci_close($conn);
?>

PL/SQL-Prozedur erfolgreich aufgerufen.

// Wichtig · Fallstricke

Veralteter Alias: ocinewcollection ist ein Alias von oci_new_collection. In neuem Code sollte ausschließlich oci_new_collection verwendet werden, da Aliase in zukünftigen PHP-Versionen entfernt werden könnten.

Ressourcenverwaltung: Das erstellte Collection-Objekt sollte nach der Verwendung stets mit der Methode free() freigegeben werden, um Speicherlecks zu vermeiden.

Voraussetzung: Die OCI8-Erweiterung muss in der PHP-Konfiguration aktiviert sein (extension=oci8), und eine gültige Oracle-Client-Installation muss vorhanden sein.

Siehe auch

oci_new_collection oci_connect oci_bind_by_name oci_new_descriptor