oci_bind_by_name — Funktion · PHP-Referenz

Signatur

oci_bind_by_name(resource $statement, string $param, mixed &$var, int $max_length = -1, int $type = SQLT_CHR): bool

Beschreibung

oci_bind_by_name() verknüpft eine PHP-Variable mit einem benannten Platzhalter (z. B. :id) in einem zuvor mit oci_parse() vorbereiteten Oracle-Statement. Die Bindung erfolgt als Referenz, d. h. der Wert der Variable wird erst beim Aufruf von oci_execute() ausgewertet — was besonders beim Batch-Verarbeiten mehrerer Zeilen in einer Schleife nützlich ist.

Durch die Verwendung von Bind-Variablen werden SQL-Injection-Angriffe verhindert, da die übergebenen Werte niemals als SQL-Code interpretiert werden. Außerdem erlaubt Oracle-intern das Wiederverwenden des geparsten Ausführungsplans (Cursor-Caching), was die Performance erheblich verbessert.

Der Parameter $max_length gibt die maximale Länge des gebundenen Werts in Bytes an. Bei Eingabe-Binds (INTO-Klausel oder PL/SQL-OUT-Parameter) sollte ein ausreichend großer Wert gesetzt werden; bei reinen Eingabe-Werten kann -1 übergeben werden, um die Länge automatisch aus dem aktuellen Wert von $var zu ermitteln.

Über den Parameter $type lässt sich der Oracle-Datentyp explizit festlegen — relevant etwa bei LOB-Werten (SQLT_CLOB, SQLT_BLOB), Cursor-Referenzen (SQLT_RSET) oder booleschen PL/SQL-Werten (SQLT_BOL). Für einfache Zeichenketten und Zahlen ist der Standardwert SQLT_CHR in aller Regel ausreichend.

Parameter

Name	Typ	Default	Beschreibung
$statement Pflicht	resource		Ein gültiges OCI-Statement-Handle, das zuvor mit `oci_parse()` erzeugt wurde.
$param Pflicht	string		Der Name des Platzhalters im SQL-Statement, inklusive Doppelpunkt, z. B. `':id'` oder `':name'`. Groß-/Kleinschreibung wird nicht unterschieden.
$var Pflicht	mixed		Die PHP-Variable, die per Referenz gebunden wird. Der Wert wird erst bei `oci_execute()` gelesen bzw. bei OUT-Parametern nach der Ausführung befüllt.
$max_length	int	-1	Maximale Länge des Werts in Bytes. `-1` bedeutet, dass die aktuelle Länge von `$var` verwendet wird. Bei OUT-Parametern muss ein ausreichend großer Wert angegeben werden, z. B. `4000`.
$type	int	SQLT_CHR	Oracle-Datentyp der gebundenen Variable. Häufige Werte: `SQLT_CHR` (Zeichenkette), `SQLT_INT` (Integer), `SQLT_CLOB` (CLOB-Objekt), `SQLT_BLOB` (BLOB-Objekt), `SQLT_RSET` (REF CURSOR).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiges Statement-Handle oder unbekannter Platzhalter-Name).

Beispiele

Einfaches SELECT mit gebundener Eingabe-Variable

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

$sql  = 'SELECT vorname, nachname FROM mitarbeiter WHERE abteilung_id = :abt_id';
$stmt = oci_parse($conn, $sql);

$abteilungId = 10;
oci_bind_by_name($stmt, ':abt_id', $abteilungId, -1, SQLT_INT);

oci_execute($stmt);

while ($row = oci_fetch_assoc($stmt)) {
    echo $row['VORNAME'] . ' ' . $row['NACHNAME'] . PHP_EOL;
}

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

Max Mustermann Erika Musterfrau

Batch-INSERT mit Schleife und Bind-Variable

<?php
$conn = oci_connect('hr', 'geheim', 'localhost/XE');

$sql  = 'INSERT INTO produkte (id, bezeichnung) VALUES (:id, :bez)';
$stmt = oci_parse($conn, $sql);

$daten = [
    [1, 'Apfel'],
    [2, 'Birne'],
    [3, 'Kirsche'],
];

// Bind-Variablen werden einmalig gebunden
oci_bind_by_name($stmt, ':id',  $id,  -1, SQLT_INT);
oci_bind_by_name($stmt, ':bez', $bez, 50, SQLT_CHR);

foreach ($daten as [$id, $bez]) {
    // Beim nächsten oci_execute() werden die aktuellen Werte von $id und $bez verwendet
    oci_execute($stmt, OCI_NO_AUTO_COMMIT);
}

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

echo '3 Datensätze erfolgreich eingefügt.';

3 Datensätze erfolgreich eingefügt.

PL/SQL OUT-Parameter lesen

<?php
$conn = oci_connect('hr', 'geheim', 'localhost/XE');

$sql  = 'BEGIN :ergebnis := berechne_bonus(:emp_id); END;';
$stmt = oci_parse($conn, $sql);

$empId    = 7369;
$ergebnis = null;

oci_bind_by_name($stmt, ':emp_id',    $empId,    -1,   SQLT_INT);
oci_bind_by_name($stmt, ':ergebnis',  $ergebnis, 20,   SQLT_CHR);

oci_execute($stmt);

echo 'Bonus: ' . $ergebnis . ' EUR';

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

Bonus: 1250.00 EUR

// Wichtig · Fallstricke

Sicherheit: Bind-Variablen sind die einzig zuverlässige Methode, SQL-Injection bei Oracle zu verhindern. Niemals Benutzereingaben direkt per String-Konkatenation in SQL-Statements einbauen.

Referenz-Semantik: Da $var per Referenz gebunden wird, darf die Variable bis zum Aufruf von oci_execute() nicht mit unset() gelöscht werden. Bei der Schleifentechnik (Batch-INSERT) ist darauf zu achten, dass nach foreach die Schleifenvariable ihren letzten Wert behält — das ist in diesem Fall gewünscht.

LOB-Bindung: Für CLOB/BLOB-Werte muss zunächst ein LOB-Deskriptor via oci_new_descriptor() erstellt und dieser als $var übergeben werden. SQLT_CHR reicht für LOBs nicht aus.

max_length bei OUT-Parametern: Wird -1 gesetzt und $var ist initial null, kann Oracle keinen Speicher reservieren — es kommt zu einem Laufzeitfehler. Immer einen realistischen Maximalwert angeben.

Siehe auch

oci_parse oci_execute oci_bind_array_by_name oci_new_descriptor oci_fetch_assoc oci_connect