Dutch PHP Conference 2025 - Call For Papers

oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnectConnect to an Oracle database using a persistent connection

Опис

oci_pconnect(
    string $username,
    string $password,
    ?string $connection_string = null,
    string $encoding = "",
    int $session_mode = OCI_DEFAULT
): resource|false

Creates a persistent connection to an Oracle server and logs on.

Persistent connections are cached and re-used between requests, resulting in reduced overhead on each page load; a typical PHP application will have a single persistent connection open against an Oracle server per Apache child process (or PHP FPM process). See the OCI8 Connection Handling and Connection Pooling section for more information.

Параметри

username

The Oracle user name.

password

The password for username.

connection_string

Містить примірник Oracle для з'єднання. Це може бути або » Easy Connect string, або Connect Name з файлу tnsnames.ora, або назва локального примірника Oracle.

Якщо не вказано або null, то PHP використовує змінні оточення, як от TWO_TASK (в Linux) або LOCAL (у Windows) та ORACLE_SID, щоб визначити примірник Oracle для з'єднання.

Для використання методу називання Easy Connect, PHP має бути скомпоновано з Oracle 10g або новішими клієнтськими бібліотеками. Easy Connect string для Oracle 10g має форму [//]назва_хосту[:порт][/назва_сервісу]. Починаючи з Oracle 11g, синтаксис наступний: [//]назва_хосту[:порт][/назва_сервісу][:тип_сервера][/назва_примірника]. Додаткові можливості були запроваджені в Oracle 19c, як от налаштування обмеженого у часі та постійного з'єднання. Докладніше про це у документації Oracle. Назви служб можна побачити, запустивши утиліту Oracle lsnrctl status на машині сервера бази даних.

Файл tnsnames.ora може бути на шляху пошуку Oracle Net, що містить /ваш/шлях/до/instantclient/network/admin, $ORACLE_HOME/network/admin та /etc. Як варіант, можна встановити TNS_ADMIN, тоді буде прочитано файл $TNS_ADMIN/tnsnames.ora. Вебсервер має мати право на читання цього файлу.

encoding

Визначає набір символів, які використовують клієнтські бібліотеки Oracle. Кодування може не збігатися з тим, що використовує база даних. Якщо так, Oracle намагатиметься перекодувати дані. Залежно від кодування, це може не давати прийнятні результати. Перетворення також збільшуватиме час виконання.

Якщо не визначено, то клієнтські бібліотеки Oracle оберуть кодування, яке вказано в змінній оточення NLS_LANG.

Визначення цього параметра може скоротити час з'єднання.

session_mode

Цей параметр доступний, починаючи з PHP 5 (PECL OCI8 1.1) та має такі допустимі значення: OCI_DEFAULT, OCI_SYSOPER і OCI_SYSDBA. Якщо вказано OCI_SYSOPER або OCI_SYSDBA, то ця функція намагатиметься встановити привілейоване підключення за допомогою зовнішніх облікових даних. Привілейовані з'єднання початково вимкнені. Для увімкнення необхідно директиві oci8.privileged_connect встановити значення On.

У PHP 5.3 (PECL OCI8 1.3.4) вводиться значення режиму OCI_CRED_EXT. Воно вказує Oracle використовувати зовнішню автентифікацію або автентифікацію операційної системи, котра має бути налаштована в базі даних. Прапорець OCI_CRED_EXT дозволено використовувати тільки з іменем користувача "/" та порожнім паролем. oci8.privileged_connect може бути On або Off.

OCI_CRED_EXT можна поєднувати з режимами OCI_SYSOPER або OCI_SYSDBA.

OCI_CRED_EXT не підтримується у Windows з міркувань безпеки.

Значення, що повертаються

Returns a connection identifier or false on error.

Приклади

Приклад #1 Basic oci_pconnect() Example using Easy Connect syntax

<?php

// Connects to the XE service (i.e. database) on the "localhost" machine
$conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
if (!
$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo
"<table border='1'>\n";
while (
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo
"<tr>\n";
foreach (
$row as $item) {
echo
" <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
echo
"</tr>\n";
}
echo
"</table>\n";

?>

See oci_connect() for further examples of parameter usage.

Примітки

Зауваження: The lifetime and maximum number of persistent Oracle connections per PHP process can be tuned by setting the following configuration values: oci8.persistent_timeout, oci8.ping_interval and oci8.max_persistent.

Прогляньте також

add a note

User Contributed Notes 2 notes

up
2
php at jaggard dot org dot uk
15 years ago
[Editor's note: OCI8 1.3 should not experience the problem described in this user comment. The first use of such a connection will return an Oracle error which will trigger a cleanup in PHP. Subsequent persistent connection calls will then succeed. For high availability you might consider doing consecutive oci_pconnect calls in your script.]

If you connect using oci_pconnect and the connection has logged you off but is still valid, there seems to be no way to re-use that connection. The next time I try oci_pconnect and then perform an oci_execute operation, I get a "ORA-01012: not logged on" warning. This problem remains, even if I close the connection using oci_close. I ended up with the following (rather annoying) code.

<?php
function getOracleConnection()
{
if (!
function_exists('oci_pconnect'))
return
false;
$toReturn = oci_pconnect('user', 'pass', 'db');
if (
$testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))
if (@
oci_execute($testRes))
if (@
oci_fetch_array($testRes))
return
$toReturn;
oci_close($toReturn);
if (!
function_exists('oci_connect'))
return
false;
$toReturn = oci_connect('user', 'pass', 'db');
if (
$testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))
if (@
oci_execute($testRes))
if (@
oci_fetch_array($testRes))
return
$toReturn;
oci_close($toReturn);
if (!
function_exists('oci_new_connect'))
return
false;
$toReturn = oci_new_connect('user', 'pass', 'db');
if (
$testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))
if (@
oci_execute($testRes))
if (@
oci_fetch_array($testRes))
return
$toReturn;
oci_close($toReturn);
return
false;
}
?>
up
0
gotankersley at NOSPAM dot com
12 years ago
Installed on CentOS 6.2, and had lots of trouble getting it to recognize tnsnames.ora. The fix for me was:

1. Make sure apache is getting the TNS_ADMIN env variable by putting it in the /etc/init.d/httpd file:
TNS_ADMIN=/usr/lib/oracle/11.2/client64/network/admin
export PATH TNS_ADMIN

This can be debugging in PHP by <?php echo system('env'); ?> and by verifying that TNS_ADMIN is there.

2. Make sure to use the name at the beginning of the tnsnames.ora file - not the SID (although ideally they should match. However, if the name at the beginning is XXXX.world then pconnect will expect this - not the SID)
To Top