[edit] Last updated: Thu, 12 Jan 2012

oci_connect

(PHP 5, PECL OCI8 >= 1.1.0)

oci_connect — Connect to an Oracle database

Descrierea

resource oci_connect ( string $username , string $password [, string $connection_string [, string $character_set [, int $session_mode ]]] )

Returns a connection identifier needed for most other OCI8 operations.

See Connection Handling for general information on connection management and connection pooling.

From PHP 5.1.2 (PECL OCI8 1.1) oci_close() can be used to close the connection.

The second and subsequent calls to oci_connect() with the same parameters will return the connection handle returned from the first call. This means that transactions in one handle are also in the other handles, because they use the same underlying database connection. If two handles need to be transactionally isolated from each other, use oci_new_connect() instead.

Parametri

username

The Oracle user name.

password

The password for username.

connection_string

Conține instanța Oracle la care se efectuează conectarea. Poate fi un » șir Easy Connect, sau o Denumire de conexiune din fișierul tnsnames.ora, sau denumirea unei instanțe locale Oracle.

Dacă nu este specificat, PHP utilizează variabile de mediu, cum ar fi TWO_TASK (în Linux) sau LOCAL (în Windows) și ORACLE_SID pentru a determina instanța Oracle la care trebuie efectuată conexiunea.

Pentru a utiliza metoda Easy Connect, PHP trebuie să fie legat cu bibliotecile-client Oracle 10g sau ulterioare. Șirul Easy Connect pentru Oracle 10g este de forma: [//]host_name[:port][/service_name]. Pentru Oracle 11g sintaxa este: [//]host_name[:port][/service_name][:server_type][/instance_name]. Denumirile serviciilor pot fi găsite rulând utilitara Oracle lsnrctl status pe mașina unde rulează serverul de baze de date.

Fișierul tnsnames.ora poate fi în calea de căutare Oracle Net, care include $ORACLE_HOME/network/admin și /etc. Ca alternativă, poate fi stabilit TNS_ADMIN astfel încât $TNS_ADMIN/tnsnames.ora este citit. Asigurați-vă că serviciul web posedă dreptul de citire a acestui fișier.

character_set

Determină setul de caractere utilizat de bibliotecile-client Oracle. Setul de caractere nu trebuie în mod obligatoriu să se potrivească cu setul de caractere al bazei de date. Dacă nu se potrivește, Oracle va face tot posibilul să convertească datele din și în setul de caractere al bazei de date. În dependență de seturile de caractere aceasta poate să ducă la rezultate incorecte. Convertirea de asemenea impune un timp mărit de prelucrare.

Dacă nu este specificat, bibliotecile-client Oracle determină setul de caractere din variabila de mediu NLS_LANG.

Transmiterea acestui parametru poate reduce timpul de conectare.

session_mode

Acest parametru este disponibil începând cu versiunea PHP 5 (PECL OCI8 1.1) și acceptă următoarele valori: OCI_DEFAULT, OCI_SYSOPER și OCI_SYSDBA. Dacă sunt specificate OCI_SYSOPER sau OCI_SYSDBA, această funcție va încerca să stabilească o conexiune privilegiată utilizând credențiale externe. Conexiunile privilegiate sunt dezactivate implicit. Pentru a le activa trebuie să stabiliți oci8.privileged_connect în On.

PHP 5.3 (PECL OCI8 1.3.4) a introdus valoarea modului OCI_CRED_EXT. Aceasta indică Oracle să utilizeze autentificare Externă sau la nivel de S.O., ceea ce trebuie configurat în baza de date. Fanionul OCI_CRED_EXT poate fi utilizat doar cu numele utilizatorului "/" și o parolă vidă. oci8.privileged_connect poate fi On sau Off.

OCI_CRED_EXT poate fi combinat cu modul OCI_SYSOPER sau OCI_SYSDBA.

OCI_CRED_EXT nu este susținut pe Windows din motive de securitate.

Valorile întoarse

Returns a connection identifier or FALSE on error.

Exemple

Example #1 Basic oci_connect() using Easy Connect syntax


<?php

// Connects to the XE service (i.e. database) on the "localhost" machine
$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) : "&nbsp;") . "</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>

Example #2 Basic oci_connect() using a Network Connect name


<?php

// Connects to the MYDB database described in tnsnames.ora file,
// One example tnsnames.ora entry for MYDB could be:
//   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) : "&nbsp;") . "</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>

Example #3 oci_connect() with an explicit character set


<?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) : "&nbsp;") . "</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>

Example #4 Using multiple calls to oci_connect()


<?php

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

// Both $c1 and $c2 show the same PHP resource id meaning they use the
// same underlying database connection
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);   // Insert a row using c1
sleep(2);                 // sleep to show a different timestamp for the 2nd row
insert_data('c2', $c2);   // Insert a row using c2

