Signatur
Beschreibung
oci_connect() öffnet eine Verbindung zu einer Oracle-Datenbank und gibt bei Erfolg ein Verbindungs-Handle (Resource) zurück, das für alle weiteren OCI-Funktionen (z. B. oci_parse(), oci_execute()) benötigt wird. Bei einem Fehler wird false zurückgegeben.
Innerhalb eines PHP-Requests werden Verbindungen mit identischen Parametern (username, password, connection_string) intern wiederverwendet (Connection-Caching). Das bedeutet: Mehrere Aufrufe von oci_connect() mit denselben Zugangsdaten liefern dasselbe zugrundeliegende Datenbank-Handle. Dies spart Ressourcen, kann aber zu unerwarteten Nebeneffekten führen, wenn man parallele, voneinander unabhängige Transaktionen erwartet – in diesem Fall sollte oci_new_connect() verwendet werden.
Der optionale Parameter $connection_string nimmt einen Oracle Easy Connect-String (z. B. localhost/XE), einen TNS-Namen aus der tnsnames.ora oder einen vollständigen TNS-Deskriptor entgegen. Wird er weggelassen, wird die Umgebungsvariable ORACLE_SID verwendet. Mit $encoding lässt sich der Zeichensatz der Verbindung (z. B. AL32UTF8) explizit festlegen.
Für langlebige Prozesse oder Webserver-Umgebungen mit vielen Anfragen empfiehlt sich alternativ oci_pconnect() (persistente Verbindung). Mit dem Parameter $session_mode können besondere Modi wie OCI_SYSDBA oder OCI_SYSOPER aktiviert werden, um administrative Verbindungen herzustellen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $username Pflicht | string | Der Oracle-Benutzername für die Anmeldung. | |
| $password Pflicht | string | Das Passwort des Oracle-Benutzers. | |
| $connection_string | string|null | null | Oracle Easy Connect-String (z. B. localhost/XEPDB1), ein TNS-Name oder ein vollständiger TNS-Deskriptor. Wird null oder kein Wert übergeben, greift die Umgebungsvariable ORACLE_SID. |
| $encoding | string | Der Zeichensatz der Verbindung, z. B. AL32UTF8 oder WE8ISO8859P15. Ein leerer String übernimmt den Zeichensatz aus der Oracle-Umgebung (NLS_LANG). |
|
| $session_mode | int | OCI_DEFAULT | Verbindungsmodus. Mögliche Werte: OCI_DEFAULT, OCI_SYSDBA, OCI_SYSOPER, OCI_CRED_EXT (externe Authentifizierung). Administrative Modi erfordern entsprechende Oracle-Berechtigungen. |
Rückgabewert
false zurückgegeben. Fehlerdetails können mit oci_error() abgefragt werden.Beispiele
Einfache Verbindung und SELECT-Abfrage
<?php
$conn = oci_connect('hr', 'geheimesPasswort', 'localhost/XE', 'AL32UTF8');
if (!$conn) {
$e = oci_error();
trigger_error(htmlspecialchars($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$sql = 'SELECT employee_id, last_name FROM employees WHERE rownum <= 5';
$stmt = oci_parse($conn, $sql);
oci_execute($stmt);
while ($row = oci_fetch_assoc($stmt)) {
echo $row['EMPLOYEE_ID'] . ': ' . $row['LAST_NAME'] . PHP_EOL;
}
oci_free_statement($stmt);
oci_close($conn);Verbindung mit TNS-Namen und Fehlerbehandlung
<?php
// TNS-Name 'PROD_DB' ist in tnsnames.ora definiert
$conn = oci_connect('app_user', getenv('DB_PASSWORD'), 'PROD_DB');
if ($conn === false) {
$error = oci_error();
// Fehlermeldung NIEMALS direkt an den Browser ausgeben – Loggen statt anzeigen!
error_log('Oracle-Verbindungsfehler: ' . $error['message']);
http_response_code(503);
exit('Datenbankverbindung nicht möglich.');
}
echo 'Verbindung erfolgreich hergestellt.' . PHP_EOL;
// ... weitere Datenbankoperationen ...
oci_close($conn);Administrative Verbindung als SYSDBA
<?php
// SYSDBA-Verbindung für administrative Aufgaben (z. B. Startup/Shutdown)
$conn = oci_connect('sys', 'sys_passwort', 'localhost/XE', '', OCI_SYSDBA);
if (!$conn) {
$e = oci_error();
die('SYSDBA-Verbindung fehlgeschlagen: ' . $e['message']);
}
echo 'SYSDBA-Verbindung erfolgreich.';
oci_close($conn);// Wichtig · Fallstricke
Sicherheit: Passwörter niemals im Quellcode hartcodieren. Stattdessen Umgebungsvariablen (getenv()) oder sichere Konfigurationsdateien außerhalb des Web-Roots verwenden. Fehlermeldungen von oci_error() können sensible Informationen (Datenbankstruktur, Zugangsdaten) enthalten – diese niemals ungeprüft an den Browser ausgeben.
Connection-Caching: oci_connect() gibt bei identischen Verbindungsparametern innerhalb desselben PHP-Prozesses dasselbe Handle zurück. Wer wirklich isolierte Verbindungen (und damit unabhängige Transaktionen) benötigt, muss oci_new_connect() nutzen.
Persistente Verbindungen: Für Webserver-Umgebungen mit hohem Verbindungsaufkommen empfiehlt sich oci_pconnect(). Persistente Verbindungen werden nach dem Skript-Ende nicht geschlossen, sondern im Pool gehalten. Dies erfordert ein sorgfältiges Verbindungsmanagement (Rollback offener Transaktionen etc.).
Extension: oci_connect() erfordert die aktivierte OCI8-Extension (extension=oci8 in der php.ini) sowie eine installierte Oracle-Client-Bibliothek (Instant Client oder vollständige Oracle-Installation).