oci_connect

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

oci_connectEstablece una conexión con un servidor Oracle

Descripción

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

Devuelve un identificador de conexión, necesario para la mayoría de las llamadas OCI8.

Para mejorar el rendimiento, la mayoría de las aplicaciones deberían utilizar conexiones persistentes con oci_pconnect() en lugar de oci_connect(). Consulte la sección sobre la gestión de conexiones para obtener información general sobre la gestión de conexiones y el agrupamiento de conexiones.

Las llamadas siguientes (tras la primera) a la función oci_connect() con los mismos parámetros devolverán el manejador de conexión devuelto en la primera llamada. Esto significa que las transacciones realizadas sobre un manejador estarán activas en los demás, siempre que utilicen la misma conexión subyacente. Si 2 manejadores deben tener transacciones aisladas, utilice en su lugar la función oci_new_connect().

Parámetros

username

El nombre de usuario de Oracle.

password

La contraseña del usuario.

connection_string

Contiene la instancia de Oracle a la que conectarse. Puede ser una » cadena de Conexión Sencilla (Easy Connect), o un Nombre de Conexión del fichero tnsnames.ora, o el nombre de una instancia local de Oracle.

Si no se especifica, PHP utiliza variables de entorno como TWO_TASK (en Linux) o LOCAL (en Windows) y ORACLE_SID para determinar la instancia de Oracle a la que conectarse.

Para utilizar el método de nomenclatura de Conexión Sencila, PHP debe estar vinculado con las bibliotecas cliente de Oracle 10g o superiores. La cadena de Conexión Sencilla para Oracle 10g se utiliza de la siguiente forma: [//]nombre_host[:puerto][/nombre_servicio]. Desde Oracle 11g, la sintaxis es: [//]nombre_host[:puerto][/nombre_servicio][:tipo_servicio][/nombre_instancia]. Los nombres de servicio pueden encontrarse ejecuntado la utilidad de Oracle lsnrctl status en el servidor donde se encuentra la base de datos.

El fichero tnsnames.ora puede estar en la ruta de búsqueda de Oracle Net, la cual incluye $ORACLE_HOME/network/admin y /etc. De forma alternativa, establezca TNS_ADMIN para que $TNS_ADMIN/tnsnames.ora sea leído. Asegúrse que el demonio web tiene acceso de lectura al fichero.

encoding

Determina el juego de caracteres usado por las bibliotecas cliente de Oracle. El juego de caracteres no tiene por que coinicidir con el utilizado en la base de datos. Si no coinicide, Oracle intentará hacer lo posible para convertir los datos entre los dos juegos de caracteres. Dependiendo del juego de caracteres que se esté usando, podría no proporcionarse resultados útiles. La conversión también añade algo de carga extra de tiempo.

Si no se especifica, las bibliotacas cliente de Oracle determinarán el juego de caracteres desde la variable de entorno NLS_LANG.

Pasar este parámetro puede reducir el tiempo que toma en conectarse.

session_mode

Este parámetro está disponible desde la versión 5 de PHP (PECL OCI8 1.1) y acepta los siguientes valores: OCI_DEFAULT, OCI_SYSOPER y OCI_SYSDBA. Si se especifica OCI_SYSOPER o OCI_SYSDBA, esta función intentará establecer una conexión privilegiada con las credenciales externas. Las conexiones privilegiadas están desactivadas por omisión. Para activarlas hay que establecer oci8.privileged_connect a On.

En PHP 5.3 (PECL OCI8 1.3.4) se introdujo el valor de modo OCI_CRED_EXT. Esto indica a Oracle que utilice la autenticación Externa o del SO, la cual debe estar configurada en la base de datos. La bandera OCI_CRED_EXT sólo puede usarse con el nombre de usuario "/" y la contraseña en blanco. oci8.privileged_connect podría ser On o Off.

OCI_CRED_EXT podría estar en combinación con los modos OCI_SYSOPER o OCI_SYSDBA.

OCI_CRED_EXT no se admite en Windows por razones de seguridad.

Valores devueltos

Devuelve un identificador de conexión o false si ocurre un error.

Historial de cambios

Versión Descripción
8.0.0, PECL OCI8 3.0.0 connection_string ahora es nullable.

Ejemplos

Ejemplo #1 Ejemplo con oci_connect() utilizando la sintaxis simplificada

<?php

// Conexión al servicio XE (es decir, la base de datos) en la máquina "localhost"
$conn = oci_connect('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) : "") . "</td>\n";
}
echo
"</tr>\n";
}
echo
"</table>\n";

