Signatur
Beschreibung
oci_set_client_identifier() weist einer bestehenden Oracle-Datenbankverbindung einen frei wählbaren Client-Identifier zu. Dieser Wert wird in der Oracle-Systemansicht V$SESSION in der Spalte CLIENT_IDENTIFIER gespeichert und steht damit für Monitoring, Auditing und Tracing zur Verfügung.
Der Client-Identifier wird typischerweise genutzt, um in Connection-Pooling-Szenarien den eigentlichen Endbenutzer einer Anwendung an die Datenbankschicht zu übermitteln. Da bei gepoolten Verbindungen alle Anfragen unter einem gemeinsamen Datenbankbenutzer laufen, ermöglicht der Client-Identifier trotzdem die Zuordnung einzelner Operationen zu konkreten Anwendungsbenutzern.
Der gesetzte Wert wird bei der nächsten Interaktion mit der Datenbank übertragen. Er kann über Oracle-Funktionen wie DBMS_SESSION.SET_IDENTIFIER oder intern über OCI abgerufen werden. Er bleibt bis zum Ende der Verbindung oder bis zum nächsten Setzen eines anderen Wertes erhalten.
Besonders in Verbindung mit Oracle-Features wie DBMS_MONITOR, Fine Grained Auditing oder dem Application Context ist diese Funktion äußerst nützlich, da sie granulares Tracing auf Benutzerebene ermöglicht, ohne separate Datenbankverbindungen pro Benutzer aufbauen zu müssen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection Pflicht | resource | Eine gültige OCI8-Verbindungsressource, die zuvor mit oci_connect(), oci_pconnect() oder oci_new_connect() erzeugt wurde. |
|
| $client_id Pflicht | string | Der Client-Identifier als Zeichenkette, die dem aktuellen Datenbankbenutzer in V$SESSION.CLIENT_IDENTIFIER zugeordnet wird. Oracle erlaubt maximal 64 Byte. Ein leerer String setzt den Wert zurück. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler, z. B. wenn die übergebene Verbindungsressource ungültig ist.Beispiele
Client-Identifier für Monitoring setzen
<?php
$conn = oci_connect('hr', 'geheim', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}
// Anwendungsbenutzer an Oracle übermitteln
$appUser = 'max.mustermann@example.com';
oci_set_client_identifier($conn, $appUser);
// Abfrage ausführen — in V$SESSION ist nun CLIENT_IDENTIFIER gesetzt
$stid = oci_parse($conn, 'SELECT SYSDATE FROM dual');
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
echo 'Datum: ' . $row['SYSDATE'] . PHP_EOL;
// Nachprüfen, welcher Client-Identifier aktiv ist
$check = oci_parse($conn, "SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') AS cid FROM dual");
oci_execute($check);
$info = oci_fetch_array($check, OCI_ASSOC);
echo 'Client-ID in DB: ' . $info['CID'] . PHP_EOL;
oci_free_statement($stid);
oci_free_statement($check);
oci_close($conn);Client-Identifier bei gepoolten Verbindungen zurücksetzen
<?php
// Bei persistenten Verbindungen sollte der Identifier
// am Anfang jeder Anfrage neu gesetzt (oder geleert) werden.
$conn = oci_pconnect('app_user', 'geheim', 'localhost/PROD');
// Sicherstellen, dass kein alter Wert aus dem Pool übernommen wird
oci_set_client_identifier($conn, '');
// Dann den aktuellen Benutzer aus der Session laden
session_start();
if (!empty($_SESSION['username'])) {
oci_set_client_identifier($conn, $_SESSION['username']);
}
$stid = oci_parse($conn, 'SELECT COUNT(*) AS cnt FROM orders');
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
echo 'Bestellungen: ' . $row['CNT'] . PHP_EOL;
oci_free_statement($stid);
// Verbindung nicht schließen — sie geht zurück in den Pool// Wichtig · Fallstricke
Sicherheitshinweis: Der Client-Identifier sollte niemals ungeprüfte Benutzereingaben enthalten. Obwohl er für die SQL-Ausführung selbst nicht genutzt wird, kann er in Audit-Logs und Datenbankansichten erscheinen. Bereinigen oder validieren Sie den Wert stets, bevor er gesetzt wird.
Gepoolte Verbindungen: Bei persistenten Verbindungen (oci_pconnect()) bleibt der zuletzt gesetzte Wert erhalten. Es ist daher empfehlenswert, den Identifier zu Beginn jeder Anfrage explizit zu setzen oder mit einem leeren String zurückzusetzen, um Datenlecks zwischen verschiedenen Anfragen zu vermeiden.
Maximale Länge: Oracle beschränkt den Client-Identifier auf 64 Byte. Längere Werte werden ggf. abgeschnitten oder führen zu einem Fehler, abhängig von der Oracle-Version.
Die Funktion überträgt den Wert nicht sofort, sondern erst beim nächsten tatsächlichen Round-Trip zur Datenbank. Sie steht nur zur Verfügung, wenn PHP mit der OCI8-Erweiterung kompiliert wurde.