select_data('c1', $c1);   // Results of both inserts are returned
select_data('c2', $c2);   // Results of both inserts are returned

rollback('c1', $c1);      // Rollback using c1

select_data('c1', $c1);   // Both inserts have been rolled back
select_data('c2', $c2);

drop_table($c1);

// Closing one of the connections makes the PHP variable unusable, but
// the other could be used
oci_close($c1);
echo "c1 is $c1<br>\n";
echo "c2 is $c2<br>\n";


// Output is:
//    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

?>

Note

Notă:
An incorrectly installed or configured OCI8 extension will often manifest itself as a connection problem or error. See Installing/Configuring for troubleshooting information.

Notă:
In PHP versions before 5.0.0 use ocilogon() instead. Denumirea veche a funcției poate fi încă utilizată în versiunile curente, însă ea este învechită și nu este recomandată.

Vedeți de asemenea

oci_pconnect() - Connect to an Oracle database using a persistent connection
oci_new_connect() - Connect to the Oracle server using a unique connection
oci_close() - Closes an Oracle connection

oci_define_by_name

oci_commit

[edit] Last updated: Thu, 12 Jan 2012

add a note User Contributed Notes oci_connect

peter at goldthorp dot com 07-Aug-2011 03:28


I started getting "ORA-12514: TNS:listener does not currently know of service requested in connect descriptor" errors when I upgraded my database instance from 10.2 to 11.2.  For some reason it would not resolve the oci_connect calls with the Easy Connect syntax (easy connect calls from sqlplus were fine).  I was able to workaround the issue by passing a tns connect string:





<?php


$db = "(DESCRIPTION=(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.XX.XXX)(PORT = 1521)))(CONNECT_DATA=(SID=XXXX)))";





$c1 = oci_connect("name","password",$db);


?>

jtacon at php dot net 07-Feb-2011 05:24


If you upgrades the OCI8, be sure to use the latest oracle instantclient version, otherwise you can receive an "ORA-24315: illegal attribute type" when trying to connect due to incompatibility with some versions.



HTH,

Javier Tacón

dali at dali dot net dot nz 06-Dec-2010 03:04


If you have issues connecting to an Oracle database from a script that's run via cron, make sure that your ORACLE_HOME environment variable is set correctly.



Add



ORACLE_HOME=/path/to/oracle/client



to the top of your cron file

Jonathon Robinson 15-Jun-2010 11:12


Regarding the following statement in the documentation:


"The second and subsequent calls to oci_connect() with the same parameters will return the connection handle returned from the first call."





There's one caveat here.  Subsequent calls to oci_connect() will only return the same connection handle as the first call as long as a reference is held to the original handle.





For example, the following code will generate *one* connection handle:





<?php


$dbh = oci_connect($username, $password, $conn_info);


// Do stuff


$dbh = oci_connect$username, $password, $conn_info);


// Do more stuff





The follow code will generate *two* connection handles:


getData();


// Do stuff


getData();


// Do more stuff





getData() {


    $dbh = oci_connect($username, $password, $conn_info);


    // Do stuff


}


?>





This is the result of PHP garbage collecting the handle at the end of the method scope.





If you want to isolate your DB layer through function calls but still want to leverage the fact that oci_connect can return the same handle, just keep a reference to the handle like so:





<?php


getData($username, $password, $conn_info) {


    $dbh = oci_connect($username, $password, $conn_info);


    $key = hash('md5', "$username|$password|$conn_info");


    $GLOBALS[$key] = $dbh;


    // Do stuff


}


?>





I originally logged this as a bug but apparently this is the expected behaviour, likely because oci_close($dbh) just calls unset($dbh).

webmaster at moisesjafet dot com 18-Apr-2010 11:57


In order to use UTF8 charset in Oracle, just indicate the bespoke charset in the connection function.





Example:





<?php


$conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');


?>





Please look on the manual page of oci_connect for details.





If you also want to on the fly localize your app (date formatting, decimal separator, and so on) additionally use NLS values by alter session statements.





Never forget to indicate the app's charset to the browser for proper display.

drew dot carmichael at gmail dot com 03-Jul-2009 01:55


When using the OCI_CRED_EXT in php 

if the ENV $ORACLE_SID is set the DB does not need to be specified explicitly and the connection will fail unless you provide a NULL DB value when creating the connection. 



The $ORACLE_SID trumps the TNS name look up for the connection. So even a manual connection string in the DB parameter will fail.



So when the $ORACLE_SID Env is set a NULL passed instead of the DB name connects successfully. 



Hope this saves some hair pulling when moving to %.3 and OS Authentications

Leandro da Cunha Campos 11-May-2009 11:04


