oci_bind_array_by_name — Funktion · PHP-Referenz

Signatur

oci_bind_array_by_name(resource $statement, string $param, array &$var, int $max_array_length, int $max_item_length = -1, int $type = SQLT_AFC): bool

Beschreibung

oci_bind_array_by_name() ermöglicht es, ein PHP-Array direkt an einen PL/SQL-Array-Parameter einer Oracle-Stored-Procedure oder eines anonymen PL/SQL-Blocks zu binden. Im Gegensatz zu oci_bind_by_name(), das einzelne skalare Werte bindet, unterstützt diese Funktion das Übergeben und Empfangen ganzer Mengen von Werten in einem einzigen Datenbankaufruf.

Die Funktion arbeitet mit Call-by-Reference: Das Array $var wird direkt an den Statement-Handle gekoppelt. Beim Aufruf von oci_execute() werden die aktuellen Inhalte des Arrays an Oracle übergeben. Falls die Prozedur Werte zurückschreibt (OUT-Parameter), werden diese nach der Ausführung in $var gespiegelt.

Der Parameter $max_array_length legt die maximale Anzahl der Array-Elemente fest, die Oracle reserviert. Er muss mindestens so groß sein wie das tatsächlich übergebene Array. $max_item_length definiert die maximale Länge eines einzelnen Elements in Bytes; der Wert -1 lässt PHP automatisch die maximale Länge aus dem Array ermitteln.

Typische Einsatzszenarien sind Massenoperationen (Bulk-INSERT/UPDATE über PL/SQL-Tabellen), der Aufruf von Prozeduren mit Array-IN/OUT-Parametern sowie die Abfrage von mehreren Werten in einem einzigen Roundtrip zur Datenbank.

Parameter

Name	Typ	Default	Beschreibung
$statement Pflicht	resource		Ein gültiger OCI-Statement-Handle, der von `oci_parse()` zurückgegeben wurde.
$param Pflicht	string		Der Name des Bind-Parameters im SQL/PL/SQL-Statement, z. B. `':my_array'`. Der Doppelpunkt ist optional.
$var Pflicht	array		Das PHP-Array, das gebunden wird. Wird als Referenz übergeben, damit OUT-Werte nach `oci_execute()` direkt darin erscheinen.
$max_array_length Pflicht	int		Die maximale Anzahl von Elementen, die Oracle für diesen Array-Parameter reserviert. Muss >= Anzahl der tatsächlichen Array-Elemente sein.
$max_item_length	int	-1	Maximale Länge eines einzelnen Array-Elements in Bytes. Bei `-1` ermittelt PHP die Länge automatisch aus dem aktuellen Array-Inhalt.
$type	int	SQLT_AFC	Oracle-Datentyp-Konstante für die Array-Elemente. Gültige Werte sind z. B. `SQLT_NUM`, `SQLT_INT`, `SQLT_AFC` (CHAR), `SQLT_CHR` (VARCHAR2), `SQLT_VCS`, `SQLT_AVC`, `SQLT_STR`, `SQLT_LVC`, `SQLT_FLT`, `SQLT_ODT`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiger Statement-Handle oder ungültige Parameter).

Beispiele

Array-IN-Parameter an eine PL/SQL-Prozedur übergeben

<?php
// Verbindung zur Oracle-Datenbank herstellen
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

// PL/SQL-Prozedur, die eine Liste von IDs verarbeitet:
// CREATE OR REPLACE PROCEDURE process_ids(p_ids IN DBMS_SQL.NUMBER_TABLE) IS ...
$sql = 'BEGIN process_ids(:p_ids); END;';

$stmt = oci_parse($conn, $sql);

$ids = [10, 20, 30, 40, 50];

// PHP-Array an den Oracle-Parameter :p_ids binden
oci_bind_array_by_name(
    $stmt,
    ':p_ids',
    $ids,
    count($ids),   // max_array_length
    -1,            // max_item_length: automatisch
    SQLT_INT       // Oracle-Datentyp: Integer
);

oci_execute($stmt);
echo "Prozedur erfolgreich aufgerufen.\n";

oci_free_statement($stmt);
oci_close($conn);

Prozedur erfolgreich aufgerufen.

Array-OUT-Parameter lesen (Rückgabe von Werten aus PL/SQL)

<?php
// Verbindung herstellen
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

// PL/SQL-Block, der ein String-Array befüllt
$sql = '
DECLARE
  TYPE t_names IS TABLE OF VARCHAR2(50) INDEX BY PLS_INTEGER;
  v_names t_names;
BEGIN
  v_names(1) := \'Alice\';
  v_names(2) := \'Bob\';
  v_names(3) := \'Charlie\';
  :out_names := v_names;
END;';

$stmt = oci_parse($conn, $sql);

// Leeres Array vorbereiten; max. 10 Elemente, je max. 50 Zeichen, Typ VARCHAR2
$outNames = [];
oci_bind_array_by_name(
    $stmt,
    ':out_names',
    $outNames,
    10,       // max_array_length
    50,       // max_item_length: 50 Zeichen
    SQLT_CHR  // VARCHAR2
);

oci_execute($stmt);

// Nach execute enthält $outNames die von Oracle geschriebenen Werte
foreach ($outNames as $name) {
    echo $name . "\n";
}

oci_free_statement($stmt);
oci_close($conn);

Alice Bob Charlie

// Wichtig · Fallstricke

Typen beachten: Der $type-Parameter muss zum tatsächlichen PL/SQL-Typ passen. Ein falscher Typ führt zu ORA--Fehlern zur Laufzeit, nicht beim Binden.

$max_array_length korrekt setzen: Wenn dieser Wert kleiner ist als die Anzahl der Elemente im Array, werden überschüssige Elemente stillschweigend abgeschnitten. Bei OUT-Parametern muss er groß genug sein, um alle Rückgabewerte aufzunehmen.

Nur für PL/SQL-Arrays: Diese Funktion bindet keine SQL-Arrays für z. B. WHERE id IN (:arr). Für solche Fälle muss der SQL-Text dynamisch aufgebaut oder eine PL/SQL-Hilfsprozedur verwendet werden.

OCI8-Erweiterung erforderlich: Die Funktion ist nur verfügbar, wenn PHP mit der OCI8-Erweiterung kompiliert oder diese als Shared Extension geladen wurde (extension=oci8).

Siehe auch

oci_bind_by_name oci_parse oci_execute oci_error oci_free_statement