?>

Ejemplo #2 Ejemplo con oci_connect() utilizando un nombre de conexión de red

<?php

// Conexión a la base de datos MYDB descrita en el archivo tnsnames.ora,
// Un ejemplo de entrada tnsnames.ora para MYDB podría ser:
// MYDB =
// (DESCRIPTION =
// (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
// (CONNECT_DATA =
// (SERVER = DEDICATED)
// (SERVICE_NAME = XE)
// )
// )

$conn = oci_connect('hr', 'welcome', 'MYDB');
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) : "") . "</td>\n";
}
echo
"</tr>\n";
}
echo
"</table>\n";

?>

Ejemplo #3 Ejemplo con oci_connect() utilizando un juego de caracteres específico

<?php

$conn
= oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
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) : "") . "</td>\n";
}
echo
"</tr>\n";
}
echo
"</table>\n";

?>

Ejemplo #4 Ejemplo con múltiples llamadas a la función oci_connect()

<?php

$c1
= oci_connect("hr", "welcome", 'localhost/XE');
$c2 = oci_connect("hr", "welcome", 'localhost/XE');

// Tanto $c1 como $c2 muestran el mismo identificador de recursos PHP, lo que significa
// que se trata de la misma conexión a la base de datos
echo "c1 is $c1<br>\n";
echo
"c2 is $c2<br>\n";

function
create_table($conn)
{
$stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
oci_execute($stmt);
echo
"Created table<br>\n";
}

function
drop_table($conn)
{
$stmt = oci_parse($conn, "drop table hallo");
oci_execute($stmt);
echo
"Dropped table<br>\n";
}

function
insert_data($connname, $conn)
{
$stmt = oci_parse($conn, "insert into hallo
values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))"
);
oci_execute($stmt, OCI_DEFAULT);
echo
"$connname inserted row without committing<br>\n";
}

function
rollback($connname, $conn)
{
oci_rollback($conn);
echo
"$connname rollback<br>\n";
}

function
select_data($connname, $conn)
{
$stmt = oci_parse($conn, "select * from hallo");
oci_execute($stmt, OCI_DEFAULT);
echo
"$connname ----selecting<br>\n";
while (
oci_fetch($stmt)) {
echo
" " . oci_result($stmt, "TEST") . "<br>\n";
}
echo
"$connname ----done<br>\n";
}

create_table($c1);

insert_data('c1', $c1); // Inserta una fila utilizando c1
sleep(2); // Se espera para ver un timestamp diferente para la segunda fila
insert_data('c2', $c2); // Inserta una fila utilizando c2

select_data('c1', $c1); // Se devuelven los resultados de las 2 inserciones
select_data('c2', $c2); // Se devuelven los resultados de las 2 inserciones

rollback('c1', $c1); // Revertir la transacción utilizando c1

select_data('c1', $c1); // Las 2 inserciones han sido revertidas
select_data('c2', $c2);

drop_table($c1);

// El cierre de una conexión hace que las variables PHP sean inaccesibles, pero las demás
// pueden seguir siendo utilizadas
oci_close($c1);
echo
"c1 is $c1<br>\n";
echo
"c2 is $c2<br>\n";

// Salida:
// c1 is Resource id #5
// c2 is Resource id #5
// Created table
// c1 inserted row without committing
// c2 inserted row without committing
// c1 ----selecting
// 09-DEC-09 12:14:43
// 09-DEC-09 12:14:45
// c1 ----done
// c2 ----selecting
// 09-DEC-09 12:14:43
// 09-DEC-09 12:14:45
// c2 ----done
// c1 rollback
// c1 ----selecting
// c1 ----done
// c2 ----selecting
// c2 ----done
// Dropped table
// c1 is
// c2 is Resource id #5

?>

Notas

Nota:

Si ha ocurrido un problema durante la instalación de la extensión OCI8, una de las manifestaciones será un problema durante la conexión. Consulte la sección Instalación/Configuración para obtener más información en caso de errores.

Ver también