ONE ALTERNATIVE OF CONNECT IN ORACLE RAC "Real Application Clusters"





<?php


$dbstr ="(DESCRIPTION =(ADDRESS = (PROTOCOL = TCP)(HOST =ip1)(PORT = 1521))


(CONNECT_DATA =


(SERVER = DEDICATED)


(SERVICE_NAME = banco)


(INSTANCE_NAME = banco1)))"; 


 


$dbstr1 ="(DESCRIPTION =(ADDRESS = (PROTOCOL = TCP)(HOST =ip2)(PORT = 1521))


(CONNECT_DATA =


(SERVER = DEDICATED)


(SERVICE_NAME = banco)


(INSTANCE_NAME = banco2)))"; 


 


if(!@($conn = oci_connect('user','password',$dbstr1)))


{ $conn = oci_connect('user','password',$dbstr) or die (ocierror()); }


?>

sixd at php dot net 21-Jul-2008 01:16


From PHP 5.3 onwards:



A new OCI_CRED_EXT flag can be passed as the "session_mode" parameter

to oci_connect(), oci_new_connect() and oci_pconnect().



  $c1 = oci_connect("/", "", $db, null, OCI_CRED_EXT);



This tells Oracle to do external or OS authentication, if configured

in the database.



OCI_CRED_EXT can only be used with username of "/" and a empty

password.  Oci8.privileged_connection may be On or Off.  



OCI_CRED_EXT is not supported on Windows for security reasons.



The new flag may be combined with the existing OCI_SYSOPER or

OCI_SYSDBA modes (note: oci8.privileged_connection needs to be On for

OCI_SYSDBA and OCI_SYSOPER), e.g.:



  $c1 = oci_connect("/", "", $db, null, OCI_CRED_EXT+OCI_SYSOPER);

sixd at php dot net 30-Jun-2008 04:33


If you want to specify a connection timeout in case there is network problem, you can edit the client side (e.g. PHP side) sqlnet.ora file and set SQLNET.OUTBOUND_CONNECT_TIMEOUT. This sets the upper time limit for establishing a connection right through to the DB, including the time for attempts to connect to other services.   It is available from Oracle 10.2.0.3 onwards.



In Oracle 11.1, a slightly lighter-weight solution TCP.CONNECT_TIMEOUT was introduced.  It also is a sqlnet.ora parameter.  It bounds just the TCP connection establishment time, which is mostly where connection problem are seen.



The client sqlnet.ora file should be put in the same directory as the tnsnames.ora file.

sebastien.barbieri _at_ gmail dot com 13-Sep-2006 09:42


When you are using Oracle 9.2+ I would say that you MUST use the CHARSET parameter.



Of course, you will not notice it until there is accented character... so just specify it and you will avoid a big headache.



So for example here is our Oracle internal conf:

select * from nls_database_parameters;

 

PARAMETER                      VALUE

------------------------------ ----------------------------------------

…

NLS_LANGUAGE                   AMERICAN

NLS_TERRITORY                  AMERICA

NLS_ISO_CURRENCY               AMERICA

NLS_CHARACTERSET               WE8ISO8859P15

…

 

And there our oci_connect call:



$dbch=ocilogon($user,$pass,$connectString,"WE8ISO8859P15");



Without that, you will get question mark (inversed), squares… instead of most accented character.



Don’t forget to use that for writing as well as for reading.

ben at onshop dot co dot uk 14-Jul-2005 05:25


There is a useful solution to the problem of securing connection information in the PHP Cookbook (O'Reilly) by David Sklar and Adam Trachtenberg. They propose using 'SetEnv' in the Apache configuration and then accessing the values from within a script using $_SERVER.





Unfortunately using the 'SetEnv' solution exposes your connection information to all users of that virtual host. If they run phpinfo.php or display $_SERVER, I found that they will see the password from any file under the root of that virtual host.





To restrict exposure to a particular directory or specific file:





1. First put an 'Include' to the secret file in httpd.conf. For example:





Include "/web/private/secret.txt"





2. In the password file, use the 'SetEnvIf' directive to enable the Environment variables by directory only or within a specific file. For example:





- For all files in the directory:





SetEnvIf Request_URI "/path/to/my/directory" ORACLE_PASS=5gHj790j





- For a specific file in the directory





SetEnvIf Request_URI "/path/to/my/directory/connection.oracle.php" ORACLE_PASS=5gHj790j

M0no at ethonfusino dot com 21-Nov-2002 10:04


If your oracle database is on a remote system within your local network and you don't want to worry about the tnsnames file you can try this.





$db = "(DESCRIPTION=(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.XX.XXX)(PORT = 1521)))(CONNECT_DATA=(SID=XXXX)))";





$c1 = ocilogon("name","password",$db);





Hope this helps someone.

add a note