ocicollgetelem — Funktion · PHP-Referenz

Signatur

ocicollgetelem(OCICollection $collection, int $index): mixed

Beschreibung

ocicollgetelem() ist ein prozeduraler Alias für die Methode OCICollection::getElem(). Die Funktion liest ein einzelnes Element aus einer Oracle-Collection (z. B. einem VARRAY oder einer TABLE-Typen) anhand des nullbasierten Index und gibt dessen Wert zurück.

Oracle-Collections werden über die OCI8-Erweiterung genutzt, um strukturierte Datentypen wie VARRAY oder TABLE OF ... aus PL/SQL-Procedures und -Funktionen zu empfangen oder an diese zu übergeben. Mit ocicollgetelem() kann auf einzelne Elemente zugegriffen werden, ohne die gesamte Collection in ein PHP-Array umzuwandeln.

Der Index ist nullbasiert, d. h. das erste Element befindet sich an Position 0. Liegt der angegebene Index außerhalb des gültigen Bereichs, wird false zurückgegeben.

Hinweis: Diese Funktion ist ein Alias und gilt seit PHP 8.0 als veraltet (deprecated). Es wird empfohlen, stattdessen die objektorientierte Methode OCICollection::getElem() zu verwenden.

Parameter

Name	Typ	Default	Beschreibung
$collection Pflicht	OCICollection		Ein gültiges `OCICollection`-Objekt, das zuvor über `oci_new_collection()` erstellt oder aus einer Oracle-Datenbankabfrage empfangen wurde.
$index Pflicht	int		Der nullbasierte Index des abzurufenden Elements. Das erste Element hat Index `0`.

Rückgabewert

Typ

mixed

Beschreibung

Gibt den Wert des Elements an der angegebenen Position zurück. Handelt es sich bei dem Element um ein Oracle-Objekt, wird ein OCICollection-Objekt zurückgegeben. Liegt der Index außerhalb des gültigen Bereichs oder tritt ein Fehler auf, wird false zurückgegeben.

Beispiele

Element einer Oracle-Collection per Index lesen

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

if (!$conn) {
    $err = oci_error();
    trigger_error('Verbindungsfehler: ' . $err['message'], E_USER_ERROR);
}

// Oracle-Typ-Name und Schema festlegen
$collection = oci_new_collection($conn, 'ODCIVARCHAR2LIST', 'SYS');

// Elemente zur Collection hinzufügen
$collection->append('Erstes Element');
$collection->append('Zweites Element');
$collection->append('Drittes Element');

// Element an Index 1 (zweites Element) lesen
$element = ocicollgetelem($collection, 1);
echo 'Element an Index 1: ' . $element . PHP_EOL;

// Element an Index 0 (erstes Element) lesen
$element0 = ocicollgetelem($collection, 0);
echo 'Element an Index 0: ' . $element0 . PHP_EOL;

// Ungültiger Index — gibt false zurück
$ungueltig = ocicollgetelem($collection, 99);
var_dump($ungueltig);

$collection->free();
oci_close($conn);

Element an Index 1: Zweites Element Element an Index 0: Erstes Element bool(false)

Empfehlung: Objektorientierte Methode OCICollection::getElem()

<?php
// Moderne, empfohlene Schreibweise anstelle des Alias ocicollgetelem()
$conn = oci_connect('benutzer', 'passwort', 'localhost/XE');

$collection = oci_new_collection($conn, 'ODCIVARCHAR2LIST', 'SYS');
$collection->append('Hallo');
$collection->append('Welt');

// OOP-Methode statt prozeduralem Alias verwenden
$element = $collection->getElem(0);
echo 'Erstes Element: ' . $element . PHP_EOL;

$collection->free();
oci_close($conn);

Erstes Element: Hallo

// Wichtig · Fallstricke

Deprecation: ocicollgetelem() ist ein Alias der Methode OCICollection::getElem(). Prozedurale OCI8-Aliasfunktionen gelten ab PHP 8.0 als veraltet und können in zukünftigen PHP-Versionen entfernt werden. Die Verwendung der objektorientierten Schnittstelle über OCICollection::getElem() wird dringend empfohlen.

Der Index ist nullbasiert. Ein Zugriff auf einen negativen oder zu großen Index gibt false zurück, ohne eine Fehlermeldung zu erzeugen — daher sollte der Rückgabewert stets mit === false geprüft werden.

Die OCI8-Erweiterung muss aktiviert sein (extension=oci8 in der php.ini), und es wird eine gültige Oracle-Datenbankverbindung benötigt.

Siehe auch

OCICollection::getElem oci_new_collection ocicollappend ocicollsize ocicollfree