The Underground PHP

and Oracle Manual

CHRI STOPHER JONES AND ALI SON HOLLOWAY
P
H
P



Updated for Oracle Database Express Edition 11g Release 2
The Underground PHP and Oracle

Manual, Release 2.0, December 2012.

Copr!gh" # 200$, 2012 Oracle. %ll r!gh"s reser&ed.
The la"es" ed!"!on o' "h!s boo( !s a&a!lable 'ree onl!ne a")
http://www.oracle.com/technetwork/topics/php/underground-php-oracle-manual-098250.html
%u"hors) Chr!s"opher *ones and %l!son Hollo+a
Con"r!bu"ors and ac(no+ledgmen"s) ,lad!m!r -arr!ere, .u/! Ch!dambaran, Rober" Cle&enger,
%n"on Do&gal, 0e1 2urlong, Maur!ce 3amanho, Deepa( 3oel, 4ue Harper, Manuel Ho5'eld,
6en *acobs, 4r!na"h 6r!shnas+am, 4hoa!b .ar!, 4!mon .a+, 6r!shna Mohan, Cra!g Mohrman,
Chuc( Murra, 6e&!n 7eel, 6an" Pa"el, Charles Poulsen, 6ar"h!( Ra8an, R!chard Rendell, Ro
Rossebo, *e''re Rub!no'', M!chael 4e(urs(!, 4ree(umar 4eshadr!, Mohammad 4o+dagar,
Ma(o"o To1a+a, Todd Tr!chler, 4!mon 0a"", 9ah!, 4hup!ng 9hou.
The chap"er on global!1a"!on !s der!&ed 'rom "he Oracle Database Express Edition 2 Day Plus
PHP Developer Guide. The chap"er on connec"!on pool!ng !s der!&ed 'rom "he Oracle +h!"e
paper PHP Scalability and High Availability. The d!scuss!on on Cl!en" :den"!'!ers !s 'rom an OT7
ar"!cle PHP Web Auditing, Authoriation and !onitoring" The 'ounda"!on 'or "he chap"er on "he
7e"-eans :D; +as con"r!bu"ed b *e''re Rub!no''. The Oracle 4olar!s con"en" +as con"r!bu"ed
b Cra!g Mohrman. 0e gra"e'ull ac(no+ledge all "he people +ho con"r!bu"ed "o "he crea"!on
o' "h!s boo(.
Trademark Notice
Oracle and *a&a are reg!s"ered "rademar(s o' Oracle and<or !"s a''!l!a"es. O"her names ma be
"rademar(s o' "he!r respec"!&e o+ners. :n"el and :n"el =eon are "rademar(s or reg!s"ered
"rademar(s o' :n"el Corpora"!on. %ll 4P%RC "rademar(s are used under l!cense and are
"rademar(s or reg!s"ered "rademar(s o' 4P%RC :n"erna"!onal, :nc. %MD, Op"eron, "he %MD
logo, and "he %MD Op"eron logo are "rademar(s or reg!s"ered "rademar(s o' %d&anced M!cro
De&!ces. U7:= !s a reg!s"ered "rademar( o' The Open 3roup.
License Restrictions Warranty/Consequential Damages Disclaimer
Th!s so'"+are and rela"ed documen"a"!on are pro&!ded under a l!cense agreemen" con"a!n!ng
res"r!c"!ons on use and d!sclosure and are pro"ec"ed b !n"ellec"ual proper" la+s. ;/cep" as
e/pressl perm!""ed !n our l!cense agreemen" or allo+ed b la+, ou ma no" use, cop,
reproduce, "ransla"e, broadcas", mod!', l!cense, "ransm!", d!s"r!bu"e, e/h!b!", per'orm,
publ!sh, or d!spla an par", !n an 'orm, or b an means. Re&erse eng!neer!ng, d!sassembl,
or decomp!la"!on o' "h!s so'"+are, unless re>u!red b la+ 'or !n"eroperab!l!", !s proh!b!"ed.
Warranty Disclaimer
The !n'orma"!on con"a!ned here!n !s sub8ec" "o change +!"hou" no"!ce and !s no" +arran"ed "o
be error?'ree. :' ou '!nd an errors, please repor" "hem "o us !n +r!"!ng.
Restricted Rights Notice
:' "h!s !s so'"+are or rela"ed documen"a"!on "ha" !s del!&ered "o "he U.4. 3o&ernmen" or
anone l!cens!ng !" on behal' o' "he U.4. 3o&ernmen", "he 'ollo+!ng no"!ce !s appl!cable)
U.4. 3O,;R7M;7T ;7D U4;R4) Oracle programs, !nclud!ng an opera"!ng ss"em, !n"egra"ed
so'"+are, an programs !ns"alled on "he hard+are, and<or documen"a"!on, del!&ered "o U.4.
3o&ernmen" end users are @commerc!al compu"er so'"+are@ pursuan" "o "he appl!cable
2ederal %c>u!s!"!on Regula"!on and agenc?spec!'!c supplemen"al regula"!ons. %s such, use,
dupl!ca"!on, d!sclosure, mod!'!ca"!on, and adap"a"!on o' "he programs, !nclud!ng an opera"!ng
ss"em, !n"egra"ed so'"+are, an programs !ns"alled on "he hard+are, and<or documen"a"!on,
shall be sub8ec" "o l!cense "erms and l!cense res"r!c"!ons appl!cable "o "he programs. 7o o"her
r!gh"s are gran"ed "o "he U.4. 3o&ernmen".
Hazardous Applications Notice
Th!s so'"+are or hard+are !s de&eloped 'or general use !n a &ar!e" o' !n'orma"!on
managemen" appl!ca"!ons. :" !s no" de&eloped or !n"ended 'or use !n an !nheren"l dangerous
appl!ca"!ons, !nclud!ng appl!ca"!ons "ha" ma crea"e a r!s( o' personal !n8ur. :' ou use "h!s
so'"+are or hard+are !n dangerous appl!ca"!ons, "hen ou shall be respons!ble "o "a(e all
appropr!a"e 'a!l?sa'e, bac(up, redundanc, and o"her measures "o ensure !"s sa'e use. Oracle
Corpora"!on and !"s a''!l!a"es d!scla!m an l!ab!l!" 'or an damages caused b use o' "h!s
so'"+are or hard+are !n dangerous appl!ca"!ons.
Third!arty Content" !roducts" and #er$ices Disclaimer
Th!s so'"+are or hard+are and documen"a"!on ma pro&!de access "o or !n'orma"!on on
con"en", produc"s, and ser&!ces 'rom "h!rd par"!es. Oracle Corpora"!on and !"s a''!l!a"es are no"
respons!ble 'or and e/pressl d!scla!m all +arran"!es o' an (!nd +!"h respec" "o "h!rd?par"
con"en", produc"s, and ser&!ces. Oracle Corpora"!on and !"s a''!l!a"es +!ll no" be respons!ble 'or
an loss, cos"s, or damages !ncurred due "o our access "o or use o' "h!rd?par" con"en",
produc"s, or ser&!ces.
CONTENTS
Chapter 1 Introduction..............................................................................................................1
PHP and Oracle.................................................................................................................................. 1
Introduction to Oracle Database......................................................................................................... 1
Introduction to PHP............................................................................................................................ 1
Chapter 2 Getting Started With PHP.......................................................................................5
Creating and Editing PHP Scripts....................................................................................................... 5
PHP Syntax Overview........................................................................................................................ 5
unning PHP Scripts.......................................................................................................................... !
unning Scripts "ia a #rowser........................................................................................................ !
unning Scripts $sing t%e PHP Develop&ent 'eb Server.............................................................!
unning Scripts 'it% Co&&and()ine PHP.....................................................................................*
Debugging PHP Scripts...................................................................................................................... *
Chapter 3 PHP Oracle Eten!ion!.........................................................................................11
PHP Oracle Extensions.................................................................................................................... 11
PHP OCI! Extension........................................................................................................................ 11
+etting t%e OCI! Extension........................................................................................................... 1,
OCI! and Oracle Database Installation Options............................................................................1-
PHP OCI! History......................................................................................................................... 1.
PHP PDO Extension......................................................................................................................... 15
+etting t%e PDO Extension........................................................................................................... 15
PHP /ra&ewor0s............................................................................................................................. 15
PHP Database 1bstraction )ibraries................................................................................................. 15
1DOdb.......................................................................................................................................... 12
PE1 D#...................................................................................................................................... 12
PE1 3D#,................................................................................................................................. 12
4%e PHP elease Cycle................................................................................................................... 15
Chapter " In!talling Oracle #ata$a!e 11g Epre!! Edition................................................1%
Oracle Database Editions................................................................................................................. 1*
Oracle Database 11g 6E.................................................................................................................. 1*
Installing Oracle Database 11g 6E on )inux.....................................................................................,7
Installing Oracle Database 11g 6E on 'indows...............................................................................,1
3anaging t%e Oracle Database 11g 6E............................................................................................ ,-
Setting t%e Oracle Database 11g 6E Environ&ent "ariables on )inux..........................................,-
Starting and Stopping t%e )istener and Database.........................................................................,.
#asic 3onitoring o8 Oracle Database 11g 6E................................................................................,5
Oracle 4er&inology........................................................................................................................... ,5
Chapter 5 S&' With Oracle #ata$a!e...................................................................................2%
Oracle S9):Plus.............................................................................................................................. ,*
i
Setting t%e Environ&ent 8or S9):Plus........................................................................................... ,*
Starting S9):Plus......................................................................................................................... ,*
$sing S9):Plus to $nloc0 t%e H Sc%e&a 8or De&onstration 4able 1ccess................................-7
Creating Database $sers in S9):Plus.......................................................................................... -1
Executing S9) and P);S9) State&ents in S9):Plus...................................................................-1
Controlling 9uery Output in S9):Plus........................................................................................... -,
unning S9) Scripts in S9):Plus................................................................................................. -,
4able 3etadata in S9):Plus.......................................................................................................... --
Starting and Stopping t%e Database 'it% S9):Plus.....................................................................--
Oracle 1pplication Express............................................................................................................... -.
Creating an 1pplication Express 'or0space.................................................................................-5
)ogging In 4o Oracle 1pplication Express..................................................................................... -5
Creating Database Ob<ects in 1pplication Express........................................................................-!
'or0ing 'it% S9) in 1pplication Express..................................................................................... .1
Creating a P);S9) Procedure in 1pplication Express....................................................................-
Oracle S9) Developer...................................................................................................................... .2
Creating a Database Connection in S9) Developer.......................................................................2
Editing Data in S9) Developer...................................................................................................... .5
Creating a 4able in S9) Developer............................................................................................... .!
Executing a S9) 9uery in S9) Developer.....................................................................................*
Editing= Co&piling and unning P);S9) in S9) Developer..........................................................51
unning eports in S9) Developer.............................................................................................. 5,
Creating eports in S9) Developer.............................................................................................. 5-
Chapter ( Net)ean! I#E *or PHP...........................................................................................5+
>et#eans Installation ....................................................................................................................... 55
>et#eans Editor /eatures ............................................................................................................... 55
Develop&ent Processes in >et#eans ............................................................................................. 5*
OCI! Support in >et#eans .............................................................................................................. 5*
Oracle Database Support in >et#eans ............................................................................................ 5*
+etting Help 8or >et#eans ............................................................................................................... 27
Chapter + In!talling ,pache HTTP Ser-er............................................................................(3
1pac%e H44P Server Pac0ages on Oracle )inux.............................................................................2-
#uilding 1pac%e H44P Server on )inux............................................................................................ 2-
Con8iguring 1pac%e H44P Server on )inux...................................................................................... 2.
Setting t%e 1pac%e Server >a&e.................................................................................................. 2.
Setting up an 1pac%e $ser Directory on )inux..............................................................................2.
Environ&ent "ariables 8or PHP in 1pac%e on Oracle )inux...........................................................25
Per&issions 8or PHP OCI! in 1pac%e on Oracle )inux..................................................................22
Installing 1pac%e H44P Server on 'indows.................................................................................... 22
Starting and Stopping 1pac%e H44P Server on 'indows.............................................................25
4esting 1pac%e H44P Server........................................................................................................... 25
ii
Chapter . In!talling and Con*iguring PHP...........................................................................(%
Installing PHP on )inux..................................................................................................................... 2*
Installing )inux PHP Pac0ages...................................................................................................... 2*
Installing ?end Server Pac0ages on )inux.................................................................................... 57
Co&piling PHP as an 1pac%e 3odule on )inux............................................................................51
Installing Oracle Instant Client on )inux 8or t%e OCI! Extension....................................................5-
Con8iguration Options 8or Co&piling OCI! 'it% PHP on )inux......................................................5.
Installing OCI! on )inux as a S%ared Extension $sing PEC).......................................................55
3anually Installing OCI! on )inux as a S%ared Extension............................................................52
Setting t%e Oracle Environ&ent 8or PHP on )inux.........................................................................55
Signal Handling and De8unct Processes on )inux.........................................................................!7
$sing PHP(/P3 'it% 1pac%e on )inux......................................................................................... !1
Installing PHP 'it% OCI! on 'indows............................................................................................. !.
Oracle )ibraries on 'indows......................................................................................................... !.
Installing PHP on 'indows........................................................................................................... !5
Installing OCI! 'it% Oracle H44P Server......................................................................................... !2
Installing OCI! 'it% Oracle H44P Server 11g on )inux................................................................!5
Installing OCI! 'it% Oracle H44P Server 17g on )inux................................................................!*
Installing t%e PDO Extension............................................................................................................ *1
Installing PDO@OCI on )inux......................................................................................................... *1
Installing PDO@OCI on 'indows................................................................................................... *,
C%ec0ing OCI! and PDO@OCI Installation....................................................................................... *,
Chapter % In!talling PHP and ,pache on Oracle Solari!....................................................%5
Installing 1pac%e on Oracle Solaris 11.1........................................................................................... *5
Installing PHP on Oracle Solaris 11.1............................................................................................... *2
C%anging t%e "ersion o8 PHP used by 1pac%e.................................................................................*!
Installing Oracle Instant Client on Oracle Solaris 11.1......................................................................**
Installing OCI! on Oracle Solaris 11.1.............................................................................................. **
Chapter 1/ Connecting to Oracle 0!ing OCI....................................................................1/1
Oracle Connection Exa&ple........................................................................................................... 171
Oracle Connection 4ypes............................................................................................................... 17,
Standard Connections................................................................................................................. 17-
$niAue Connections.................................................................................................................... 17-
Persistent Connections............................................................................................................... 17-
Oracle Database >a&e Connection Identi8iers...............................................................................17.
Easy Connect String.................................................................................................................... 17.
Database Connect Descriptor String........................................................................................... 175
Database Connect >a&e............................................................................................................ 172
Co&&only Seen Connection and Environ&ent Errors....................................................................175
Closing Oracle Connections............................................................................................................ 111
Closing Connections and "ariable Scope....................................................................................111
iii
4ransactions and Connections.................................................................................................... 11,
Session State 'it% Persistent Connections.................................................................................11-
Optional Connection Para&eters.................................................................................................... 11-
Connection C%aracter Set........................................................................................................... 11-
Connection Session 3ode........................................................................................................... 11.
Password Handling in PHP 1pplications......................................................................................... 112
External 1ut%entication 'it% PHP OCI!...................................................................................... 112
4uning Connections to #uild Scalable Syste&s..............................................................................11!
$se t%e #est Connection /unction.............................................................................................. 11!
$se Connection Pooling.............................................................................................................. 11*
3ini&iBe t%e nu&ber o8 database user credentials used.............................................................11*
Connect 'it% a C%aracter Set..................................................................................................... 11*
4une t%e 1$DSESC SeAuence +enerator...................................................................................1,7
Do >ot Set t%e Date or >u&eric /or&at $nnecessarily..............................................................1,7
3anage Persistent Connections.................................................................................................. 1,1
C%anging t%e Database Password................................................................................................. 1,-
C%anging Passwords on De&and............................................................................................... 1,-
C%anging Expired Passwords..................................................................................................... 1,.
1ut%oriBation and 1ut%entication 'it% Client Identi8iers..................................................................1,2
Setting Client Identi8iers............................................................................................................... 1,2
1 Sa&ple 1pplication $sing Client Identi8iers..............................................................................1,5
$sing a Client Identi8ier in PHP 8or 1uditing.................................................................................1--
$sing a Client Identi8ier in PHP 'it% a "PD 8or estricting Data 1ccess....................................1-5
$sing a Client Identi8ier in PHP 8or 3onitoring and 4racing.........................................................1-!
Client Identi8ier Su&&ary............................................................................................................ 1.,
Oracle >etwor0 Services and PHP................................................................................................. 1.,
Connection ate )i&iting............................................................................................................ 1.,
Setting Connection 4i&eouts....................................................................................................... 1.-
Con8iguring 1ut%entication 3et%ods............................................................................................ 1.-
Detecting Dead PHP 1pac%e Sessions....................................................................................... 1..
Detecting Dead Database Servers.............................................................................................. 1..
Ot%er Oracle >et Opti&iBations................................................................................................... 1..
4racing Oracle >et...................................................................................................................... 1..
Chapter 11 Eecuting S&' State1ent! With OCI.............................................................1"+
S9) State&ent Execution Steps.................................................................................................... 1.5
9uery Exa&ple............................................................................................................................ 1.5
9uoting S9) State&ent 4ext....................................................................................................... 1.!
Oracle Data 4ypes....................................................................................................................... 1.*
/etc% /unctions.............................................................................................................................. 157
/etc%ing to a >u&eric 1rray........................................................................................................ 157
/etc%ing to an 1ssociative 1rray................................................................................................. 151
i$
/etc%ing Case Sensitive Colu&n >a&es to an 1ssociative 1rray...............................................15,
Duplicate Colu&n >a&es and 1ssociative 1rrays.......................................................................15,
/etc%ing to an Ob<ect.................................................................................................................. 15,
De8ining Output "ariables............................................................................................................ 15-
/etc%ing >ested Cursors............................................................................................................. 15.
/etc%ing and 'or0ing 'it% >u&bers.......................................................................................... 155
/etc%ing and 'or0ing 'it% Dates............................................................................................... 152
Insert= $pdate= Delete= Create and Drop in PHP OCI!...................................................................155
4ransactions in PHP OCI!.............................................................................................................. 155
1utono&ous 4ransactions........................................................................................................... 15*
4%e 4ransactional #e%avior o8 3ultiple Connections...................................................................127
PHP Error Handling........................................................................................................................ 121
Handling PHP OCI! Errors.......................................................................................................... 121
$sing #ind "ariables in Prepared State&ents................................................................................12.
#inding in a D8orE )oop................................................................................................................. 125
#inding 'it% )IFE and E+E6P@)IFE Clauses.........................................................................12!
#inding 3ultiple "alues in an I> Clause...................................................................................... 12*
$sing #ind "ariables to /etc% Data............................................................................................. 151
#inding in an ODE #G Clause................................................................................................ 15,
$sing O'ID #ind "ariables...................................................................................................... 15,
I&proving Per8or&ance by Pre8etc%ing and Cac%ing......................................................................15-
4uning t%e Pre8etc% SiBe............................................................................................................. 15-
4uning t%e State&ent Cac%e SiBe............................................................................................... 155
$sing t%e Server and Client 9uery esult Cac%es......................................................................152
3onitoring OCI! S9) State&ents.................................................................................................. 15!
OCI! Driver Identi8ication............................................................................................................ 15*
Setting 1pplication In8or&ation in PHP OCI!...............................................................................15*
)I3I4= 1uto(Incre&ent= )ast Insert ID and 3ultiple Inserts..............................................................1!7
)i&iting ows and Creating Paged Datasets..............................................................................1!1
1uto(Incre&ent Colu&ns............................................................................................................. 1!-
+etting t%e )ast Insert ID............................................................................................................. 1!.
Inserting 3ultiple "alues.............................................................................................................. 1!5
Exploring Oracle............................................................................................................................. 1!5
Case Insensitive Data 3atc%ing in 9ueries.................................................................................1!5
1nalytic /unctions in S9)........................................................................................................... 1!2
External 4ables............................................................................................................................ 1!2
Chapter 12 0!ing P'2S&' With OCI...................................................................................1.+
P);S9) Overview........................................................................................................................... 1!5
#loc0s= Procedures= Pac0ages and 4riggers..................................................................................1!!
1nony&ous #loc0s...................................................................................................................... 1!!
Stored Procedures and /unctions............................................................................................... 1!!
$
Pac0ages.................................................................................................................................... 1!*
4riggers....................................................................................................................................... 1*7
Creating P);S9) Stored Procedures in PHP..................................................................................1*7
End o8 )ine 4er&inators in P);S9) 'it% 'indows PHP..............................................................1*1
Calling P);S9) Code...................................................................................................................... 1*1
Calling P);S9) Procedures in PHP............................................................................................. 1*1
Calling P);S9) /unctions in PHP............................................................................................... 1*,
#inding $nsupported P);S9) 4ypes........................................................................................... 1*-
1rray #inding and P);S9) #ul0 Processing...................................................................................1*.
P);S9) Success 'it% In8or&ation 'arnings..................................................................................1*2
$sing E/ C$SOS 8or esult Sets........................................................................................... 1*5
Closing Cursors........................................................................................................................... ,77
Pre8etc%ing /ro& E/ C$SOS and >ested Cursors 8or Per8or&ance...................................,71
Converting 8ro& E/ C$SO to PIPE)I>ED esults..............................................................,7,
Oracle Collections in PHP.............................................................................................................. ,7-
$sing P);S9) and Oracle Ob<ect 4ypes in PHP.............................................................................,75
$sing a PIPE)I>ED /unction...................................................................................................... ,72
$sing a E/ C$SO................................................................................................................ ,75
$sing an 1rray #ind..................................................................................................................... ,7!
$sing OCI! Collection /unctions................................................................................................. ,7*
+etting Output 'it% D#3S@O$4P$4............................................................................................ ,17
P);S9) #ac0traces in a P);S9) Exception Handler......................................................................,1-
P);S9) /unction esult Cac%e...................................................................................................... ,1.
$sing Oracle )ocator 8or Spatial 3apping...................................................................................... ,1.
Inserting )ocator Data................................................................................................................. ,15
9ueries eturning Scalar "alues................................................................................................. ,15
Selecting "ertices $sing SDO@$4I).+E4"E4ICES.................................................................,12
$sing a Custo& /unction............................................................................................................ ,15
Sc%eduling #ac0ground or )ong unning Operations....................................................................,1!
Oracle Strea&s 1dvanced 9ueuing................................................................................................ ,,1
eusing Procedures 'ritten 8or 3OD@P)S9)...............................................................................,,.
Easy P);S9) $pgrades 'it% Edition #ased ede8inition...............................................................,,2
Database 4ransactions 1cross Stateless 'eb eAuests................................................................,-7
Chapter 13 0!ing 'arge O$3ect! in OCI.............................................................................233
'or0ing 'it% )O#s........................................................................................................................ ,--
Inserting and $pdating )O#s...................................................................................................... ,--
/etc%ing )O#s............................................................................................................................. ,-.
4e&porary )O#s......................................................................................................................... ,-5
$ploading and Displaying an I&age............................................................................................ ,-2
)O#s and P);S9) procedures.................................................................................................... ,-5
Ot%er )O# 3et%ods.................................................................................................................... ,-*
$i
'or0ing 'it% #/I)Es...................................................................................................................... ,.7
Chapter 1" 0!ing 45' With Oracle and PHP.....................................................................2"5
/etc%ing elational ows as 63).................................................................................................. ,.5
/etc%ing ows as /ully /or&ed 63)............................................................................................. ,.2
$sing t%e Si&ple63) Extension in PHP......................................................................................... ,.5
/etc%ing 63)4ype Colu&ns........................................................................................................... ,.!
Inserting Into 63)4ype Colu&ns.................................................................................................... ,57
/etc%ing an 63)4ype 8ro& a P);S9) /unction..............................................................................,5,
69uery 63) 9uery )anguage........................................................................................................ ,5,
1ccessing Data Over H44P 'it% 63) D#......................................................................................,5.
Chapter 15 PHP Connection Pooling and High ,-aila$ilit6.............................................25+
Database esident Connection Pooling......................................................................................... ,55
How DCP 'or0s....................................................................................................................... ,5!
PHP OCI! Connections and DCP............................................................................................. ,27
'%en to use DCP..................................................................................................................... ,2,
S%aring t%e Server Pool.............................................................................................................. ,2-
$sing DCP in PHP....................................................................................................................... ,2.
Con8iguring and Enabling t%e Pool.............................................................................................. ,25
Con8iguring PHP 8or DCP......................................................................................................... ,25
1pplication Deploy&ent 8or DCP............................................................................................... ,2!
3onitoring DCP............................................................................................................................ ,51
D#1@CPOO)@I>/O "iew........................................................................................................... ,51
"CPOCESS and "CSESSIO> "iews........................................................................................ ,5,
"CCPOO)@S414S "iew.............................................................................................................. ,5,
"CCPOO)@CC@S414S "iew....................................................................................................... ,5-
Hig% 1vailability 'it% /1> and 1C............................................................................................... ,52
Con8iguring /1> Events in t%e Database....................................................................................,52
Con8iguring PHP 8or /1>............................................................................................................. ,52
1pplication Deploy&ent 8or /1>.................................................................................................. ,52
1C Connection )oad #alancing 'it% PHP................................................................................,5!
Chapter 1( PHP and Ti1e!Ten In75e1or6 #ata$a!e........................................................2+%
Installing 4i&es4en on )inux........................................................................................................... ,5*
3anaging 4i&es4en....................................................................................................................... ,!7
Creating t%e 4i&es4en Sa&ple Database....................................................................................... ,!1
Installing 1pac%e and PHP 8or 4i&es4en........................................................................................ ,!,
C%ec0ing t%e Installation................................................................................................................. ,!,
Connecting to 4i&es4en 'it% PHP OCI!........................................................................................ ,!-
Con8iguring 4i&es4en..................................................................................................................... ,!-
Chapter 1+ PHP and Oracle Tuedo....................................................................................2.5
Installing 4uxedo 11.1 and S1)4 8or PHP 'eb 1pplications...........................................................,!5
Installing Oracle 4uxedo.............................................................................................................. ,!2
$ii
Installing Oracle S1)4................................................................................................................. ,*7
Installing PHP 8or Oracle 4uxedo.................................................................................................... ,*-
Installing Oracle 4uxedo into 1pac%e.............................................................................................. ,*-
Con8iguring Oracle 4uxedo 8or PHP................................................................................................ ,*.
Starting and 3anaging 4uxedo....................................................................................................... ,*2
"eri8ying PHP and 4uxedo.............................................................................................................. ,*!
Chapter 1. Glo$ali8ation......................................................................................................3/1
Establis%ing t%e Environ&ent #etween Oracle and PHP................................................................-71
Setting t%e )anguage= 4erritory and C%aracter Set 'it% >)S@)1>+..........................................-71
Setting t%e Oracle >u&ber /or&at 'it% >)S@>$3EIC@CH11C4ES.................................-7-
Setting t%e Oracle Date /or&at 'it% >)S@D14E@/O314.......................................................-75
Setting t%e De8ault Session 4i&e ?one 'it% O1@SD4?...........................................................-75
3anipulating Strings....................................................................................................................... -75
Deter&ining t%e )ocale o8 t%e $ser................................................................................................ -75
Developing )ocale 1wareness..................................................................................................... -7!
Encoding H43) Pages................................................................................................................... -7*
Speci8ying t%e Page Encoding 8or H43) Pages..........................................................................-7*
Speci8ying t%e Encoding in t%e H44P Header.............................................................................-7*
Speci8ying t%e Encoding in t%e H43) Page Header....................................................................-7*
Speci8ying t%e Page Encoding in PHP......................................................................................... -7*
OrganiBing t%e Content o8 H43) Pages 8or 4ranslation..................................................................-17
Strings in PHP............................................................................................................................. -17
Static /iles................................................................................................................................... -17
Data 8ro& t%e Database.............................................................................................................. -17
Presenting Data $sing Conventions Expected by t%e $ser............................................................-17
Oracle )inguistic Sorts................................................................................................................. -11
Oracle Error 3essages............................................................................................................... -1,
Chapter 1% Te!ting PHP and the OCI. Eten!ion..............................................................313
unning OCI! 4ests........................................................................................................................ -1-
unning a Single 4est.................................................................................................................. -15
4ests t%at /ail................................................................................................................................. -15
Creating OCI! 4ests ...................................................................................................................... -15
OCI! 4est Helper Scripts............................................................................................................. -15
Con8iguring t%e Database /or 4esting............................................................................................ -15
4esting PHP 1pplications................................................................................................................ -1*
,ppendi , Tracing OCI. Internal!.....................................................................................321
Enabling OCI! Debugging output................................................................................................... -,1
,ppendi ) OCI. php.ini Para1eter!.................................................................................323
Enabling PHP OCI! in p%p.ini......................................................................................................... -,-
PHP OCI! p%p.ini Para&eters........................................................................................................ -,.
,ppendi C OCI. 9unction Na1e! in PHP " and PHP 5...................................................32+
$iii
,ppendi # The O$!olete Oracle Eten!ion......................................................................331
Oracle and OCI! Co&parison........................................................................................................ --1
,ppendi E :e!ource!.........................................................................................................335
+eneral In8or&ation and /oru&s.................................................................................................... --5
Oracle Docu&entation and '%itepapers........................................................................................ --5
Selected PHP and Oracle #oo0s.................................................................................................... --2
So8tware and Source Code............................................................................................................. --5
PHP )in0s....................................................................................................................................... --!
Glo!!ar6.................................................................................................................................33%
i%
CH,PTE: 1
INT:O#0CTION
Th!s boo( !s des!gned "o br!dge "he gap be"+een "he man PHP scr!p"!ng language and "he
man Oracle Da"abase boo(s a&a!lable. :" con"a!ns un!>ue ma"er!al abou" PHPAs OC:$
e/"ens!on 'or Oracle Da"abase, and abou" o"her componen"s !n "he PHP?Oracle ecoss"em. :"
sho+s PHP de&elopers ho+ "o use PHP and Oracle "oge"her, e''!c!en"l and eas!l.
The #nderground PHP and Oracle !anual !s no" a comple"e PHP sn"a/ or Oracle 4B.
gu!de. :" also does no" descr!be o&erall appl!ca"!on arch!"ec"ure. 2or "hese, Oracle
documen"a"!on !s 'reel a&a!lable onl!ne, as are e/"ens!&e PHP documen"a"!on and appl!ca"!on
de&elopmen" resources. 2or ne+comers +e sugges" read!ng "he Oracle Database Express
Edition 2 Day $ PHP Developer%s Guide +h!ch +al(s "hrough bu!ld!ng a PHP appl!ca"!on.
4!nce "he '!rs" release o' "he #nderground PHP and Oracle !anual, man commerc!al
boo(s on PHP and Oracle ha&e been publ!shed. The are +or"h+h!le add!"!ons "o our l!brar.
;ach has a d!''eren" &!e+po!n" and sho+s some"h!ng ne+ abou" "he "echnolog!es.
PHP and Oracle
% number o' Oracle produc"s con"r!bu"e "o "he r!ch ecoss"em 'or PHP appl!ca"!ons. These
!nclude "he 7e"-eans :D;, Oracle Da"abase, Oracle T!mesTen :n?Memor Da"abase, Oracle
Tu/edo, Oracle %ppl!ca"!on 4er&er, and &ar!ous 4B. de&elopmen" "ools. There are man users
o' PHP and Oracle all around "he +orld us!ng "hese "echnolog!es.
Introduction to Oracle #ata$a!e
The ma!n Oracle produc" d!scussed !n "h!s boo( !s Oracle Da"abase. :" !s +ell (no+n 'or !"s
scalab!l!", rel!ab!l!" and 'ea"ures. :" !s "he lead!ng rela"!onal da"abase and !s a&a!lable on
man pla"'orms. The !ns"alla"!on d!scuss!on h!ghl!gh"s "he 'ree Oracle Da"abase 11g ;/press
;d!"!on C(no+n as DOracle =;EF. 4!nce Oracle =; !s a subse" o' "he 'ull Oracle Da"abase
bundle, "he PHP appl!ca"!ons ou +r!"e 'or Oracle =; can be run, +!"hou" change, aga!ns" all
o"her ed!"!ons o' "he Oracle 11g da"abase. PHP also suppor"s some o' "he ad&anced
'unc"!onal!" o' Oracle Da"abase 11gR2 ;n"erpr!se ;d!"!onG "h!s !s co&ered here "oo.
Mos" o' "he core !n'orma"!on !n "he boo( !s rele&an" "o pre&!ous &ers!ons o' Oracle
Da"abase.
Introduction to PHP
PHP !s a hugel popular, !n"erpre"ed scr!p"!ng language commonl used 'or +eb appl!ca"!ons.
:" !s open source, 'ree, and has a -4D?s"le l!cense ma(!ng !" corpora"!on?'r!endl. PHP !s
per'ec" 'or rap!dl de&elop!ng appl!ca"!ons bo"h b!g and small. :" po+ers m!ll!ons o' +eb s!"es
on "he :n"erne" and has a huge user commun!" beh!nd !". :" runs on man pla"'orms.
The language !s dnam!call "ped and eas "o use. PHP H !n"roduced s"rong ob8ec"
or!en"a"ed capab!l!"!es. PHP comes +!"h man e/"ens!ons o''er!ng all (!nds o' 'unc"!onal!"
'rom ss"em opera"!ons "o numer!cal process!ng. PHP !ncludes "he OC:$ e/"ens!on +h!ch,
+hen l!n(ed +!"h Oracle cl!en" l!brar!es, enables access "o Oracle Da"abase.
&
'ntroduction
% PHP command l!ne !n"er'ace CC.:F can be used "o e/ecu"e PHP scr!p"s 'rom an opera"!ng
ss"em shell +!ndo+, or a s!mple !n?bu!l" de&elopmen" +eb ser&er can be used "o ser&e scr!p"
ou"pu" "o a bro+ser. Th!s !s common 'or >u!c( de&elopmen" "es"!ng.
2or produc"!on appl!ca"!ons, PHP !s "p!call !ns"alled as an %pache module, or run b a
+eb ser&er us!ng 2as"C3:.
Cons!der "he scr!p" hello"php)
Script &' hello"php
<?php
echo "<phello</p"!
"uer#$cities%&!
'unction "uer#$cities%& (
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "select cit# 'rom locations"&!
oci$e.ecute%)s&!
echo "<ta/le /order*0102n"!
while %%)row * oci$'etch$arra#%)s+ 345$67734&& 8* 'alse& (
echo " <tr2n"!
echo " <td".htmlentities%)row9045:;0<&."</td2n"!
echo " </tr2n"!
=
echo "</ta/le2n"!
=
?
0hen ou en"er "he UR. o' "he scr!p" Csee s"ep 1 !n 2!gure 1F !n our bro+ser, "he +eb ser&er
!n&o(es PHP "o processes "he '!le. The PHP code !s loaded and e/ecu"ed C2F. Calls "o "he
da"abase CIF re"urn da"a +h!ch !s 'orma""ed and sen" as ou"pu". 2!nall, "h!s HTM. !s re"urned
"o "he bro+ser CJF, +h!ch 'orma"s and d!splas "he page.
(
'ntroduction to !H!
PHP !s an open source pro8ec". :" !s ma!n"a!ned b a +!de?spread commun!" us!ng an open
source de&elopmen" me"hodolog "ha" has sel'?!mposed goals and deadl!nes. Tas(s are
comple"ed b de&elopers +ho con"r!bu"e "he!r spare "!me and e''or" on sub?pro8ec"s "ha"
!n"eres" "hem.
%n !ssues +!"h PHP !"sel' or +!"h us!ng "he PHP OC:$ e/"ens!on "o access Oracle Da"abase
should be repor"ed "hrough commun!" channels such as "he OT7 PHP 'orum and "he PHP bug
da"abase.
)
(igure &' )he *our stages o* processing a PHP script"
'ntroduction
*
CH,PTE: 2
GETTING ST,:TE# WITH PHP
Th!s chap"er g!&es a &er br!e' o&er&!e+ o' "he PHP language. -as!c PHP sn"a/ !s s!mple "o
learn. :" has 'am!l!ar loop, "es" and ass!gnmen" cons"ruc"s.
Creating and Editing PHP Script!
There are a number o' spec!al!1ed PHP ed!"ors a&a!lable, !nclud!ng OracleKs 7e"-eans :D;
+h!ch !s &er h!ghl regarded 'or PHP de&elopmen". 4ome de&elopers s"!ll pre'er bas!c "e/"
ed!"ors +!"h modes "ha" h!ghl!gh" code sn"a/ and a!d de&elopmen". :n general "h!s manual
does no" assume an par"!cular ed!"or or debugger !s be!ng used.
PHP scr!p"s o'"en ha&e "he '!le e/"ens!on "php, bu" some"!mes "pht+l !s also used. 0eb
ser&ers can be con'!gured "o recogn!1e an e/"ens!onCsF "ha" ou choose and send "hose '!les
"o PHP 'or process!ng.
PHP S6nta O-er-ie;
PHP scr!p"s are enclosed !n <?php and ? "ags. .!nes are "erm!na"ed +!"h a sem!?colon)
<?php
echo 0>ello+ ?orld80!
?
-loc(s o' PHP code and HTM. code ma be !n"erlea&ed. The PHP code can also e/pl!c!"l pr!n"
HTM. "ags)
<?php
echo 0<h@0!
echo 0Aull Besults0!
echo 0</h@0!
)output * "no results aCaila/le"!
?
<ta/le /order*"1"
<tr
<td
<?php echo )output ?
</td
</tr
</ta/le
The ou"pu" +hen runn!ng "h!s scr!p" !s)
<h@Aull Besults</h@<ta/le /order*"1"
<tr
<td
no results aCaila/le </td
</tr
</ta/le
+
,etting #tarted With !H!
% bro+ser +ould d!spla !" as)
PHP s"r!ngs can be enclosed !n s!ngle or double >uo"es)
06 string constant0
"another constant"
,ar!able names are pre'!/ed +!"h a dollar s!gn. Th!ngs "ha" loo( l!(e &ar!ables !ns!de a double?
>uo"ed s"r!ng +!ll be e/panded)
"6 Calue appears here: )C1"
4"r!ngs and &ar!ables can also be conca"ena"ed us!ng a per!od.
0-mplo#ee 0 . )ename . 0 is in department 0 . )dept
,ar!ables do no" need "pes declared)
)count * 1!
)ename * 06rnie0!
%rras can ha&e numer!c or assoc!a"!&e !nde/es)
)a191< * @.1D15!
)a290E50< * @.1D15!
4"r!ngs and &ar!ables can be d!splaed +!"h an echo or print s"a"emen". 2orma""ed ou"pu"
+!"h print'%& !s also poss!ble.
echo 0>ello+ ?orld80!
echo )C+ ).!
print 0>ello+ ?orld80!
print'%":here is Fd Fs"+ )C1+ )C2&!
Code 'lo+ can be con"rolled +!"h "es"s and loops. PHP also has a s,itch s"a"emen". The i',
elsei' and else s"a"emen"s loo( l!(e)
i' %)sal 900000& (
echo 07alar# is wa# too /ig0!
= elsei' %)sal 500000& (
echo 07alar# is huge0!
= else (
echo 07alar# might /e 3G0!
=
Th!s also sho+s ho+ bloc(s o' code are enclosed !n braces.
% "rad!"!onal !ncremen"!ng loop !s)
-
(igure 2' PHP script output"
!H! #ynta% .$er$ie/
'or %)i * 0! )i < 10! HH)i& (
echo )i . "</r2n"!
=
Th!s pr!n"s "he numbers 0 "o L, each on a ne+ l!ne. The &alue o' )i !s !ncremen"ed !n each
!"era"!on. The loop s"ops +hen "he "es" cond!"!on e&alua"es "o "rue. Mou can also loop +!"h
while or do while cons"ruc"s.
The 'oreach command !s use'ul "o !"era"e o&er arras)
)a@ * arra#%06a0+ 0I/0+ 04c0&!
'oreach %)a@ as )C& (
echo )C!
=
Th!s se"s )C "o each elemen" o' "he arra !n "urn.
2unc"!ons ma be de'!ned)
'unction m#'unc%)p1+ )p2& (
echo )p1+ )p2!
return )p1 H )p2!
=
The pre&!ous 'unc"!on could be called us!ng)
)C@ * m#'unc%1+ @&!
2unc"!ons ma ha&e &ar!able numbers o' argumen"s. 2unc"!on calls ma appear earl!er "han
"he 'unc"!on de'!n!"!on. Procedures use "he same *unction (e+ord bu" do no" ha&e a return
s"a"emen".
Classes loo( l!(e)
class m#class (
priCate )state * 1!
pu/lic 'unction set%)C&
(
)this-state * )C!
=
pu/lic 'unction get%&
(
return )this-state!
=
=
)C * new m#class%&!
echo )C-get%&!
)C-set%@&!
4ub?'!les can be !ncluded !n PHP scr!p"s +!"h an include%& or re"uire%& s"a"emen".
include%0'oo.php0&!
re"uire%0/ar.php0&!
% re"uire%& +!ll genera"e a 'a"al error !' "he scr!p" !s no" 'ound. The include$once%& and
re"uire$once%& s"a"emen"s pre&en" mul"!ple !nclus!ons o' a '!le.
Commen"s are e!"her s!ngle l!ne)
0
,etting #tarted With !H!
// a short comment
or mul"!?l!ne)
/J
6
longer
comment
J/
:unning PHP Script!
PHP scr!p"s can be loaded !n a bro+ser, or e/ecu"ed a" a command promp" !n a "erm!nal
+!ndo+. -ecause bro+sers !n"erpre" HTM. "ags and "he also compress +h!"e space !nclud!ng
ne+?l!nes, "h!s means scr!p" ou"pu" can d!''er be"+een command?l!ne and bro+ser !n&oca"!on
o' "he same scr!p". 2or a s!m!lar reason pure?PHP scr!p"s o'"en om!" "he clos!ng ? "ag because
an acc!den"al "ra!l!ng +h!"e space a'"er !" +!ll be sen" "o "he bro+ser, poss!bl a''ec"!ng s"le
laou"s. PHP doesnA" re>u!re "he clos!ng "ag.
Man aspec"s o' PHP are con"rolled b se""!ngs !n a php"ini con'!gura"!on '!le. The loca"!on
o' "he '!le !s ss"em spec!'!c. :"s loca"!on, "he l!s" o' e/"ens!ons loaded, and "he &alue o' all "he
!n!"!al!1a"!on se""!ngs can be 'ound us!ng "he phpin'o%& 'unc"!on)
<?php
phpin'o%&!
?
:n!"!al!1a"!on se""!ngs can be changed b ed!"!ng php"ini and res"ar"!ng "he +eb ser&er. 4ome
&alues can also be changed +!"h!n scr!p"s a" run "!me b us!ng "he ini$set%& 'unc"!on.
To connec" "o Oracle Da"abase, some Oracle en&!ronmen" &ar!ables need "o be se" be'ore
"he +eb ser&er s"ar"s. Th!s !s d!scussed !n "he !ns"alla"!on chap"ers o' "h!s boo(.
:unning Script! <ia a )ro;!er
PHP scr!p"s are commonl run b load!ng "hem !n a bro+ser)
http://localhost/m#phpin'o.php
Re>ues"!ng a scr!p" causes "he +eb ser&er "o !n&o(e PHP "o e/ecu"e "he re>ues"ed code '!le.
%ll o' "he scr!p" ou"pu" !s sen" "o "he bro+ser +h!ch 'orma"s and d!splas "he ou"pu". Tp!call
+eb ser&ers such as %pache are used. The +eb ser&er needs "o be con'!gured "o call PHP and
"o map "he user g!&en UR. "o !"s e>u!&alen" PHP '!le.
:unning Script! 0!ing the PHP #e-elop1ent We$ Ser-er
PHP H.J has a small !n?bu!l" command?l!ne !n"er'ace CDC.:EF +eb ser&er +h!ch can help "es"!ng
b be!ng !mmed!a"el access!ble. The +eb ser&er !s su!"able 'or de&elopmen" and "es"!ng onl.
:' our PHP code !s !n a '!le +yphpin*o"php, and "he PHP e/ecu"able !s !n our pa"h, s"ar"
"he PHP C.: +eb ser&er 'rom "he command l!ne +!"h)
) php -7 localhost:8888
The '!le can be loaded !n a bro+ser +!"h "he UR.)
http://localhosthost:8888/m#phpin'o.php
1
Running !H! #cripts
:unning Script! With Co11and7'ine PHP
:' our PHP code !s !n a '!le +yphpin*o"php, and "he PHP e/ecu"able !s !n our pa"h, run !" +!"h)
) php m#phpin'o.php
,ar!ous op"!ons "o "he PHP e/ecu"able con"rol !"s beha&!or. The -h op"!ons g!&es "he help "e/".
Common op"!ons +hen '!rs" us!ng PHP are --ini +h!ch d!splas "he loca"!on o' "he php"ini '!le,
and -i +h!ch d!splas "he &alue o' "he php"ini se""!ngs.
#e$ugging PHP Script!
:' ou are no" us!ng "he 7e"-eans :D; "hen debugg!ng +!ll be an old?'ash!oned ma""er o'
pr!n"!ng &ar!ables "o chec( code 'lo+.
The Car$dump%& 'unc"!on !s par"!cularl use'ul 'or debugg!ng because !" 'orma"s and pr!n"s
comple/ &ar!ables)
)a290E50< * @.1D15!
Car$dump%)a2&!
The ou"pu" !s)
arra#%1& (
9"E5"<*
'loat%@.1D15&
=
The 'orma""!ng !s apparen" +hen us!ng command?l!ne PHP. :n a bro+ser, "o pre&en" +h!"e
space and ne+ l!nes 'rom coalesc!ng, ou +!ll need "o do)
echo 0<pre0!
)a290E50< * @.1D15!
Car$dump%)a2&!
echo 0</pre0!
4ome e/amples !n "h!s manual use Car$dump%& "o s!mpl!' "he code be!ng demons"ra"ed or "o
sho+ "he "pe and con"en"s o' a &ar!able.
2
,etting #tarted With !H!
&3
CH,PTE: 3
PHP O:,C'E E4TENSIONS
PHP has se&eral e/"ens!ons "ha" le" appl!ca"!ons use Oracle Da"abase. There are also
da"abase l!brar!es +r!""en !n PHP +h!ch are popular. These abs"rac" "he use o' "he underl!ng
e/"ens!on.
Da"abase access !n each e/"ens!on and abs"rac"!on l!brar !s 'undamen"all s!m!lar. The
d!''erences are !n suppor" 'or ad&anced 'ea"ures and "he programm!ng me"hodolog
promo"ed. :' ou +an" "o ma(e 'ull use o' OracleAs 'ea"ures and +an" h!gh per'ormance "hen
use OC:$, +h!ch !s PHPKs ma!n Oracle e/"ens!on. :' ou reall need da"abase !ndependence,
"hen "he PHP Da"a Ob8ec" CPDOF e/"ens!on or "he %DOdb abs"rac"!on l!brar are a&a!lable.
Man appl!ca"!ons "ha" &alue con'orm!" o&er per'ormance +!ll bene'!" 'rom us!ng one o'
"he !ncreas!ngl popular PHP 'rame+or(s. These abs"rac" much o' "he da"a access "as( !n an
appl!ca"!on.
PHP Oracle Eten!ion!
The PHP e/"ens!ons "ha" connec" "o Oracle Da"abase are +r!""en !n C and l!n(ed !n"o "he PHP
b!nar. The e/"ens!ons are)
OC:$
PDONOC: dr!&er 'or PDO
Mou can also use "he OD-C e/"ens!onG "h!s !s no" co&ered !n "h!s boo(.
The "hree e/"ens!ons are !mplemen"ed !ndependen"l and ha&e no da"abase access code
!n common. The e/"ens!ons can be enabled separa"el or a" "he same "!me.
PHP OCI. Eten!ion
OC:$ !s "he recommended e/"ens!on 'or access!ng Oracle Da"abase and !s "he 'ocus o' "h!s
boo(. OC:$ has been !ncluded !n PHP s!nce PHP I. :" !s open source and ma!n"a!ned b "he PHP
commun!". Oracle !s a member o' "he commun!" loo(!ng a'"er OC:$.
There ha&e been ma8or and m!nor changes "o "he OC:$ e/"ens!on !n "he h!s"or o' PHP. :'
ou are us!ng PHP &ers!ons J "o H.2, !" !s highly recommended "o upgrade 'rom "he de'aul"
OC:$ e/"ens!on.
%n e/ample scr!p" "ha" '!nds c!" names 'rom "he .OC%T:O74 "able us!ng OC:$)
Script &' intro"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ 0select cit# 'rom locations0&!
oci$e.ecute%)s&!
while %%)res * oci$'etch$arra#%)s+ 345$67734&& 8* 'alse& (
echo htmlentities%)res9045:;0<& . "</r"!
=
?
&&
!H! .racle 4%tensions
0hen !n&o(ed !n a +eb bro+ser, !" connec"s as "he demons"ra"!on user HR o' "he Oracle D=;E
da"abase runn!ng on "he local mach!ne. The >uer !s e/ecu"ed and a +eb page o' resul"s !s
d!splaed !n "he bro+ser)
:n PHP H some e/"ens!on 'unc"!on names +ere s"andard!1ed. PHP J 'unc"!ons l!(e 345Kogin%&
became oci$connect%&, "he 'unc"!on 345Earse%& became oci$parse%& and so on. The old
names s"!ll e/!s" as al!ases, so PHP J scr!p"s do no" need "o be changed. % "able sho+!ng old
and ne+ names appears !n %ppend!/ C.
The name DOC:$E !s also "he name 'or OracleKs Call :n"er'ace %P: used b C programs such
as "he PHP OC:$ e/"ens!on !"sel'. %ll un>ual!'!ed re'erences "o OC:$ !n "h!s boo( re'er "o "he
PHP e/"ens!on.
Getting the OCI. Eten!ion
The OC:$ e/"ens!on can be ob"a!ned !n &ar!ous +as. The PHP source code release !s "he
canon!cal loca"!on 'or OC:$. :" !s also a&a!lable 'rom "he PHP ;/"ens!on Commun!" .!brar
CP;C.F s!"e, +h!ch con"a!ns PHP e/"ens!ons as !nd!&!dual source code do+nloads. P;C. !s
commonl used "o !ns"all OC:$ on "op o' .!nu/ d!s"r!bu"!on pac(ages o' PHP. Pre?bu!l" 0!ndo+s
PHP b!nar!es 'rom http://php.net !nclude "he OC:$ e/"ens!on D... The OC:$ e/"ens!on !s also
!ncluded !n "he 9end 4er&er produc", +h!ch !s a&a!lable 'or &ar!ous pla"'orms.
Table 1 sho+s +here OC:$ can be do+nloaded 'rom "he PHP pro8ec".
)able &' O-./ Availability *ro+ the PHP Pro0ect and Sa+ple Pac1age 2a+es"
)undle Containing OCI. 'ocation and Sa1ple :elea!e
PHP 4ource Code
http://www.php.net/downloads.php
php34"5"/"tar"b2
Comp!les and runs on man pla"'orms
&(
(igure 6' PHP output in a ,eb bro,ser"
!H! .C'1 4%tension
)undle Containing OCI. 'ocation and Sa1ple :elea!e
PHP 0!ndo+s -!nar!es
http://windows.php.net/download/
php34"5"/3Win6237-83x/9"ip
P;C. 4ource Code
http://pecl.php.net/package/oci8
oci/3&"5"8"tg
Used "o add or upgrade OC:$ 'or an e/!s"!ng PHP !ns"alla"!on
OCI. and Oracle #ata$a!e In!tallation Option!
To pro&!de Oracle da"abase access, "he PHP b!nar mus" be l!n(ed +!"h Oracle Cl!en" l!brar!es.
These l!brar!es pro&!de underl!ng connec"!&!" "o "he da"abase, +h!ch ma be local or remo"e
on our ne"+or(.
Oracle has cross?&ers!on compa"!b!l!". 2or e/ample, !' PHP OC:$ !s l!n(ed +!"h Oracle
Da"abase 10g cl!en" l!brar!es, "hen PHP appl!ca"!ons can connec" "o Oracle Da"abase $i , Li,
10g or 11g" :' OC:$ !s l!n(ed +!"h Oracle Da"abase 11g l!brar!es, "hen PHP can connec" "o
Oracle Da"abase LiR2 on+ards"
:' "he da"abase !s !ns"alled on "he same mach!ne as "he +eb ser&er and PHP, "hen PHP can
be l!n(ed +!"h Oracle l!brar!es !ncluded !n "he da"abase so'"+are. :' "he da"abase !s !ns"alled
on ano"her mach!ne, "hen l!n( PHP +!"h "he small, 'ree Oracle :ns"an" Cl!en" l!brar!es.
2ull OC:$ 'unc"!onal!" !s no" a&a!lable unless "he Oracle cl!en" l!brar!es and da"abase
ser&er are "he la"es" &ers!on.
Table 2 sho+s "he compa"!b!l!" o' "he Oracle cl!en" l!brar!es +!"h "he curren" OC:$
e/"ens!on and PHP. Older &ers!ons o' PHP ha&e d!''eren" compa"!b!l!" re>u!remen"s.
&)
(igure 5' PHP lin1s ,ith Oracle client libraries"
!H! .racle 4%tensions
)able 2' O-./ and Oracle -o+patibility !atrix"
So*t;are )undle PHP <er!ion OCI. <er!ion
Included
Oracle Client 'i$rarie! 0!a$le
;ith OCI.
PHP Release 4ource Code Curren" release !s
H.J
OC:$ 1.J LiR2, 10g, 11g
PHP Release 0!ndo+s
-!nar!es
Curren" release !s
H.J
OC:$ 1.J 10gR2, 11gR2
P;C. OC:$ 4ource Code -u!lds +!"h PHP
J.I.L on+ards
Curren"
release !s
OC:$ 1.J
LiR2, 10g, 11g
:' PHP J, H.0, H.1 or H.2 are be!ng used, ou should replace "he de'aul" OC:$ code +!"h "he
la"es" &ers!on 'rom P;C. "o ge" !mpro&ed s"ab!l!", beha&!or and per'ormance op"!m!1a"!ons.
Th!s !s par"!cularl !mpor"an" 'or PHP J and H.0 because "he!r &ers!ons o' OC:$ are no"or!ousl
uns"able.
PHP OCI. Hi!tor6
PHP OC:$ has undergone con"!nual de&elopmen" s!nce !" +as '!rs" !n"roduced !n PHP I. Table I
sho+s "he ma8or 'ea"ures !n recen" re&!s!ons o' OC:$, e&er s!nce "he pac(age +as g!&en an
!nd!&!dual &ers!on number.
)able 6' !a0or :evisions o* O-./"
OCI. <er!ion 5ain 9eature!
OC:$ 1.0 2!rs" P;C. release. -ased on PHP J.I OC:$ code.
OC:$ 1.1 -e"a releases "ha" became OC:$ 1.2.
OC:$ 1.2 % ma8or re'ac"or!ng o' "he e/"ens!on 'or PHP H.1. :" grea"l !mpro&ed
s"ab!l!", added con"rol o&er pers!s"en" connec"!ons, and !n"roduced
per'ormance 'ea"ures such as "he ab!l!" "o do s"a"emen" cach!ng and a
ne+ arra b!nd 'unc"!on.
OC:$ 1.I Re'ac"ored connec"!on managemen" !n"roduced suppor" 'or Oracle
Da"abase 11g DRCP connec"!on pool!ng and suppor" 'or 2%7 g!&!ng h!gh
scalab!l!" and a&a!lab!l!". :ncluded suppor" 'or OracleAs e/"ernal
au"hen"!ca"!on.
OC:$ 1.J 7e+ oci$set$J 'unc"!ons 'or be""er !n"egra"!on +!"h da"abase
au"hen"!ca"!on, aud!"!ng and mon!"or!ng, and also 'or help!ng m!gra"!on
b allo+!ng mul"!ple &ers!ons o' P.<4B. pac(ages "o be used
concurren"l. :n"roduces OC:N7ON%UTONCOMM:T as an al!as o'
OC:ND;2%U.T.
&*
!H! !D. 4%tension
PHP P#O Eten!ion
PHP Da"a Ob8ec"s CPDOF !s a da"a abs"rac"!on e/"ens!on "ha" pro&!des PHP 'unc"!ons 'or
access!ng da"abases us!ng a common core o' da"abase !ndependen" me"hods. ;ach da"abase
has !"s o+n dr!&er, +h!ch ma also suppor" &endor spec!'!c 'unc"!onal!". PDONOC: pro&!des "he
Oracle 'unc"!onal!" 'or PDO. The PDO e/"ens!on and PDONOC: dr!&er are open source and
!ncluded !n PHP H.1 on+ards. Oracle does no" con"r!bu"e "o PDONOC:.
The PHP commun!" has le" "he PDO pro8ec" langu!sh and Oracle recommends us!ng OC:$
!ns"ead +hene&er poss!ble because o' !"s be""er 'ea"ure se", per'ormance, rel!ab!l!" and
s"ab!l!". Use o' PDONOC: 'or general purpose appl!ca"!ons !s not recommended. Ho+e&er PDO
!s used b some 'rame+or(s and h!gher le&el pac(ages, such as con"en" managemen"
ss"ems so ou ma need "o use !".
%n e/ample scr!p" "ha" '!nds c!" names 'rom "he .OC%T:O74 "able us!ng PDONOC: !s)
Script &' connectpdo"php
<?php
)d/h * new EL3%0oci:d/name*localhost/,-0+ 0hr0+ 0welcome0&!
)s * )d/h-prepare%"select cit# 'rom locations"&!
)s-e.ecute%&!
while %%)r * )s-'etch%EL3::A-:4>$67734&& 8* 'alse& (
echo htmlentities%)r9045:;0<& . "</r"!
=
?
The ou"pu" !s "he same as "he OC:$ e/ample !n 2!gure J.
The Da"a 4ource 7ame CD47F pre'!/ oci: mus" be lo+ercase. The &alue o' d/name !s "he
Oracle connec"!on !den"!'!er 'or our da"abase.
Getting the P#O Eten!ion
PDO and "he PDONOC: dr!&er are !ncluded +!"h PHP source code. Recen" &ers!ons o' PHP !ns"all
"he gener!c PDO e/"ens!on code b de'aul", bu" "he da"abase dr!&ers such as PDONOC: need "o
be e/pl!c!"l added +h!le bu!ld!ng, or "he can be !ns"alled manuall a'"er+ard.
Onl a 'e+ m!nor changes ha&e been made b "he commun!" "o PDONOC: s!nce !"s
!n"roduc"!on. The &ers!on o' PDONOC: !n "he P;C. repos!"or has no" been upda"ed +!"h "hese
'!/es, or +!"h o"her changes needed "o be compa"!ble +!"h recen" &ers!ons o' PHP. The P;C.
repos!"or PDONOC: release should no" be used.
PHP 9ra1e;or=!
PHP 2rame+or(s are !ncreas!ngl popular. Descr!b!ng "hem !s ou" o' scope o' "h!s boo(. The
almos" all are +r!""en !n PHP and abs"rac" "he use o' PDO or na"!&e dr!&ers. :' ou are choos!ng
a PHP 'rame+or(, cons!der one "ha" uses OC:$ !ns"ead o' PDONOC: because no" onl !s OC:$
more s"able, !" has cach!ng, pool!ng and o"her scalab!l!" 'ea"ures "ha" PDONOC: does no".
PHP #ata$a!e ,$!traction 'i$rarie!
There are some older, bu" s"!ll &!able, abs"rac"!on l!brar!es 'or PHP)
&+
!H! .racle 4%tensions
%DOdb
P;%R D-
P;%R MD-2
Mou can 'reel do+nload and use "he PHP code 'or "hese l!brar!es. The all use OC:$ 'unc"!ons
!n "he!r !mplemen"a"!ons.
,#Od$
The %DOdb l!brar !s a&a!lable 'rom http://adod/.source'orge.net. There !s an op"!onal C
e/"ens!on plug?!n !' ou need e/"ra per'ormance.
%n e/ample scr!p" "ha" '!nds c!" names 'rom "he .OC%T:O74 "able us!ng %DOdb)
Script 2' connectadodb"php
<?php
re"uire$once%"adod/.inc.php"&!
)d/ * 6L3Mew4onnection%"oci8"&!
)d/-4onnect%"localhost/,-"+ "hr"+ "welcome"&!
)s * )d/--.ecute%"select cit# 'rom locations"&!
while %)r * )s-AetchBow%&& (
echo htmlentities%)r9045:;0<& . "</r"!
=
?
There !s an Advanced Oracle )utorial a")
http://phplens.com/lens/adod//docs-oracle.htm
PE,: #)
The PHP ;/"ens!on and %ppl!ca"!on Repos!"or CP;%RF con"a!ns man use'ul pac(ages "ha"
e/"end PHPKs 'unc"!onal!". P;%R D- !s a pac(age 'or da"abase abs"rac"!on. :" !s a&a!lable 'rom
http://pear.php.net/package/LI. P;%R D- has been superseded b P;%R MD-2 bu" !s s"!ll
some"!mes used.
PE,: 5#)2
The P;%R MD-2 pac(age !s a&a!lable 'rom http://pear.php.net/package/NLI2. :" !s a l!brar
a!m!ng "o comb!ne "he bes" o' P;%R D- and "he PHP Me"abase abs"rac"!on pac(ages.
%n e/ample scr!p" "ha" '!nds c!" names 'rom "he .OC%T:O74 "able us!ng MD-2)
Script 6' connectpear"php
<?php
re"uire%"NLI2.php"&!
)md/2 * NLI2::connect%0oci8://hr:welcomeO//localhost/,-0&!
)res * )md/2-"uer#%"select cit# 'rom locations"&!
while %)row * )res-'etchBow%NLI2$A-:4>N3L-$67734&& (
echo htmlentities%)row90cit#0<& . "<//r"!
=
?
&-
The !H! Release Cycle
The PHP :elea!e C6cle
PHPKs source code !s under con"!nual de&elopmen" !n a source code con"rol ss"em &!e+able
a" http://git.php.net/. Th!s !s "he onl place bug '!/es are merged. The code !s open source
and anone can read "he code !n 3!" or see( appro&al "o con"r!bu"e. 3!" DpullE re>ues"s can be
subm!""ed a" https://githu/.com/php/php-src.
The code !n 3!" !s used "o crea"e "he &ar!ous PHP d!s"r!bu"!ons)
T+o?hourl snap?sho"s are crea"ed con"a!n!ng a comple"e se" o' all PHPKs source !n "he 3!"
repos!"or a" "he "!me "he snapsho" +as crea"ed. Mou can upda"e our PHP en&!ronmen"
b ge""!ng "h!s source code and recomp!l!ng, or b do+nload!ng "he 0!ndo+s b!nar!es.
The snapsho"s ma be rela"!&el uns"able because "he code !s !n 'lu/. The snapsho"s are
loca"ed a" http://snaps.php.net/.
The PHP release manager 're>uen"l releases a ne+ s"able &ers!on o' PHP. :" uses "he
mos" curren" 3!" code a" "he "!me o' release. Curren"l "he release ccle !s mon"hl.
P;C. OC:$ source code snapsho"s are "a(en 'rom 3!". Recen"l snapsho"s ha&e been
made concurren"l a" "he "!me o' a PHP release C+hen OC:$ has changedF.
,ar!ous opera"!ng ss"ems bundle "he &ers!on o' PHP curren" a" "he "!me "he O4 !s
released and pro&!de cr!"!cal pa"ch upda"es.
The schedules o' PHP releases, "he P;C. source snapsho"s, and "h!rd par" d!s"r!bu"!ons are
no" 'ull snchron!1ed.
&0
!H! .racle 4%tensions
&1
CH,PTE: "
INST,''ING O:,C'E #,T,),SE 11G
E4P:ESS E#ITION
Th!s chap"er con"a!ns an o&er&!e+ o', and !ns"alla"!on !ns"ruc"!ons 'or, Oracle Da"abase 11g
;/press ;d!"!on CDOracle =;EF. The !ns"alla"!on !ns"ruc"!ons are g!&en 'or .!nu/ and 0!ndo+s.
Oracle #ata$a!e Edition!
There are a number o' ed!"!ons o' "he Oracle da"abase, each +!"h d!''eren" 'ea"ures, l!cens!ng
op"!ons and cos"s. The ed!"!ons are)
;/press ;d!"!on
4"andard ;d!"!on One
4"andard ;d!"!on
;n"erpr!se ;d!"!on
%ll "he ed!"!ons are bu!l" us!ng "he same code base. Tha" !s, "he all ha&e "he same source
code, bu" d!''eren" 'ea"ures are a&a!lable !n each ed!"!on. ;n"erpr!se ;d!"!on has all "he bells
and +h!s"les, +hereas "he 'ree ;/press ;d!"!on has a l!m!"ed 'ea"ure se", bu" s"!ll has all "he
rel!ab!l!" and per'ormance o' "he ;n"erpr!se ;d!"!on. The PHP code ou +r!"e 'or ;/press
;d!"!on can be used unchanged +!"h ;n"erpr!se ;d!"!on.
Mou could s"ar" o'' +!"h "he ;/press ;d!"!on, and, as needed, mo&e up "o ano"her ed!"!on as
our scalab!l!" and suppor" re>u!remen"s change. Mou could do "h!s +!"hou" chang!ng an o'
our underl!ng "able s"ruc"ure or code. *us" change "he Oracle so'"+are and ouKre a+a.
There !s a comprehens!&e l!s" o' "he 'ea"ures 'or each Oracle ed!"!on a"
http://www.oracle.com/us/products/data/ase/product-editions-0PP501.html.
Th!s boo( d!scusses +or(!ng +!"h Oracle Da"abase 11g =;.
Oracle #ata$a!e 11g 4E
The 'ree Oracle Da"abase 11g ;/press ;d!"!on !s a&a!lable !n I2?b!" 'orm on 0!ndo+s and OJ?
b!" 'or .!nu/ pla"'orms. Oracle Da"abase 11g =; !s a good cho!ce 'or de&elopmen" o' PHP
appl!ca"!ons "ha" re>u!re a 'ree, small 'oo"pr!n" da"abase.
Oracle Da"abase 11g =; !s a&a!lable on "he Oracle Technolog 7e"+or( a"
http://www.oracle.com/technetwork/products/e.press-edition/oCerCiew/inde..html 'or
"he 'ollo+!ng opera"!ng ss"ems)
M!croso'" 0!ndo+s =P Pro'ess!onal
M!croso'" 0!ndo+s 4er&er 200I Call ed!"!onsF, 200I R$ Call ed!"!onsF, 200$ C4"andard,
;n"erpr!se, Da"acen"er, 0eb and 2ounda"!on ed!"!onsF
M!croso'" 0!ndo+s P CPro'ess!onal, ;n"erpr!se, and Ul"!ma"e ed!"!onsF
Oracle .!nu/ and RH;. J Upda"e P, or H Upda"e 2, or la"er upda"es.
&2
'nstalling .racle Data5ase &&g 4%press 4dition
4U4; 4.;4 10 4P2 and 11
The !ns"alla"!on needs 1.H 3- o' d!s( space. % R%M s!1e o' H12M- !s recommended as "he
m!n!mum.
There are some l!m!"a"!ons on us!ng Oracle Da"abase 11g =;)
Up "o 113- o' da"a can be s"ored
% s!ngle da"abase !ns"ance !s !ns"allable
% s!ngle CPU !s used, e&en !' mul"!ple CPUs e/!s"
Onl 13- R%M used, e&en !' more R%M !s !ns"alled
These l!m!"a"!ons do no" e/!s" !n o"her ed!"!ons o' Oracle Da"abase.
Oracle Da"abase 11g =; has a bro+ser?based appl!ca"!on de&elopmen" "ool called Oracle
%ppl!ca"!on ;/press. :" has some managemen" capab!l!"!es.
4uppor" 'or Oracle Da"abase 11g =; !s "hrough an Oracle Technolog 7e"+or( d!scuss!on
'orum, +h!ch !s popula"ed b peers and produc" e/per"s. Mou canno" bu suppor" 'rom Oracle
'or Oracle Da"abase 11g =;. :' ou need a 'ull suppor"ed &ers!on 'or "he Oracle da"abase,
ou should cons!der Oracle 4"andard ;d!"!on or ;n"erpr!se ;d!"!on. Mou can do+nload all "he
ed!"!ons o' "he Oracle Da"abase 'rom "he Oracle Technolog 7e"+or(. 4ub8ec" "o "he cl!c(
"hrough l!cense, ou can use "hem 'or appl!ca"!on de&elopmen" and "es"!ng, bu" +hen ou go
produc"!on, ou +!ll need "o purchase a l!cense.
In!talling Oracle #ata$a!e 11g 4E on 'inu
Mos" PHP appl!ca"!ons are deploed on .!nu/. Mou can ob"a!n Oracle .!nu/ and pa"ches 'or 'ree
'rom https://linu..oracle.com/. The um ser&er a" http://pu/lic-#um.oracle.com/
e/pla!ns ho+ "o con'!gure "he repos!"or "o ge" upda"es. :' ou +an" "o crea"e a &!r"ual
mach!ne "o run .!nu/, OracleAs ,!r"ual-o/ ma(es !" eas. Mou can do+nload "h!s 'rom
https://www.Cirtual/o..org/.
To !ns"all Oracle Da"abase 11g =; on .!nu/)
1. Turn o'' 4;.!nu/ b ed!"!ng ;etc;selinux;con*ig on Oracle .!nu/ and se""!ng)
4;.:7U=Qd!sabled
Reboo" "he ss"em a'"er do!ng "h!s, or also use "he seten*orce program.
2. :ns"all "he re>u!red pac(ages, o' "he g!&en &ers!ons or la"er)
4cr!p" 2) glibc release 2.I.J?2.J1
4cr!p" I) +a1e release I.$0
4cr!p" J) binutils 2.1O.L1.0.H
4cr!p" H) gcc J.1.2
4cr!p" O) libaio 0.I.10J
I. Do+nload Oracle Da"abase 11g =; 'rom
http://www.oracle.com/technetwork/products/e.press-edition/downloads/inde..html.
J. .og !n or su as root)
Q su -
Eassword:
H. :ns"all "he RPM)
(3
'nstalling .racle Data5ase &&g 64 on Linu%
Q rpm -iCh oracle-.e-11.2.0-1.0..8P$PD.rpm
Oracle Da"abase 11g =; !ns"alls !n a 'e+ m!nu"es.
O. Con'!gure "he da"abase)
Q /etc/init.d/oracle-.e con'igure
P. %ccep" "he por"s. The de'aul" are 1313 'or %ppl!ca"!on ;/press, and &+(& 'or "he
Da"abase .!s"ener.
$. ;n"er and con'!rm "he pass+ord 'or "he de'aul" users.
L. ;n"er 7 or N 'or +he"her ou +an" "he da"abase "o s"ar" au"oma"!call on reboo". The
da"abase and da"abase l!s"ener are con'!gured and s"ar"ed.
:' ou use "he Oracle Unbrea(able .!nu/ 7e"+or( and ha&e "he Oracle 4o'"+are channel
enabled, ou could !ns"ead !ns"all Oracle Da"abase 11g =; +!"h)
Q up2date oracle-.e
%'"er "h!s do+nload comple"es, 'ollo+ "he pre&!ous con'!gura"!on s"eps 'rom s"ep H on+ards.
In!talling Oracle #ata$a!e 11g 4E on Windo;!
To !ns"all Oracle Da"abase 11g =; on 0!ndo+s, 'ollo+ "hese s"eps)
1. .og on "o 0!ndo+s as a user +!"h %dm!n!s"ra"!&e pr!&!leges.
2. Do+nload Oracle Da"abase 11g =; 'rom
http://www.oracle.com/technetwork/products/e.press-edition/downloads/inde..html.
I. Un1!p Oracle<E&&2=Win62"ip and na&!ga"e "o "he D!s(1 'older. Double cl!c( on "he
setup"exe '!le.
J. :n "he Oracle Da"abase 11g =; ? :ns"all 0!1ard +elcome +!ndo+, cl!c( Ne%t.
(&
(igure 4' Oracle Database &&g <E install
,elco+e dialog"
'nstalling .racle Data5ase &&g 4%press 4dition
H. :n "he .!cense %greemen" +!ndo+, accep" "he l!cense and cl!c( Ne%t.
O. :n "he Choose Des"!na"!on .oca"!on +!ndo+, e!"her accep" "he de'aul" or cl!c( -ro+se "o
selec" a d!''eren" !ns"alla"!on d!rec"or. Cl!c( Ne%t.
P. Oracle Da"abase 11g =; selec"s a number o' de'aul" por"s. :' "hese por"s are alread
be!ng used, ou are promp"ed "o en"er ano"her number.
$. :n "he 4pec!' Da"abase Pass+ords +!ndo+, en"er and con'!rm "he pass+ord "o use 'or "he
S>S and S>S)E! da"abase accoun"s. Cl!c( Ne%t.
((
(igure ?' Oracle Database &&g <E database
pass,ord dialog"
(igure 9' Oracle Database &&g <E install
location dialog"
'nstalling .racle Data5ase &&g 64 on Windo/s
L. :n "he 4ummar +!ndo+, re&!e+ "he !ns"alla"!on se""!ngs. Cl!c( 'nstall.
10. :n "he :ns"all4h!eld 0!1ard Comple"e +!ndo+, cl!c( 8inish.
0!ndo+s users +!ll unders"andabl +an" "o de&elop on a 'am!l!ar pla"'orm. Ho+e&er, because
mos" PHP deplomen"s are on .!nu/, and because o' d!''erences !n per'ormance and beha&!or
o' PHP on 0!ndo+s, ou should s"rongl cons!der de&elop!ng on .!nu/ "o a&o!d une/pec"ed
surpr!ses +hen appl!ca"!ons are deploed.
5anaging the Oracle #ata$a!e 11g 4E
The Oracle Da"abase 11g =; can be managed +!"h command l!ne "ools, Oracle %ppl!ca"!on
;/press and Oracle 4B. De&eloper.
Setting the Oracle #ata$a!e 11g 4E En-iron1ent <aria$le! on 'inu
There are a number o' en&!ronmen" se""!ngs and con'!gura"!on op"!ons ou can se" 'or Oracle
Da"abase 11g =;. The more commonl used se""!ngs are precon'!gured.
On .!nu/ pla"'orms a scr!p" !s pro&!ded "o se" "he Oracle en&!ronmen" &ar!ables a'"er ou
log !n. The scr!p" 'or -ourne, -ash and 6orn shells)
/u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
2or C and "csh shells, use oracle=env"csh. Run "he appropr!a"e scr!p" 'or our shell "o se" our
Oracle Da"abase 11g =; en&!ronmen" &ar!ables. Mou can also add "h!s scr!p" "o our log!n
pro'!le "o ha&e "he en&!ronmen" &ar!ables se" up au"oma"!call +hen ou log !n.
To add "he scr!p" "o our -ourne, -ash or 6orn shell, add "he 'ollo+!ng l!nes "o our
"bash=pro*ile or "bashrc '!le)
source /u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
()
(igure /' Oracle Database &&g <E install
su++ary dialog"
'nstalling .racle Data5ase &&g 4%press 4dition
:n some &ers!ons o' "he shells ou ma need "o use a s!ngle per!od !ns"ead o' source. To add
"he scr!p" "o our log!n pro'!le 'or C and "csh shells, use "he oracle=env"csh '!le !ns"ead.
:' ou e&er 'orge" +here "he Oracle so'"+are !s !ns"alled, loo( a" "he '!le ;etc;oratab. Th!s l!s"s
each Oracle Da"abase home d!rec"or.
Starting and Stopping the 'i!tener and #ata$a!e
The da"abase l!s"ener !s an Oracle 7e" program "ha" l!s"ens 'or, and responds "o, re>ues"s "o
"he da"abase. The da"abase l!s"ener mus" be runn!ng "o handle "hese re>ues"s. The da"abase
!s ano"her process "ha" runs !n memor, and needs "o be s"ar"ed be'ore Oracle 7e" can hand
connec"!on re>ues"s "o !".
%'"er !ns"all!ng Oracle Da"abase 11g =;, "he l!s"ener and da"abase should alread be
runn!ng, and ou ma ha&e re>ues"ed dur!ng "he !ns"alla"!on "ha" "he l!s"ener and da"abase
should be s"ar"ed +hen "he opera"!ng ss"em s"ar"s up. :' ou need "o manuall s"ar" or s"op
"he da"abase l!s"ener, "he op"!ons and commands 'or "h!s are l!s"ed belo+.
Enabling Database Startup and Shutdown on Linux
Mou ma no" !n!"!all be able "o s"ar" and s"op "he da"abase us!ng "he menu on .!nu/
pla"'orms unless ou are logged !n as "he roo" user. Th!s !s because our user !s no" a member
o' "he opera"!ng ss"em dba group b de'aul". To enable "h!s 'unc"!onal!", add our username
"o "he dba group us!ng .!nu/As 4s"em 4e""!ngs and re?log!n.
Starting and Stopping the Listener and Database on Linux
The adm!n!s"ra"!on op"!ons are !n an Oracle Database &&g Express Edition menu. Depend!ng
on our &ers!on o' .!nu/ "h!s +!ll be loca"ed under "he Applications, !ain or @ !enu menu. To
s"ar" up "he l!s"ener and da"abase on .!nu/ pla"'orms us!ng "he des("op, selec" .racle
Data5ase &&g 4%press 4dition 9 #tart Data5ase. To shu" do+n "he da"abase on .!nu/
pla"'orms us!ng "he des("op, selec" .racle Data5ase &&g 4%press 4dition 9 #top
Data5ase.
To s"ar" "he l!s"ener and da"abase on .!nu/ pla"'orms us!ng "he command l!ne, run "he
'ollo+!ng command !n a shell as "he roo" user)
Q serCice oracle-.e start
To s"op "he l!s"ener and da"abase on .!nu/ pla"'orms us!ng "he command l!ne, run "he
'ollo+!ng command !n our shell)
Q serCice oracle-.e stop
The scr!p" !s loca"ed !n ;etc;init"d. :' service does no" e/!s" !n our en&!ronmen", run "he scr!p"
d!rec"l.
Mou can also use "he Services d!alog under "he 4s"em %dm!n!s"ra"!on menu "o con"rol "he
l!s"ener and da"abase. 2or e/ample, "o s"ar" "he l!s"ener and da"abase 'rom "he Des("op
4er&!ces d!alog on Oracle .!nu/ H +!"h "he 3nome +!ndo+ manager, selec" #ystem
9Administration 9 #er$er #ettings 9 #er$ices. 4elec" oracle%e 'rom "he l!s" o' ser&!ces
and selec" #tart.
(*
:anaging the .racle Data5ase &&g 64
Starting and Stopping the Listener and Database on Windows
To s"ar" "he l!s"ener and da"abase on 0!ndo+s pla"'orms, !n "he All !rograms menu selec"
.racle Data5ase &&g 4%press 4dition R #tart Data5ase. % 0!ndo+ !s d!splaed sho+!ng
"he s"a"us o' "he l!s"ener and da"abase s"ar"up process.
Tpe e%it and press ;n"er "o close "he +!ndo+. The l!s"ener and da"abase are no+ s"ar"ed.
To s"op "he l!s"ener and da"abase on 0!ndo+s pla"'orms, selec" All !rograms R .racle
Data5ase &&g 4%press 4dition R #top Data5ase. % +!ndo+ !s d!splaed sho+!ng "he
s"a"us o' "he l!s"ener and da"abase shu"do+n process.
Tpe e%it and press ;n"er "o close "he +!ndo+. The l!s"ener and da"abase are no+ s"opped.
Mou can also s"ar" and s"op "he l!s"ener separa"el on 0!ndo+s pla"'orms us!ng "he 4er&!ces
d!alog.
)a!ic 5onitoring o* Oracle #ata$a!e 11g 4E
The Oracle %ppl!ca"!on ;/press D%pe/E "ool pro&!des some bas!c da"abase mon!"or!ng.
(+
(igure 8' Start Database dialog"
(igure &A' Stop Database dialog"
'nstalling .racle Data5ase &&g 4%press 4dition
Oracle 4B. De&eloper also has mon!"or!ng and managemen" capab!l!"!es, d!scussed !n "he
ne/" chap"er.
To use %pe/ "o &er!' "he !ns"alla"!on o' Oracle Da"abase 11g =;)
1. Open a +eb bro+ser and en"er "he home page adm!n!s"ra"!on UR., us!ng "he por" ou
selec"ed dur!ng !ns"alla"!on, http';;localhost'/A/A;*BpC584A" Th!s UR. !s also !n&o(ed b
"he ,et #tarted sub?menu op"!on o' "he .racle Data5ase &&g 4%press 4dition menu.
2. The Da"abase adm!n!s"ra"!on page !s d!splaed.
I. Cl!c( on Storage. .og !n as user S>S)E! +!"h "he pass+ord ou en"ered dur!ng "he
!ns"alla"!on. Mou should no+ see "he da"abase con'!gura"!on parame"ers "ha" ha&e non?
de'aul" &alues. Mou can also un?chec( "he '!l"er "o see all parame"er &alues.
4!m!larl +!"h "he o"her "op le&el menu !"ems on "he Da"abase home page ou can
&!e+ "he curren" sess!ons o' da"abase connec"!ons, and loo( a" "he !n!"!al!1a"!on
parame"ers o' "he da"abase.
(-
(igure &&' Oracle Database &&g <E ho+e page
login screen"
(igure &2' Oracle Database &&g <E para+eters
page"
.racle Terminology
Oracle Ter1inolog6
There are some d!''erences be"+een "he "erm!nolog used +hen descr!b!ng an Oracle
da"abase and o"her da"abases. The 'ollo+!ng o&er&!e+ co&ers "he ma!n Oracle "erm!nolog.
Databases and Instances
%n Oracle da"abase s"ores and re"r!e&es da"a. ;ach da"abase cons!s"s o' one or more da"a
'!les. %n Oracle database server cons!s"s o' an Oracle database and an Oracle instance. ;&er
"!me a ser&er !s s"ar"ed, a shared memor reg!on called "he syste+ global area C43%F !s
alloca"ed and "he Oracle bac(ground processes are s"ar"ed. The comb!na"!on o' "he
bac(ground processes and 43% !s called an Oracle instance. On some opera"!ng ss"ems, l!(e
0!ndo+s, "here are no separa"e bac(ground processes. :ns"ead "hreads run +!"h!n "he Oracle
!mage.
Tablespaces
Tablespaces are "he log!cal un!"s o' da"a s"orage made up o' one or more da"a'!les.
Tablespaces are o'"en crea"ed 'or !nd!&!dual appl!ca"!ons because "ablespaces can be
con&en!en"l managed. Users are ass!gned a de'aul" "ablespace "ha" holds all "he da"a "he
users crea"e. % da"abase !s made up o' de'aul" and D-%?crea"ed "ablespaces.
Schemas and Users
% schema !s a collec"!on o' da"abase ob8ec"s such as "ables and !nde/es. % schema !s o+ned
b a da"abase user and has "he same name as "ha" user. Man people use "he +ords sche+a
and user !n"erchangeabl.
Once ou ha&e !ns"alled PHP and +an" "o +r!"e scr!p"s "ha" !n"erac" +!"h Oracle, ou need
"o connec" as "he o+ner o' "he schema "ha" con"a!ns "he ob8ec"s ou +an" "o !n"erac" +!"h. 2or
e/ample, "o connec" "o "he HR schema, ou +ould use "he username HR !n PHPKs connec"!on
s"r!ng.
%l"hough ou ma ha&e more "han one da"abase per mach!ne, "p!call onl a s!ngle
Oracle da"abase e/!s"s con"a!n!ng mul"!ple schemas. Mul"!ple appl!ca"!ons can use "he same
da"abase +!"hou" an con'l!c" b us!ng d!''eren" schemas. :ns"ead o' us!ng a 4B-6:- L6:6I67-
command 'or ne+ appl!ca"!ons, !n Oracle use "he 4B-6:- R7-B command "o crea"e a ne+
schema !n "he da"abase.
(0
'nstalling .racle Data5ase &&g 4%press 4dition
(1
CH,PTE: 5
S&' WITH O:,C'E #,T,),SE
Th!s chap"er con"a!ns an o&er&!e+ o' some 4B.SPlus, Oracle %ppl!ca"!on ;/press and Oracle
4B. De&eloper 'ea"ures ou can use "o per'orm da"abase de&elopmen". These "hree "ools are
a&a!lable +!"h, or 'or, all ed!"!ons o' Oracle Da"abase. The o''er an e/"ens!&e se" o'
de&elopmen" 'unc"!onal!". Th!s chap"er 'ocuses on ho+ "o use "hem 'or 4B. de&elopmen".
Tes"!ng and "un!ng 4B. !s o'"en more eas!l done !n one o' "hese "ools be'ore !ncorpora"!ng !"
!n"o PHP appl!ca"!ons.
Oracle S&'>Plu!
4B.SPlus !s OracleAs "rad!"!onal command l!ne "ool. :" !s a&a!lable +hene&er "he da"abase !s
!ns"alled. :" !s also a&a!lable !n D:ns"an" Cl!en"E 'orm so cl!en" mach!nes can eas!l connec" "o a
remo"e da"abase. 4B.SPlus allo+s ad?hoc >uer!es, scr!p"!ng and 'undamen"al da"abase
adm!n!s"ra"!on. Man boo(s, !nclud!ng "h!s one, use 4B.SPlus "o sho+ 4B. e/amples.
Setting the En-iron1ent *or S&'>Plu!
Oracle Da"abase &&g =; se"s up a menu op"!on "o run 4B.SPlus. Ho+e&er, !n general, !' ou
+an" "o run 4B.SPlus 'rom a "erm!nal +!ndo+, "he sDlplus e/ecu"able mus" be !n our P%TH
and se&eral en&!ronmen" &ar!ables need "o be se" e/pl!c!"l. These are pre?se" !n "he reg!s"r
on 0!ndo+s.
:n "he .!nu/ bash shell, se" "he en&!ronmen" 'or Oracle Da"abase &&g =; +!"h)
) source /u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
:n some &ers!ons o' "he shell ou +!ll need "o use a per!od !ns"ead o' source. %n e>u!&alen"
'!le +!"h "he su''!/ D.cshE e/!s"s 'or users o' "he C shell.
On o"her ed!"!ons o' "he Oracle da"abase, "he ;usr;local;bin;oraenv or
;usr;local;bin;coraenv C'or users o' C shellF scr!p"s se" "he en&!ronmen". :n "he -ash shell, use)
) source /usr/local//in/oraenC
3B64K-$75L * 9< ?
Mou +!ll be promp"ed 'or "he ss"em !den"!'!er C@4:D@F o' "he da"abase "ha" ou !n"end "o
connec" "o on "h!s mach!ne. The a&a!lable 4:Ds can be seen !n ;etc;oratab. Tpe "he des!red
4:D and press en"er.
:' ou are runn!ng 4B.SPlus on a mach!ne remo"e 'rom "he da"abase ser&er, ou need "o
manuall se" "he en&!ronmen".
The same en&!ronmen" &ar!ables needed 'or 4B.SPlus are also used b "he PHP OC:$
e/"ens!on.
Starting S&'>Plu!
Once "he en&!ronmen" !s se", 4B.SPlus can be s"ar"ed +!"h "he sDlplus command)
) s"lplus
(2
#;L With .racle Data5ase
7SKJElus: Belease 11.2.0.2.0 - Eroduction on 7at Tun 2 1U:19:09 2012
4op#right %c& 1982+ 2011+ 3racle. 6ll rights reserCed.
-nter user-name: s#stem
-nter password:
4onnected to:
3racle Lata/ase 11g -.press -dition Belease 11.2.0.2.0 V PD/it Eroduction
7SK
2or Oracle 11g =;, "he pass+ord "o en"er !s "he one se" dur!ng !ns"alla"!on. %'"er s"ar"!ng
4B.SPlus, "he promp" 7SK !s sho+n. %" "he promp" ou can "pe 4B. commands. ;n"er >-KE
5ML-, "o '!nd a l!s" o' commands. Tpe -,5: "o >u!".
:n de&elopmen", !" !s common "o pu" "he username, pass+ord and da"abase "ha" ou +an"
"o connec" "o all on "he command l!ne, bu" be+are "ha" en"er!ng "he pass+ord l!(e "h!s !s a
secur!" r!s()
s"lplus s#stem/s#stempwdOlocalhost/,-
% be""er prac"!ce !s "o run)
s"lplus s#stemOlocalhost/,-
Th!s +!ll promp" 'or "he pass+ord.
%no"her +a !s "o s"ar" 4B.SPlus +!"hou" a""emp"!ng "o log on, and "hen use "he 43MM-4:
command)
) s"lplus /nolog
. . .
7SK connect s#stem/s#stempwdOlocalhost/,-
4onnected.
7SK
To connec" as a pr!&!leged user 'or da"abase adm!n!s"ra"!on, '!rs" log!n "o "he opera"!ng ss"em
as a user !n "he opera"!ng ss"em dba group and "hen use)
) s"lplus / as s#sd/a
or
s"lplus /nolog
7SK connect / as s#sd/a
0!ing S&'>Plu! to 0nloc= the H: Sche1a *or #e1on!tration Ta$le ,cce!!
2or general da"abase access, !" !s be""er no" "o connec" as "he 4M4T;M user. Th!s boo( uses
"he Human Resource sample "ables, loca"ed !n "he HR schema. To unloc( "h!s accoun" and se"
"he pass+ord a'"er "he da"abase has been !ns"alled, connec" as a pr!&!leged user and e/ecu"e
an 6K:-B R7-B command)
7SK connect s#stem/s#stempwd
7SK alter user hr identi'ied /# welcome account unlock!
)3
.racle #;L<!lus
Th!s se"s "he pass+ord "o welcome.
Creating #ata$a!e 0!er! in S&'>Plu!
:' ou +an" "o crea"e our o+n schema, s"ar" 4B.SPlus. Then run 4B. s"a"emen"s l!(e)
7SK connect s#stem/s#stempwdOlocalhost/,-
7SK create user cW identi'ied /# welcome!
7SK alter user cW de'ault ta/lespace users
temporar# ta/lespace temp
"uota unlimited on users!
7SK grant create session
+ create ta/le
+ create procedure
+ create se"uence
+ create trigger
+ create Ciew
+ create s#non#m
+ alter session
to cW!
Th!s crea"es a user c0 +!"h pass+ord o' ,elco+e. The user has "he capab!l!" "o crea"e and
use some "pes o' da"abase ob8ec"s. Mou can choose +h!ch pr!&!leges "o gran" each user
depend!ng on +ha" our appl!ca"!on does.
Eecuting S&' and P'2S&' State1ent! in S&'>Plu!
4B. s"a"emen"s such as >uer!es mus" be "erm!na"ed +!"h a sem!?colon CGF)
7SK select J 'rom locations!
or +!"h a s!ngle slash C/F)
7SK select J 'rom locations
2 /
Th!s las" e/ample also sho+s 4B.SPlus promp"!ng 'or a second l!ne o' !npu". Code !n OracleAs
procedural language, P.<4B., mus" end +!"h a slash !n add!"!on "o "he P.<4B. codeAs sem!?
colon)
7SK /egin
2 m#proc%&!
@ end!
D /
The "erm!na"!ng sem!?colon or slash !s no" par" o' "he s"a"emen". Tools o"her "hen 4B.SPlus
+!ll use d!''eren" me"hods "o !nd!ca"e Dend o' s"a"emen"E.
:' a blan( l!ne C!n 4B.F or a s!ngle per!od C!n 4B. or P.<4B.F !s en"ered, 4B.SPlus re"urns "o
"he ma!n promp" and does no" e/ecu"e "he s"a"emen")
7SK select J 'rom locations
2
7SK
)&
#;L With .racle Data5ase
Commands "ha" are local "o 4B.SPlus l!(e 7:6B:RE and 7-: +h!ch are no" sen" "o "he da"abase
do no" need a "erm!na"!ng sem!?colon or slash.
Controlling &uer6 Output in S&'>Plu!
4B.SPlus has &ar!ous +as "o con"rol ou"pu" d!spla.
The 7-: command con"rols some 'orma""!ng. 2or e/ample, "o change "he page s!1e Cho+
o'"en "able column names repea"F and "he l!ne s!1e C+here l!nes +rapF)
7SK set pagesiXe 80
7SK set linesiXe 1@2
:' ou are 'e"ch!ng da"a 'rom .O73, C.O- or -.O- columns, !ncrease "he ma/!mum number o'
charac"ers "ha" +!ll d!spla C"he de'aul" !s 8us" $0F)
7SK set long 1000
The column +!d"h o' >uer!es can be changed +!"h "he 43KRNM command, here se""!ng "he
COU7TRMN7%M; ou"pu" +!d"h "o 20 charac"ers, and "he R;3:O7N:D column "o a numer!c
'orma" +!"h a dec!mal place)
7SK select J 'rom countries where countr#$id * 0AB0!
43 43RM:B;$M6N- B-Y53M$5L
-- ---------------------------------------- ----------
AB Arance 1
7SK column countr#$name 'ormat a20
7SK column region$id 'ormat 99.0
7SK select J 'rom countries where countr#$id * 0AB0!
43 43RM:B;$M6N- B-Y53M$5L
-- -------------------- ----------
AB Arance 1.0
Ou"pu" can be spooled "o a '!le b us!ng "he 7E33K command be'ore commands are e/ecu"ed)
7SK spool /tmp/m#'ile.log
:unning S&' Script! in S&'>Plu!
:' mul"!ple 4B. s"a"emen"s are s"ored !n a scr!p" +yscript"sDl, "he can be e/ecu"ed +!"h "he
7:6B: command or !"s more common abbre&!a"!on O. 4cr!p"s can be run e!"her 'rom "he
"erm!nal promp")
) s"lplus hrOlocalhost/,- Om#script.s"l
or 'rom "he 4B.SPlus promp")
7SK Om#script.s"l
-ecause 4B.SPlus doesnA" ha&e a 'ull h!s"or command, crea"!ng scr!p"s !n an e/"ernal ed!"or
and runn!ng "hem +!"h O !s recommended.
)(
.racle #;L<!lus
Ta$le 5etadata in S&'>Plu!
Buer!es 'rom !nbu!l" &!e+s l!(e U4;RNT%-.;4 and U4;RN:7D;=;4 +!ll sho+ !n'orma"!on abou"
"he ob8ec"s ou o+n. % "rad!"!onal >uer 'rom "he C%T &!e+ g!&es a shor" summar)
7SK select J 'rom cat!
:6IK-$M6N- :6IK-$:;E-
------------------------------ -----------
43RM:B5-7 :6IK-
L-E6B:N-M:7 :6IK-
L-E6B:N-M:7$7-S 7-SR-M4-
-NEK3;--7 :6IK-
-NEK3;--7$7-S 7-SR-M4-
T3I7 :6IK-
T3I$>57:3B; :6IK-
K346:53M7 :6IK-
K346:53M7$7-S 7-SR-M4-
B-Y53M7 :6IK-
10 rows selected.
To '!nd ou" abou" "he columns o' a "able, >uer "he U4;RNT%-NCO.UM74 &!e+, or s!mpl use
"he L-74B5I- command "o g!&e an o&er&!e+)
7SK descri/e countries
Mame Mull? :#pe
----------------------------------------- -------- ----------------------------
43RM:B;$5L M3: MRKK 4>6B%2&
43RM:B;$M6N- Z6B4>6B2%D0&
B-Y53M$5L MRNI-B
Starting and Stopping the #ata$a!e With S&'>Plu!
To s"ar" up "he l!s"ener on .!nu/, open a "erm!nal +!ndo+ as "he roo" user and run "he
'ollo+!ng commands)
Q su V oracle
) source /u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
) lsnrctl start
Oracle 7e" s"ar"s "he l!s"ener, +h!ch handles commun!ca"!on be"+een "he da"abase and cl!en"
programs l!(e 4B.SPlus or PHP. :' ou la"er +an" "o shu" do+n "he l!s"ener manuall, use
lsnrctl l!(e)
) lsnrctl stop
On 0!ndo+s, use "he 4er&!ces d!alog "o con"rol "he l!s"ener.
%'"er s"ar"!ng "he l!s"ener, ou need "o s"ar" "he da"abase !"sel' us!ng 4B.SPlus. 2or "h!s,
ou mus" s"ar" 4B.SPlus +!"h "he 4M4D-% role. To s"ar" up a da"abase us!ng 4B.SPlus, en"er
"he 'ollo+!ng a" "he command l!ne promp")
Q su V oracle
) source /u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
))
#;L With .racle Data5ase
) s"lplus /nolog
The 4B.SPlus command l!ne s"ar"s. Mou can also s"ar" 4B.SPlus 'rom "he .racle Data5ase
&&g 4%press 4dition R Run #;L Command Line on .!nu/, or !rogram 8iles R .racle
Data5ase &&g 4%press 4dition R Run #;L Command Line on 0!ndo+s.
%" "he 4B.SPlus command l!ne promp", en"er "he 'ollo+!ng commands "o connec" "o "he
da"abase and s"ar" !" up)
7SK connect / as s#sd/a
7SK startup
The da"abase !s s"ar"ed.
:' ou s"ar" "he da"abase be'ore s"ar"!ng "he Oracle 7e" l!s"ener, !" can "a(e a shor" +h!le
be'ore "he da"abase reg!s"ers +!"h "he l!s"ener. Un"!l "h!s happens, connec"!ons "o "he
da"abase +!ll 'a!l. Mou can e/pl!c!"l 'orce reg!s"ra"!on +!"h)
7SK alter s#stem register!
To shu" do+n "he da"abase, ou need "o log !n as a 4M4D-% user, and !ssue "he 7>R:L3?M
5NN-L56:- command. .og !n"o 4B.SPlus as be'ore and !ssue "he 'ollo+!ng command)
7SK connect / as s#sd/a
7SK shutdown immediate
:' ou use "he al"erna"!&e 7>R:L3?M M3BN6K command, "he shu"do+n +!ll hang un"!l all open
connec"!ons ha&e comple"ed "he!r +or(. 4!nce PHP OC:$ has "he concep" o' pers!s"en"
connec"!ons "ha" rema!n open !nde'!n!"el, ou +!ll '!rs" need "o shu"do+n %pache "o close
"hose connec"!ons. Mou can also use 7>R:L3?M 6I3B: "o !mmed!a"el "erm!na"e a da"abase,
al"hough "h!s !s no" recommended.
The SEFGPlus #serHs Guide and :e*erence manual g!&es ou "he 'ull sn"a/ and o"her
op"!ons 'or s"ar"!ng up and shu""!ng do+n "he da"abase !' ou need more help.
The eas!es" +a on .!nu/ "o s"ar" and s"op Oracle =; 11g !s +!"h "he service command as
sho+n !n "he pre&!ous chap"er.
Oracle ,pplication Epre!!
Oracle %ppl!ca"!on ;/press !s a bro+ser?based appl!ca"!on bu!lder 'or "he Oracle da"abase. :" !s
!ns"alled +!"h Oracle Da"abase 11g =; and !s also a&a!lable 'or do+nload 'rom Oracle
Technolog 7e"+or( as a s"andalone produc" 'or o"her &ers!ons and ed!"!ons o' "he da"abase.
:" con"a!ns an appl!ca"!on de&elopmen" "ool, no" co&ered !n "h!s boo(. The release o' Oracle
%ppl!ca"!on ;/press !ns"alled +!"h Oracle Da"abase 11g =; has a small add!"!onal module 'or
per'orm!ng da"abase mon!"or!ng.
)*
.racle Application 4%press
Creating an ,pplication Epre!! Wor=!pace
1. Open a +eb bro+ser and en"er "he home page adm!n!s"ra"!on UR., us!ng "he por" ou
selec"ed dur!ng !ns"alla"!on, http';;localhost'/A/A;*BpC584A"
2. Cl!c( on Application Express and log!n us!ng "he creden"!als crea"ed dur!ng da"abase
!ns"alla"!on.
)+
2!gure 1J) Oracle %ppl!ca"!on ;/press
%dm!n!s"ra"!on .og!n.
(igure &6' Oracle Application Express
Ad+inistration Page"
#;L With .racle Data5ase
I. Crea"e a ne+ +or(space +!"h ne+ Da"abase and %ppl!ca"!on ;/press users. 2or e/ample,
use +yapexdb and +yapex, respec"!&el.
J. Cl!c( -reate Wor1space and "he +or(space !s crea"ed)
)-
2!gure 1H) Crea"!ng ne+ users +!"h Oracle
%ppl!ca"!on ;/press
2!gure 1O) Oracle %ppl!ca"!on ;/press
0or(space Crea"!on
.racle Application 4%press
'ogging In To Oracle ,pplication Epre!!
To log !n "o Oracle %ppl!ca"!on ;/press as "he ne+ appl!ca"!on user)
1. 2ollo+ "he Dcl!c( hereE l!n( on "he accoun" con'!rma"!on page or open "he UR.,
http';;localhost'/A/A;apex"The Oracle %ppl!ca"!on ;/press log!n screen !s d!splaed)
2. .og!n +!"h "he creden"!als ou crea"ed !n "he pre&!ous sec"!on, +yapexdb and +yapex.
)0
(igure &?' Oracle Application Express login
screen"
(igure &/' Oracle Application Express inter*ace"
#;L With .racle Data5ase
Creating #ata$a!e O$3ect! in ,pplication Epre!!
The Oracle %ppl!ca"!on ;/press Ob8ec" -ro+ser can be used "o crea"e or ed!" man "pes o'
da"abase ob8ec"s, 'rom "ables and &!e+s, r!gh" "hrough "o procedures and "r!ggers.
Oracle %ppl!ca"!on ;/press uses +!1ards "o gu!de ou "hrough crea"!ng "hese da"abase
ob8ec"s. The 'ollo+!ng e/ample co&ers crea"!ng a "able, bu" ou +!ll see "ha" "he !n"er'ace !s
+!1ard?based and crea"!ng and ed!"!ng d!''eren" ob8ec"s and >uer!es can all be per'ormed
"hrough "he 4B. 0or(shop.
To crea"e a ne+ "able)
1. On "he Da"abase home page, cl!c( "he #;L Workshop menu l!n(.
2. Cl!c( "he .5=ect >ro/ser !con. The Ob8ec" -ro+ser page !s d!splaed.
)1
(igure 2A' Oracle Application Express ob0ect
bro,ser screen"
2!gure 1L) Oracle %ppl!ca"!on ;/press 4B.
0or(shop
.racle Application 4%press
I. 4elec" "he ello+ Create menu on "he r!gh" hand s!de and choose Ta5le.
J. ;n"er a "able name !n "he Table 7ame '!eld, and de"a!ls 'or each column. Cl!c( Ne%t.
)2
(igure 2&' Oracle Application Express ob0ect
bro,ser screen
(igure 22' Oracle Application Express table
de*inition screen"
#;L With .racle Data5ase
H. .ea&e "he de'aul" 7o Pr!mar 6e and cl!c( Ne%t.
O. .ea&e "he 2ore!gn 6e unse" and cl!c( Ne%t.
P. .ea&e "he Cons"ra!n"s page unchanged and cl!c( Ne%t.
$. The 4B. 4B-6:- s"a"emen" used "o crea"e "he "able !s sho+n.
L. On "h!s con'!rma"!on page cl!c( Create "o comple"e "he crea"!on" The "able !s crea"ed and
a descr!p"!on o' "he "able !s d!splaed.
*3
(igure 25' Oracle Application Express table
created con*ir+ation screen"
2!gure 2I) Oracle %ppl!ca"!on ;/press Crea"e
Table
.racle Application 4%press
Wor=ing With S&' in ,pplication Epre!!
The 4B. 0or(shop also enables ou "o)
0r!"e 4B. and P.<4B.
.oad and sa&e 4B. scr!p"s
3raph!call bu!ld 4B.
The 'ollo+!ng e/ample gu!des ou "hrough crea"!ng a 4B. scr!p". Th!s e/ample uses "he Buer
-u!lder "o graph!call crea"e a 4B. scr!p" "o >uer da"a. The +yapex user ou crea"ed has "he
sample "ables alread crea"ed. To access Buer -u!lder)
1. On "he %ppl!ca"!on ;/press home page, cl!c( "he #;L Workshop !con.
2. Cl!c( "he ;uery >uilder !con.
*&
(igure 24' Oracle Application Express SEF
options screen"
#;L With .racle Data5ase
I. 4elec" ob8ec"s 'rom "he Ob8ec" 4elec"!on pane. 0hen ou cl!c( on "he ob8ec" name, !" !s
d!splaed !n "he Des!gn pane.
J. 4elec" columns 'rom "he ob8ec"s !n "he Des!gn pane "o selec" +h!ch columns "o !nclude !n
"he >uer resul"s.
*(
(igure 29' Oracle Application Express SEF
Duery builder screen"
2!gure 2P) Oracle %ppl!ca"!on ;/press Buer
-u!lder
.racle Application 4%press
H. ;s"abl!sh rela"!onsh!ps be"+een ob8ec"s b cl!c(!ng on "he r!gh"?hand column o' each
"able.
O. Cl!c( Run "o e/ecu"e "he >uer and &!e+ "he resul"s.
P. Mou can sa&e our >uer us!ng "he #a$e bu""on.
Creating a P'2S&' Procedure in ,pplication Epre!!
To en"er and run P.<4B. code !n "he 4B. Commands page)
1. On "he %ppl!ca"!on ;/press home page, cl!c( "he #;L Workshop !con "o d!spla "he 4B.
0or(shop page. Then cl!c( "he #;L Commands !con "o d!spla "he 4B. Commands page.
*)
(igure 2/' Oracle Application Express SEF Duery results screen"
2!gure 2L) Oracle %ppl!ca"!on ;/press 4B. Command Page
#;L With .racle Data5ase
2. On "he 4B. Commands page, en"er some P.<4B. code. 2or e/ample, "he procedure
emp$stat a&erages "he salar 'or depar"men"s !n "he HR schema, and !s encapsula"ed !n a
P.<4B. pac(age called emp$sal.
create or replace package emp$sal as
procedure emp$stat!
end emp$sal!
I. Cl!c( Run "o e/ecu"e "he P.<4B..
J. 7o+ replace "he code +!"h "he pac(age bod spec!'!ca"!on)
create or replace package /od# emp$sal as
procedure emp$stat is
t#pe -mp7tat:#p is record %Lept$name Carchar2%20&+ Lept$aCg num/er&!
-mp7tatZar -mp7tat:#p!
/egin
d/ms$output.put$line%0Lepartment 6Cg 7alar#0&!
d/ms$output.put$line%0--------------- -----------0&!
'or -mp7tatZar in %select round%aCg%e.sal&+2&
a+d.dname /
'rom dept d+ emp e
where d.deptno * e.deptno
group /# d.dname&
loop
d/ms$output.put$line%rpad%-mp7tatZar./+1P+0 0&[[
to$char%-mp7tatZar.a+0999+999+999.990&&!
end loop!
end!
end emp$sal!
**
(igure 6A' Oracle Application Express PF;SEF
and SEF co++and screen"
.racle Application 4%press
H. Cl!c( Run. The P.<4B. code !s e/ecu"ed.
O. Mou can sa&e "he P.<4B. code 'or 'u"ure use, b cl!c(!ng #a$e, or e/ecu"e "he s"ored
procedure b en"er!ng "he 'ollo+!ng P.<4B. code and cl!c(!ng Run.
/egin
emp$sal.emp$stat!
end!
*+
2!gure I2) Oracle %ppl!ca"!on ;/press 4B.
Commands 4creen
2!gure I1) Oracle %ppl!ca"!on ;/press 4B.
Commands
#;L With .racle Data5ase
Oracle S&' #e-eloper
:n add!"!on "o Oracle %ppl!ca"!on ;/press and 4B.SPlus, ou can also use Oracle 4B.
De&eloper 'or da"abase de&elopmen" and adm!n!s"ra"!on. Oracle 4B. De&eloper !s a 'ree,
"h!c(?cl!en" graph!cal "ool. Mou can use !" "o e/ecu"e 4B. s"a"emen"s, &!e+ me"ada"a, e/ecu"e
and debug P.<4B. s"a"emen"s, and run some 4B.SPlus commands Cl!(e L-74B5I-F. 4B.
De&eloper !ncludes a da"abase modeler, and a module "o ass!s" m!gra"!on "o Oracle Da"abase.
4B. De&eloper can connec" "o Oracle da"abases 'rom &ers!on L.2.0.1 on+ards. Me"ada"a
and da"a 'rom se&eral "h!rd par" da"abases, !nclud!ng M4B. Da"abase are also &!e+able.
4B. De&eloper !s a&a!lable on .!nu/, 0!ndo+s and Mac O4 =.
Mou can do+nload 4B. De&eloper 'rom "he Oracle Technolog 7e"+or( a"
http://www.oracle.com/technetwork/deCeloper-tools/s"l-deCeloper. Mou can also
do+nload e/"ens!ons, documen"a"!on, and o"her resources 'rom "h!s s!"e. There !s also a
d!scuss!on 'orum 'or ou "o as( >ues"!ons o' o"her users, and g!&e 'eedbac( "o "he 4B.
De&eloper produc" "eam.
Creating a #ata$a!e Connection in S&' #e-eloper
0hen ou s"ar" 4B. De&eloper 'or "he '!rs" "!me "here are no da"abase connec"!ons
con'!gured, so "he '!rs" "h!ng ou need "o do !s crea"e one. The de'aul" 4B. De&eloper screen
!s sho+n !n 2!gure II.
*-
(igure 66' Oracle SEF Developer login screen"
.racle #;L De$eloper
To crea"e a da"abase connec"!on "o "he local Oracle Da"abase 11g =; da"abase)
1. 4elec" Connections !n "he le'" pane, r!gh" cl!c( and selec" Ne/ Connection. Choose a
name "o assoc!a"e +!"h "he connec"!on. ;n"er "he log!n creden"!als 'or "he Oracle
Da"abase 11g =; +!"h "he username hr, and pass+ord ou crea"ed 'or "he HR user, "he
hos"name localhost, and "he 4:D ,-.
2. Cl!c( "he Test bu""on "o "es" "he connec"!on. % message !s d!splaed a" "he bo""om le'"
s!de o' "he d!alog "o "ell ou +he"her "he "es" connec"!on succeeded.
I. Cl!c( "he Connect bu""on "o sa&e "he connec"!on and connec" "o "he da"abase. 0hen ou
ha&e connec"ed "o a da"abase, ou can bro+se "hrough "he da"abase ob8ec"s d!splaed !n
"he le'" pane, and "he r!gh" pane sho+s "he con"en"s o' "he ob8ec". :n 2!gure IH, "he
;MP.OM;;4 "able !s d!splaed.
Editing #ata in S&' #e-eloper
Mou can &!e+ and ed!" da"a us!ng "he Da"a "ab 'or a "able de'!n!"!on. 4elec" "he Da"a "ab 'or
"he ;MP.OM;;4 "able "o d!spla "he records a&a!lable. Mou can add ro+s, upda"e da"a and
dele"e ro+s us!ng "he da"a gr!d. :' ou ma(e an changes, "he records are mar(ed +!"h an
*0
(igure 64' Oracle SEF Developer +ain screen"
(igure 65' Oracle SEF Developer -onnection
screen"
#;L With .racle Data5ase
as"er!s(. Throughou" 4B. De&eloper, "here are con"e/" sens!"!&e menus. 2!gure IO sho+s "he
cho!ce o' con"e/" menus a&a!lable !n "he da"a gr!d.
Creating a Ta$le in S&' #e-eloper
Mou can crea"e da"abase ob8ec"s such as "ables, &!e+s, !nde/es, and P.<4B. procedures us!ng
4B. De&eloper. To crea"e a da"abase ob8ec", r!gh" cl!c( on "he da"abase ob8ec" "pe ou +an"
"o crea"e, and 'ollo+ "he d!alogs. Mou can use "h!s me"hod "o crea"e an o' "he da"abase
ob8ec"s d!splaed !n "he le'" pane.
To crea"e a ne+ "able)
1. 4elec" Ta5les !n "he le'" pane, r!gh" cl!c( and selec" Ne/ Ta5le. The Crea"e Table d!alog
!s d!splaed. ;n"er "he column names, "pes and o"her parame"ers as re>u!red.
There !s an Ad$anced chec( bo/ "ha" +!ll g!&e more ad&anced op"!ons l!(e
cons"ra!n"s, !nde/es, 'ore!gn (es, and par"!"!ons.
*1
(igure 6?' Oracle SEF Developer -reate )able
screen"
(igure 69' Oracle SEF Developer Data Grid"
.racle #;L De$eloper
2. Cl!c( .? "o crea"e "he "able. The ne+ "able +ytable !s no+ l!s"ed !n "he le'" pane.
Cl!c( on "he "abs d!splaed !n "he r!gh" pane "o see "he op"!ons a&a!lable on "he "able, such as
"he Da"a "ab, +h!ch enables ou "o add, dele"e, mod!', sor", and '!l"er ro+s !n "he "able.
Eecuting a S&' &uer6 in S&' #e-eloper
The 4B. 0or(shee" componen" !ncluded !n 4B. De&eloper can be used "o e/ecu"e 4B. and
P.<4B. s"a"emen"s. 4ome 4B.SPlus commands can also be e/ecu"ed. To e/ecu"e a 4B.
s"a"emen" !n 4B. De&eloper)
1. 4elec" "he myhr "ab !n "he r!gh" hand pane. Th!s !s "he connec"!on crea"ed earl!er !n
-reating a Database -onnection in SEF Developer. The 4B. 0or(shee" componen" !s
d!splaed, and sho+s an area "o en"er s"a"emen"s, and a se" o' "abs belo+ "ha" 'or 'ur"her
op"!ons. :' "he "ab !s no" a&a!lable, selec" "he menu Tools R#;L Worksheet. Mou are
promp"ed 'or "he da"abase connec"!on name.
*2
(igure 6/' Oracle SEF Developer screen
sho,ing the ne, table, !>)AIFE"
(igure 68' Oracle SEF Developer screen
sho,ing the SEF Wor1sheet"
#;L With .racle Data5ase
2. ;n"er "he 'ollo+!ng "+o s"a"emen"s !n "he 4B. 0or(shee")
descri/e emplo#ees
select J 'rom emplo#ees!
Cl!c( "he Run #cript !con C"he second 'rom "he le'" !n "he r!gh" hand paneF, or press
8+. -o"h "he l!nes o' "h!s scr!p" are run and "he ou"pu" !s d!splaed !n "abs belo+. Mou
can &!e+ "he ou"pu" o' "he 7-K-4: s"a"emen" !n "he Results "ab, us!ng 82, and "he
ou"pu" o' "he +hole scr!p" C!nclud!ng "he L-74B5I- and 7-K-4: s"a"emen"sF !n "he
#cript .utput "ab, b us!ng 8+. The ou"pu" !n "he 4cr!p" Ou"pu" +!ndo+ !s s!m!lar "o
4B.SPlus ou"pu".
I. :' ou +an" "o e/ecu"e a s!ngle l!ne o' "he "+o?l!ne bloc(, selec" "he l!ne ou +an" "o
e/ecu"e and cl!c( on "he 4%ecute #tatement !con C"he '!rs" 'rom "he le'" !n "he r!gh"
hand paneF, or press 82. :n "h!s case, "he 7-K-4: s"a"emen" Csecond l!neF !s selec"ed, and
"he resul"s are sho+n !n "he Resul"s "ab.
+3
(igure 5A' Oracle SEF Developer screen
sho,ing SEF Wor1sheet ,ith output"
(igure 5&' Oracle SEF Developer screen
sho,ing SEF Wor1sheet ,ith output"
.racle #;L De$eloper
Editing? Co1piling and :unning P'2S&' in S&' #e-eloper
Mou can use 4B. De&eloper "o bro+se, crea"e, ed!", comp!le, run, and debug P.<4B..
1. :n "he Connections pane, r!gh" cl!c( "he !rocedures node 'or our connec"!on and
selec" Ne/ !rocedure 'rom "he con"e/" menu. %dd "he name %DDND;PT and cl!c( .?.
2. The P.<4B. ;d!"or 'or %DDND;PT !s opened. Change "he "e/" so "ha" "he code !s as 'ollo+s)
create or replace procedure add$dept
%name in departments.department$nameFt#pe+
loc in departments.location$idFt#pe& is
/egin
insert into departments%department$id+ department$name+ location$id&
Calues%departments$se".ne.tCal+ name+ loc&!
end add$dept!
I. Comp!le "he code b selec"!ng "he comp!le !con !n "he "oolbar. :' "here are errors, "he +!ll
appear !n a Message?.og +!ndo+ belo+ "he code.
J. Run "he procedure. The green arro+ !con runs "he code.
+&
(igure 52' SEF Developer ne, procedure dialog"
(igure 56' SEF Developer PF;SEF -ode Editor"
#;L With .racle Data5ase
H. 4B. De&eloper pro&!des a d!alog +!"h an anonmous bloc( "o help "es" and run our code.
2!nd and replace "he 7U.. &alues +!"h &alues o' our o+n, 'or e/ample, ATra!n!ngA and
1$00.
Cl!c( .? "o run "he procedure. %'"er+ard bro+se "he Depar"men"s "able and go "o "he
Da"a "ab "o see "he resul"s added.
:unning :eport! in S&' #e-eloper
There are a number o' repor"s !ncluded +!"h 4B. De&eloper "ha" ma be use'ul "o ou, 'or
e/ample, ge""!ng l!s"s o' all users !n a da"abase, all "he "ables o+ned b a user, or all "he
&!e+s a&a!lable !n "he da"a d!c"!onar.
Mou can also crea"e our o+n repor"s Cus!ng 4B. and P.<4B.F, and !nclude "hem !n 4B.
De&eloper.
+(
(igure 55' SEF Developer :un PF;SEF dialog"
.racle #;L De$eloper
To d!spla "he &ers!on numbers o' "he da"abase componen"s us!ng one o' "he suppl!ed
repor"s)
1. 4elec" "he Reports "ab !n "he le'" hand pane. 7a&!ga"e do+n "o Reports R Data
Dictionary Reports R A5out 7our Data5ase R @ersion >anner. %'"er con'!rm!ng "he
connec"!on "o use, "he repor" !s run and "he resul"s are d!splaed !n "he r!gh" hand pane.
2. Cl!c( "he Run Report in #;L Worksheet !con Cne/" "o ReAreshF. The source code !s
+r!""en "o "he 4B. 0or(shee", +here ou could ed!" !" and crea"e a ne+ repor", !' ou
+!shed.
Creating :eport! in S&' #e-eloper
To crea"e our o+n repor", selec" Bser DeAined Reports !n "he Reports pane, and r!gh"
cl!c(. :" !s good prac"!ce "o crea"e 'older 'or our repor"s, "o ca"egor!1e "hem.
+)
(igure 54' Oracle SEF Developer screen
sho,ing output *ro+ a report"
(igure 59' Oracle SEF Developer screen
sho,ing the source code o* a report"
#;L With .racle Data5ase
I. R!gh" cl!c( "he Bser DeAined Reports node and selec" Ne/ 8older. Comple"e "he
de"a!ls !n "he d!alog. Mou can use "h!s 'older "o !mpor" or add ne+ repor"s.
J. 4elec" "he 'older ou crea"ed and r!gh" cl!c( "o selec" Ne/ Report.
H. 3!&e "he repor" a name and descr!p"!on and en"er "he 'ollo+!ng 4B. "e/".
select last$name+
department$name+
cit#
'rom departments d+
locations l+
emplo#ees e
where %d.location$id * l.location$id&
and %d.manager$id * e.emplo#ee$id&
and %e.department$id * d.department$id&
order /# cit#+ department$name
+*
(igure 5?' SEF Developer #ser De*ined :eports
.racle #;L De$eloper
O. 7o"!ce "ha" "he de'aul" s"le !s table. Mou can "es" "he repor" "o ensure our 4B. !s correc",
+!"hou" lea&!ng "he d!alog. Cl!c( "he Test Report bu""on abo&e "he 4B..
P. Cl!c( Apply "o sa&e and close.
$. To run "he repor", selec" !" !n "he Repor"s 7a&!ga"or. Mou are promp"ed 'or a da"abase
connec"!on.
Mou can crea"e "abular repor"s, char"s, dr!ll do+n repor"s and mas"er<de"a!l repor"s. 2or all
repor"s, suppl!ed and user de'!ned, ou can e/por", !mpor" and share our repor"s.
++
(igure 5/' SEF Developer -reate :eport Dialog
(igure 58' SEF Developer #ser De*ined,
)abular :eport
#;L With .racle Data5ase
+-
CH,PTE: (
NET)E,NS I#E 9O: PHP
The 7e"-eans :D; C:n"egra"ed De&eloper ;n&!ronmen"F 'or PHP pro&!des "ools "o ma(e PHP
de&elopmen" produc"!&e and e''ec"!&e.
The core o' 7e"-eans PHP suppor" !s "he PHP ;d!"or, +h!ch !ncludes code comple"!on and
o"her programm!ng a!ds. The :D; !s also !n"egra"ed +!"h man "h!rd par" componen"s
!nclud!ng PHP 'rame+or(s, "he =debug debugger, "he PHPUn!" "es"er, *en(!ns con"!nuous
!n"egra"!on, and "he %p!3en documen"a"!on genera"or.
Th!s chap"er g!&es a h!gh le&el o&er&!e+ o' 7e"-eans. 7e"-eans !s e/"remel popular and
"here !s a large amoun" o' documen"a"!on and !n'orma"!on alread a&a!lable. Re'er "o "hese
e/cellen" resources, no"abl "hose a" http://net/eans.org/k//trails/php.html.
Net)ean! In!tallation
To !ns"all 7e"-eans :D;, go "o http://net/eans.org/downloads. Do+nload "he 7e"-eans PHP
bundle 'or our opera"!ng ss"em or ge" "he pla"'orm?!ndependen" &ers!on. 2ollo+ "he
2etIeans .DE ?"2 .nstallation .nstructions a"
http://net/eans.org/communit#/releases/U2/install.html.
:' ou need add!"!onal language suppor", ou can !ns"all !nd!&!dual plug!ns 'rom !ns!de "he
:D;.
Net)ean! Editor 9eature!
4ome o' "he commonl used 7e"-eans ed!"or 'ea"ures are men"!oned belo+. 2or more
!n'orma"!on and "o d!sco&er o"her ed!"or 'ea"ures, see "he 2etIeans .DE *or PHP Editor' Irie*
Overvie, http://net/eans.org/k//docs/php/editorguide.html.
#ynta% Highlighting and Code Na$igation
Comprehens!&e h!ghl!gh"!ng !s a&a!lable 'or PHP and o"her languages, !nclud!ng HTM., *4O7
and =M.)
+0
2!gure H0) 7e"-eans :D; sn"a/ h!ghl!gh"!ng
Net>eans 'D4 Aor !H!
7e"-eans also g!&es parame"er h!n"s, !den"!'!es sn"a/ errors and pro&!des error descr!p"!ons.
Code completion and parameter hints
4"rong code comple"!on 'unc"!onal!" !s pro&!ded.
O"her :D; 'ea"ures !nclude code 'old!ng, smar" !nden"!ng, 'orma""!ng, and brac(e" comple"!on.
Na$igator
The 7a&!ga"or allo+s eas !n"erpre"a"!on o' code, and allo+s d!rec" access "o 'unc"!on and
me"hod de'!n!"!ons.
Mou can also na&!ga"e d!rec"l 'rom an occurrence o' a &ar!able "o "he l!ne +here "he &ar!able
!s declared or !n!"!al!1ed.
Rename re'ac"or!ng and !ns"an" renam!ng allo+s sa'e renam!ng o' all occurrences o' an
elemen" across mul"!ple '!les, and has a pre&!e+ 'ea"ure.
+1
2!gure H1) 7e"-eans code comple"!on
(igure 42' 2etIeans 2avigator
Net>eans 4ditor 8eatures
Third !arty Component integration
7e"-eans :D; can u"!l!1e man s"andard PHP de&elopmen" "ools, !nclud!ng)
%p!3en documen"a"!on genera"or suppor"
Code genera"ors "o genera"e class ge""ers, se""ers, and "o o&err!de !mplemen"ed
me"hods
PHPUn!" and 4elen!um au"oma"ed "es"!ng "ools
4m'on2, 9end 2rame+or( and Doc"r!ne2 2rame+or(s
#e-elop1ent Proce!!e! in Net)ean!
The 7e"-eans :D; suppor"s bo"h comple/ pro8ec"s and s!ngle '!le de&elopmen". The :D; has
suppor" 'or 4ub&ers!on, Mercur!al, and 3!" &ers!on!ng ss"ems. Mou can also add C,4 suppor"
as a plug!n.
PHP '!les can be run as scr!p"s, run +!"h PHPAs bu!l"?!n +ebser&er or deploed remo"el.
7e"-eans suppor"s 2TP<42TP 'or remo"e '!les access.
OCI. Support in Net)ean!
7e"-eans :D; 'or PHP au"oma"!call recogn!1es OC:$ 'or code comple"!on and pro&!des
documen"a"!on.
:' "he local PHP b!nar reg!s"ered +!"h 7e"-eans has "he OC:$ e/"ens!on "hen scr!p"s us!ng
OC:$ +!ll e/ecu"e !n command l!ne or +!"h "he local PHP de&elopmen" +eb ser&er. :' ou are
deplo!ng "o a remo"e hos", "hen OC:$ needs "o be !ns"alled "here.
Oracle #ata$a!e Support in Net)ean!
The 7e"-eans :D; can connec" "o Oracle Da"abase, &!e+ da"a and me"a?da"a, and also
e/ecu"e 4B. commands.
To connec" "o Oracle, open "he Services +!ndo+ and reg!s"er our da"abase b r!gh"?
+2
(igure 46' 2etIeans code co+pletion
Net>eans 'D4 Aor !H!
cl!c(!ng "he Databases node and selec"!ng 2e, -onnection. Mou ma need "o add "he pa"h
"o our da"abase dr!&er as +ell. 2or !ns"ruc"!ons see -onnecting to Oracle Database *ro+
2etIeans .DE, http://net/eans.org/k//docs/ide/oracle-d/.html.
7e"-eans :D; pro&!des a "ree &!e+ o' da"abase con"en"s and an 4B. ed!"or.
7o"e "ha" ou do no" need "o crea"e a connec"!on "o our Oracle da"abase 'rom "he :D;. Mou
can use ano"her "ool "o +or( +!"h 4B. and Oracle da"abase ob8ec"s, and use "he 7e"-eans
:D; onl 'or ed!"!ng PHP, !' "h!s !s our pre'erred de&elopmen" process.
Net>eans .C'1 Tutorial
2or a 'ull e/ample o' PHP de&elopmen" !n 7e"-eans us!ng Oracle Da"abase and "he OC:$
e/"ens!on, see -reating a Database3Driven Application ,ith 2etIeans .DE PHP Editor
http://net/eans.org/k//docs/php/wish-list-tutorial-main-page.html.
Daily and De$elopment Net>eans >uilds
To "r ou" upcom!ng 'ea"ures be!ng added "o 7e"-eans, ou can !ns"all da!l de&elopmen"
bu!lds o' "he :D;. -o"h publ!c release and de&elopmen" bu!lds can be !ns"alled 'rom
http://net/eans.org/downloads/inde..html. .oo( 'or "he Develop+ent l!n(.
Getting Help *or Net)ean!
7e"-eans :D; 'or PHP has grea" sources o' !n'orma"!on)
>uiltin help. :ns!de "he :D;, cl!c( 21 or na&!ga"e "o Help R Help -ontents and a help
+!ndo+ opens. Mou can also cl!c( "he Help bu""on !n a d!alog "o see a descr!p"!on o' "he
op"!ons !n "ha" d!alog. Con"e/"?sens!"!&e help !s also a&a!lable 'or "he ;d!"or, Pro8ec"s,
-3
)ext &' 2etIean Database connection navigator and Oracle SEF area
,etting Help Aor Net>eans
4er&!ces, 2!les, and o"her +!ndo+s. 4elec" an !"em !n a +!ndo+ and press 21 "o see "he
help 'or "ha" +!ndo+.
We55ased tutorials. 4ee "he PHP .earn!ng Tra!l,
http://net/eans.org/k//trails/php.html.
Net>eans !H! Bsers 8orum and :ailing List. % 'orum 'or PHP users !s a&a!lable a"
http://'orums.net/eans.org/php-users.html. Th!s 'orum !s m!rrored as a ma!l!ng
l!s". 4ubscr!be "o "he ma!l!ng l!s" or "he 'orum a"
http://net/eans.org/communit#/lists/inde..html.
Net>eans !H! >log. The 7e"-eans PHP de&elopmen" "eam (eeps a blog +here ou
can learn abou" 'u"ure plans and "he la"es" 7e"-eans 'ea"ures. Commen"s +elcomeT
4ee http:///logs.oracle.com/net/eansphp/.
-&
Net>eans 'D4 Aor !H!
-(
CH,PTE: +
INST,''ING ,P,CHE HTTP SE:<E:
Th!s chap"er g!&es ou "he s"eps needed "o !ns"all and con'!gure "he %pache HTTP 4er&er 'or
use +!"h PHP. :' ou alread ha&e %pache !ns"alled, 'or e/ample 'rom a .!nu/ so'"+are
repos!"or, ou can s(!p "h!s chap"er.
4"eps are g!&en 'or Oracle .!nu/ and 0!ndo+s. The procedure "o !ns"all on o"her .!nu/
pla"'orms !s "he same as 'or Oracle .!nu/.
%d8us" "he '!le names and commands belo+ !' "he &ers!on o' %pache ou ha&e d!''ers 'rom
"he !ns"ruc"!ons.
,pache HTTP Ser-er Pac=age! on Oracle 'inu
%pache !s a&a!lable !n "he httpd pac(age on Oracle .!nu/. :' ou +an" "o rebu!ld PHP +!ll also
need "he httpd3devel pac(age !ns"alled)
Q #um install httpd httpd-deCel
Use "he service command "o con"rol %pache)
Q serCice httpd start
Q serCice httpd stop
7o"e "ha" service passes onl a l!m!"ed range o' en&!ronmen" &ar!ables 'rom our curren" shell
"o %pache.
%l"erna"!&el ou can con"rol %pache +!"h)
Q /usr/s/in/apachectl start
Q /usr/s/in/apachectl stop
)uilding ,pache HTTP Ser-er on 'inu
The de'aul" &ers!on o' %pache on our .!nu/ d!s"r!bu"!on ma no" be "he mos" recen"
a&a!lable. To manuall !ns"all %pache HTTP 4er&er 'or use +!"h PHP on Oracle .!nu/)
1. Do+nload "he %pache HTTP 4er&er 'rom http://httpd.apache.org/download.cgi. The
&ers!on used !n "h!s !ns"alla"!on e/ample !s httpd32"5"2"tar"b2.
2. Do+nload "he %pache Por"able Run"!me C%PRF and %PR u"!l!"!es 'rom
http://apr.apache.org/download.cgi. The '!les used !n "h!s !ns"alla"!on are apr3
&"5"9"tar"b2 and apr3util3&"5"&"tar"b2.
I. .og !n as "he root user and e/"rac" "he '!les)
Q tar -W.C' httpd-2.D.2.tar./X2
Q tar -W.C' apr-1.D.P.tar./X2
Q tar -W.C' apr-utl-1.D.1.tar./X2
:' ou do+nloaded "he "g g1!pped '!les, use "he -X 'lag !ns"ead o' "he -W 'lag.
-)
'nstalling Apache HTT! #er$er
J. Mo&e "he %PR d!rec"or!es !n"o "he +eb ser&er source, remo&!ng "he &ers!on su''!/)
Q mC apr-1.D.P httpd-2.D.2/srcli//apr
Q mC apr-util-1.D.1 httpd-2.D.2/srcli//apr-util
H. Con'!gure and bu!ld "he +eb ser&er)
Q cd httpd-2.D.2
Q ./con'igure V-pre'i.*/opt/apache V-with-included-apr 2
V-with-mpm*pre'ork --ena/le-mpms-shared
Q make
Q make install
0hen con'!gur!ng "he +eb ser&er, "he op"!ons !nd!ca"e "he de'aul" process!ng module !s
pre*or1, a mul"!?process mode +h!ch !s generall recommended because PHP "hread
sa'e" !snA" guaran"eed. Ho+e&er enabl!ng "he process!ng module as shared allo+s la"er
s+app!ng !' ou +an" "o "r a d!''eren" module. The 33pre*ix op"!on se"s +here %pache
HTTP 4er&er +!ll be !ns"alled dur!ng "he command +a1e install.
%'"er !ns"alla"!on, use "he apachectl scr!p" !n "he %pache bin d!rec"or "o s"ar" and s"op
%pache HTTP 4er&er)
Q /opt/apache//in/apachectl start
Q /opt/apache//in/apachectl stop
Con*iguring ,pache HTTP Ser-er on 'inu
The con'!gura"!on '!les 'or %pache are !n ;etc;httpd;con* 'or "he ss"em %pache, or
;opt;apache;con* !' ou d!d a manual !ns"all.
Setting the ,pache Ser-er Na1e
:' ou !ns"alled on a mach!ne +!"h a dnam!c :P address, ou m!gh" see a +arn!ng +hen
%pache s"ar"s) D-ould not reliably deter+ine the server%s *ully Duali*ied do+ain na+eE. Mou
can pre&en" "h!s +arn!ng b ed!"!ng httpd"con* !n "he con'!gura"!on d!rec"or and se""!ng)
7erCerMame localhost:80
Setting up an ,pache 0!er #irector6 on 'inu
Mou m!gh" l!(e "o se" up "he UserD!r d!rec"!&e so ou can run PHP scr!p"s 'rom our o+n
JHO!E;public=ht+l d!rec"or. O"her+!se ou +!ll need access "o "he documen" roo" d!rec"or,
;var;,,,;ht+l or ;opt;apache;htdocs. Ho+ ou enable user d!rec"or!es depends on "he
%pache &ers!on. Tp!call !" re>u!res "he userdir=+odule "o be loaded and UserD!r enabled.
Mour home and public=ht+l d!rec"or!es, and PHP or HTM. '!les +!ll also need read and<or
e/ecu"e perm!ss!ons 'or "he DotherE group.
0!"h "he httpd pac(age on Oracle .!nu/)
1. ;d!" ;etc;httpd;con*;httpd"con*
2. Change "he +od=userdir sec"!on "o)
<5'Nodule mod$userdir.c
-*
ConAiguring Apache HTT! #er$er on Linu%
RserLir pu/lic$html
</5'Nodule
I. 4e" 4;.!nu/ "o per+issive, o"her+!se '!les !n "he user d!rec"or +!ll no" be access!ble)
Q seten'orce permissiCe
%l"erna"!&el ;etc;selinux;con*ig can be upda"ed.
J. Res"ar" "he +eb ser&er)
Q serCice httpd restart
H. .og!n as our normal, non?pr!&!leged user and ma(e a public=ht+l sub?d!rec"or)
) mkdir )>3N-/pu/lic$html
) chmod U55 )>3N- )>3N-/pu/lic$html
To crea"e a user d!rec"or +!"h a manuall !ns"alled %pache !n ;opt;apache)
1. ;d!" ;opt;apache;con*;httpd"con*
2. Uncommen" "he l!ne)
KoadNodule userdir$module modules/mod$userdir.so
I. Uncommen" "he l!ne)
5nclude con'/e.tra/httpd-userdir.con'
J. Res"ar" "he +eb ser&er)
Q /opt/apache//in/apachectl restart
H. .og!n as our normal, non?pr!&!leged user and ma(e a public=ht+l sub?d!rec"or)
) mkdir )>3N-/pu/lic$html
) chmod U55 )>3N- )>3N-/pu/lic$html
En-iron1ent <aria$le! *or PHP in ,pache on Oracle 'inu
0hen ou use %pache HTTP 4er&er +!"h PHP OC:$, ou mus" se" some Oracle en&!ronmen"
&ar!ables be'ore s"ar"!ng "he +eb ser&er. 0h!ch &ar!ables ou need "o se" are de"erm!ned b
ho+ PHP !s !ns"alled, ho+ ou connec" "o "he da"abase, and +ha" op"!onal se""!ngs are
des!red.
7e&er se" Oracle en&!ronmen" &ar!ables !n PHP scr!p"s +!"h putenC%&. The +eb ser&er ma
load Oracle l!brar!es and !n!"!al!1e Oracle da"a s"ruc"ures be'ore runn!ng our scr!p". Us!ng
putenC%& causes hard "o "rac( errors as "he beha&!or !s no" cons!s"en" 'or all &ar!ables, +eb
ser&ers, opera"!ng ss"ems, or OC:$ 'unc"!ons. ,ar!ables should be se" pr!or "o %pache
s"ar"!ng.
-+
'nstalling Apache HTT! #er$er
To se" en&!ronmen" &ar!ables 'or use b "he Oracle .!nu/ pac(aged %pache, add "hem "o
;etc;syscon*ig;httpd" These &ar!ables +!ll be passed "o %pache e&en !' ou con"rol !" +!"h "he
service command. 2or Apache in ;opt;apache se" "hem !n "he ;opt;apache;bin;envvars scr!p""
2or e/ample, !' ou !ns"all PHP us!ng Oracle Da"abase 11g =;, se")
e.port 3B64K-$>3N-*/u01/app/oracle/product/11.2.0/.e
e.port KL$K5IB6B;$E6:>*)KL$K5IB6B;$E6:>:)3B64K-$>3N-/li/
2or more !n'orma"!on abou" se""!ng "he en&!ronmen" see Setting the Oracle Environ+ent on
Finux !n "he chap"er .nstalling and -on*iguring PHP.
Per1i!!ion! *or PHP OCI. in ,pache on Oracle 'inu
0hen ou !ns"all PHP OC:$ !n %pache Csee "he ne/" chap"erF, ou +!ll need "o ma(e sure "ha"
"he %pache processes can access "he Oracle l!brar!es, messages and global!1a"!on da"a.
0!"hou" "h!s, %pache ma 'a!l "o s"ar" and ou +!ll see errors !n "he %pache log '!les. 0!"h
Oracle 11g or +!"h Oracle :ns"an" Cl!en", g!&!ng access can be as s!mple as ma(!ng "he "op
le&el d!rec"or readable.
:' ou are us!ng a non =; ed!"!on o' Oracle Da"abase 10g Release 10.2, more comple/
perm!ss!on changes are needed. 0!"h Oracle Da"abase 10g Release 10.2.0.2 on+ards, "here !s
a scr!p" loca"ed !n JO:A-FE=HO!E;install;changePer+"sh "o change perm!ss!ons.
In!talling ,pache HTTP Ser-er on Windo;!
The 'ollo+!ng procedure descr!bes ho+ "o !ns"all "he %pache HTTP 4er&er on 0!ndo+s. The
common recommenda"!on !s "o use PHP !n a non?"hreaded mode &!a "he 2as"C3: module.
O. Do+nload %pache httpd32"2"223,in623x/93no=ssl"+si 'rom
http://httpd.apache.org/download.cgi
P. Double cl!c( "he M4: "o s"ar" "he !ns"alla"!on +!1ard. :ns"all @'or %ll Users, on Por" $0@
because "he Donl 'or "he Curren" UserE al"erna"!&e +!ll clash +!"h Oracle Da"abase 11g
=;As de'aul" por" $0$0. Do a "p!cal !ns"all !n"o "he de'aul" des"!na"!on 'older, +h!ch !s
-'KProgra+ (iles Lx/9MKApache So*t,are (oundationKApache2"2 on 0!ndo+s P, or
-'KProgra+ (ilesKApache So*t,are (oundationKApache2"2 on 0!ndo+s =P.
$. Do+nload "he %pache +od=*cgid 2as"C3: +od=*cgid32"6"93,in623x/9"ip 'rom)
http://httpd.apache.org/download.cgiQmod$'cgid
Mou ma need "o na&!ga"e "o "he do+nload d!rec"or l!s"!ng
http://www.apache.org/dist/httpd//inaries/win@2/ !' "here !s no d!rec" l!n( 'or
"he 0!ndo+s b!nar!es on "h!s page.
L. Un1!p +od=*cgid "o "he !ns"alled %pache 2.2 d!rec"or. The -'KProgra+ (ilesKApache
So*t,are (oundationKApache2"2K+odules d!rec"or should no+ ha&e +od=*cgid"so and
+od=*cgid"pdb '!les.
10. ;d!" -'KProgra+ (ilesKApache So*t,are (oundationKApache2"2Kcon*Khttpd"con* and add)
KoadNodule 'cgid$module modules/mod$'cgid.so
11. :n httpd"con* loca"e "he LDirectoryM sec"!on 'or htdocs and add Exec-G. "o Options)
<Lirector# "4:/Erogram Ailes/6pache 7o'tware Aoundation/6pache2.2/htdocs"
--
'nstalling Apache HTT! #er$er on Windo/s
...
3ptions 5nde.es Aollow7#mKinks ExecCGI
...
</Lirector#
Mou can use "he 4"ar" menu op"!on "o s"ar" %pache. Th!s opens a console +!ndo+
sho+!ng an error messages. ;rror messages ma also be +r!""en "o -'KProgra+
(ilesKApache So*t,are (oundationKApache2"2KlogsKerror"log.
Mou can also use "he Apache!onitor u"!l!" "o s"ar" %pache. :' ou chose "o !ns"all
%pache as a ser&!ce 'or all users, !" +!ll appear as an !con !n our 4s"em Tra.
:' ou ha&e errors, double chec( our httpd"con* '!le
Starting and Stopping ,pache HTTP Ser-er on Windo;!
Mour ss"em "ra has an %pache Mon!"or con"rol "ha" ma(es !" eas "o s"op and res"ar" "he
%pache HTTP 4er&er +hen needed. %l"erna"!&el, use "he %pache op"!ons added "o our
0!ndo+s 4"ar" menu.
Te!ting ,pache HTTP Ser-er
Mou should no+ "es" "ha" %pache HTTP 4er&er has been !ns"alled properl b s"ar"!ng !" on
our mach!ne and open!ng our +eb bro+ser "o http';;localhost; or http';;&2?"A"A"&;. Th!s +!ll
d!spla an %pache banner page.
:' "here !s no ou"pu" or "here are errors +hen s"ar"!ng %pache, re&!e+ "he error log +h!ch
ma be !n ;var;log;htpd;error=log C'or "he Oracle .!nu/ httpd pac(ageF,
;opt;apache;logs;error=log C'or a cus"om !ns"all on .!nu/F, or !n -'KProgra+ (iles
Lx/9MKApache So*t,are (oundationKApache2"2KlogsKerror=log Non 0!ndo+s PF.
-0
'nstalling Apache HTT! #er$er
-1
CH,PTE: .
INST,''ING ,N# CON9IG0:ING PHP
Th!s chap"er d!scusses "he ma!n +as o' !ns"all!ng PHP on .!nu/ and 0!ndo+s. The ne/"
chap"er d!scusses !ns"alla"!on on 4olar!s. :ns"alla"!on on o"her U7:=?l!(e ss"ems !s s!m!lar "o
"he !ns"ruc"!ons 'or .!nu/.
The %pache HTTP 4er&er generall needs "o be !ns"alled be'ore !ns"all!ng PHP, and a
da"abase should be access!ble !n our ne"+or(.
In!talling PHP on 'inu
There are "hree ma!n +as "o !ns"all PHP on .!nu/)
.!nu/ d!s"r!bu"!on pac(ages
9end 4er&er pac(ages
PHP source code
Depend!ng on "he PHP !ns"alla"!on, "he OC:$ e/"ens!on 'or Oracle Da"abase access !s alread
!ns"alled, or can be !ns"alled separa"el. % common deplomen" me"hod +hen OC:$ !s
comp!led separa"el !s "o !ns"all !" as a shared l!brar. Ho+e&er OC:$ can be s"a"!call
comp!led !n"o PHP +hen bu!ld!ng all o' PHP 'rom source code. To bu!ld "he e/"ens!on ou need
"o ha&e Oracle source header '!les a&a!lable. %" run"!me, OC:$ needs access "o Oracle
l!brar!es. The headers and l!brar!es can be used 'rom an Oracle da"abase home or 'rom Oracle
:ns"an" Cl!en".
The !ns"alla"!on scenar!os are co&ered belo+.
In!talling 'inu PHP Pac=age!
Mos" .!nu/ &ar!an"s suppl PHP pac(ages "ha" ma(e !ns"alla"!on eas. The ca&ea" !s "ha" .!nu/
d!s"r!bu"!on ma!n"a!ners generall pre'er (eep!ng usersA appl!ca"!ons s"able, so o'"en "he
pac(ages lag beh!nd "he mos" recen" PHP source code. Us!ng older &ers!ons o' PHP !s no"
recommended b "he PHP commun!".
:n Oracle .!nu/ H "he php RPM pac(ages are PHP &ers!on H.1. Oracle .!nu/ H.O !n"roduced
an add!"!onal se" o' php46 pac(ages 'or PHP H.I. :n Oracle .!nu/ O "he php pac(ages con"a!n
PHP H.I. 0hen ne+er &ers!ons o' PHP become s"able bu" are no" a&a!lable as pac(ages, ou
should comp!le our o+n b!nar!es, !' poss!ble.
The bas!c PHP !ns"alla"!on 'rom Oracle .!nu/ O d!s"r!bu"!on RPMs !s descr!bed here.
1. :ns"all "he PHP command l!ne and %pache modules)
Q #um install php php-cli
Chec( our local pac(age repos!"or 'or o"her e/"ens!on pac(ages "ha" ou ma +an".
:ns"all "he php3devel RPM pac(age !' ou plan "o !ns"all PHP e/"ens!ons "ha" are onl
a&a!lable !n source code 'rom PHPAs P;C. repos!"or or else+here.
2. Once PHP !s !ns"alled, ed!" ;etc;php"ini and se" "he date"ti+eone d!rec"!&e "o our
"!me1one, 'or e/ample)
date.timeXone * 6merica/Kos$6ngeles
-2
'nstalling and ConAiguring !H!
4ee php.net/manual/timeXones.php 'or "he a&a!lable &alues.
2or "es"!ng !" !s help'ul "o ha&e "he d!rec"!&e)
displa#$errors * 3n
Th!s le"s ou see an problems !n our code +!"hou" ha&!ng "o re&!e+ "he +eb ser&er
logs. Ma(e sure ou change "h!s con'!gura"!on op"!on "o O'' be'ore releas!ng our
appl!ca"!on "o users because !" !s a secur!" r!s( +hen errors Dlea(E !n'orma"!on abou"
our con'!gura"!on.
I. %pache should no+ be res"ar"ed)
Q serCice httpd restart
7o"e "ha" service clears "he en&!ronmen", so !' ou need "o pass !n Oracle
en&!ronmen" &ar!ables 'rom our shell, res"ar" %pache e/pl!c!"l +!"h)
Q /etc/init.d/httpd restart
3enerall !" !s be""er no" "o rel on "he &ar!ables be!ng se" correc"l !n "he !n&o(!ng
en&!ronmen". :ns"ead, se" "hem !n %pache con'!gura"!on '!les such as
;etc;syscon*;httpd. Th!s !s d!scussed la"er !n "he chap"er.

The bundled pac(ages do no" ha&e "he PHP OC:$ e/"ens!on. Use P;C. "o !ns"all !", as
descr!bed belo+. %l"erna"!&el, Oracle .!nu/ users +!"h an Unbrea(able .!nu/ 7e"+or( CU.7F
subscr!p"!on can !ns"all an OC:$ RPM 'rom https://linu..oracle.com.
In!talling @end Ser-er Pac=age! on 'inu
9end 4er&er !s a pre?bu!l" release o' PHP 'rom 9end "ha" comes +!"h "he OC:$ e/"ens!on and
PDONOC: dr!&er. :" also comes read +!"h "he Oracle :ns"an" Cl!en" l!brar!es. 9end 4er&er !s
a&a!lable 'or se&eral pla"'orms, !nclud!ng Oracle .!nu/. :" !ncludes a bro+ser?based
managemen" console 'or con'!gura"!on and ge""!ng upda"es.
9end 4er&er C; !s 'ree "o do+nload and use. % suppor"ed ed!"!on +!"h en"erpr!se 'ea"ures
such as ad&anced cach!ng and mon!"or!ng !s also a&a!lable.
There are se&eral +as "o use 9end 4er&er on Oracle .!nu/)
1. Us!ng an Oracle ,!r"ual-o/ ,M) % >u!c( e&alua"!on, pre?bu!l" de&eloper ,M +!"h 9end
4er&er and Oracle Da"abase 11g =; can be do+nloaded 'rom 9end.
2. Us!ng OracleAs Unbrea(able .!nu/ 7e"+or() U.7 subscr!bers can !ns"all 9end 4er&er b
subscr!b!ng "o "he @;n"erpr!se .!nu/ H %dd ons C!I$OF@ or @;n"erpr!se .!nu/ H %dd ons
C/$ONOJF@ channels and !ns"all!ng "he 1end?ser&er?repo RPM. ;>u!&alen" channels 'or
Oracle .!nu/ O e/!s". 9end 4er&er can "hen be !ns"alled)
Q up2date Xend-serCer-repo
Q #um install Xend-serCer-php-5.@
I. Us!ng OracleAs 'ree, publ!c Mum Repos!"or) 2ollo+ "he s"eps "o enable "he Mum repos!"or
g!&en !n http://pu/lic-#um.oracle.com. Ma(e sure "o enable one o' "he base channels,
'or e/ample @elHNuHNbase@ !' ou are us!ng Oracle .!nu/ H upda"e H. %lso !n our ne+
repos!"or con'!gura"!on '!le, enable "he @%ddons@ channel. 2or e/ample)
Q Ci /etc/#um.repos.d/pu/lic-#um-el5.repo
03
'nstalling !H! on Linu%
:n "he sec"!on +!"h "he head!ng UelHNuHNbaseV enable "he channel)
ena/led*1
:n "he sec"!on +!"h "he head!ng UelHNaddonsV enable "he channel)
ena/led*1
4a&e "he '!le and "hen !ns"all 9end 4er&er +!"h)
Q #um install Xend-serCer-repo
Q #um install Xend-serCer-php-5.@
4ee "he 9end 4er&er page 'or up "o da"e !n'orma"!on on 9end 4er&er and Oracle)
http://www.oracle.com/technetwork/topics/php/Xend-serCer-09P@1D.html
Co1piling PHP a! an ,pache 5odule on 'inu
Comp!l!ng PHP 'rom source code allo+s "he pac(ages and bu!ld op"!ons "o be e/pl!c!"l
cus"om!1ed. 0hen bu!ld!ng PHP 'rom source code, !" !s common "o bu!ld PHP '!rs" +!"hou"
mos" e/"ens!ons, and "hen la"er add "he e/"ens!ons as shared l!brar!es. Th!s allo+s !nd!&!dual
e/"ens!ons "o be upgraded or pa"ched +!"hou" !mpac"!ng "he en"!re PHP !n'ras"ruc"ure. 4ome
people go so 'ar as "o con'!gure PHP us!ng ?3disable3all and e/pl!c!"l enable onl "he
absolu"el smalles" se" o' e/"ens!ons needed.
The bas!c s"eps 'or bu!ld!ng PHP as an %pache module are)
1. .og!n as "he root user and shu"do+n %pache)
Q serCice httpd stop
On Ubun"u use service apache2 stop. On o"her .!nu/ &ar!an"s ou ma need "o use
;etc;init"d;httpd stop or run apachectl stop.
2. :ns"all "he %pache de&elopmen" "ools "o ge" "he apxs u"!l!")
Q #um install httpd-deCel
I. Do+nload PHP 'rom http://www.php.net/downloads.php.
J. ;/"rac" "he PHP source code, 'or e/ample +!"h PHP H.J.J)
Q tar -W.' php-5.D.D.tar./X2
Q cd php-5.D.D
:' ou do+nloaded "he b!gger "tar"g '!le, e/"rac" !" +!"h tar -X.' php-5.D.D.tar.gX.
H. Con'!gure PHP +!"h an des!red op"!ons, 'or e/ample)
Q ./con'igure --pre'i.*/opt/php --with-ap.s2*/usr/s/in/ap.s
The e/ample abo&e !ns"alls PHP !n ;opt;php and bu!lds PHPAs %pache D4%P:E 'or "he
pac(aged httpd ser&er. Command l!ne PHP +!ll also be bu!l".
:' ou !ns"alled our o+n %pache, use "he appropr!a"e pa"h "o "he %pache e/"ens!on
"ool, 'or e/ample ;opt;apache;bin;apxs. :' ou ha&e %pache 1.I !ns"ead o' %pache 2,
0&
'nstalling and ConAiguring !H!
change "he 33,ith3apxs2 op"!on "o 33,ith3apxs. O"her des!red op"!ons and e/"ens!ons
can be used !n "he con*igure command. To l!s" all "he op"!ons, use "he command)
Q ./con'igure V-help
Mou could bu!ld "he OC:$ e/"ens!on no+ b !nclud!ng "he 33,ith3oci/ op"!on as
descr!bed !n de"a!l la"er !n "h!s chap"er. %l"erna"!&el, ou can bu!ld OC:$ separa"el
+h!ch allo+s eas!er upgrades. Th!s !s recommended and !s also descr!bed !n "h!s
chap"er.
To bu!ld PHP +!"h a spec!al comp!ler or comp!ler op"!ons, se" an op"!ons be'ore
runn!ng con*igure. Ma(e sure "o also remo&e an con'!gura"!on cache. 2or e/ample)
Q e.port 44*//in/cc
Q e.port 4AK6Y7*HLLPD
Q rm -r' automDte.cache con'ig.cache
Q ./con'igure ...
PHP H.J re>u!res autocon* 2.HL or la"er. Pr!or "o PHP H.J, older &ers!ons o' "he
opera"!ng ss"em bu!ld "ools +ere needed. :' ou ha&e bo"h old and ne+ autocon*
pac(ages !ns"alled, PHP bu!lds can be 'orced "o use "he appropr!a"e &ers!on, 'or
e/ample +!"h)
Q e.port E>E$6R:343MA*autocon'-2.1@
Q e.port E>E$6R:3>-6L-B*autoheader-2.1@
O. Ma(e and !ns"all PHP)
Q make
Q make install
P. Cop one o' "he suppl!ed !n!"!al!1a"!on '!les php"ini3develop+ent or php"ini3production 'or
PHP. To '!nd "he des"!na"!on con'!gura"!on '!le d!rec"or, use "he 33ini op"!on "o command
l!ne PHP)
Q php --ini
4on'iguration Aile %php.ini& Eath: /opt/php/li/
Koaded 4on'iguration Aile: %none&
7can 'or additional .ini 'iles in: %none&
6dditional .ini 'iles parsed: %none&
Th!s sho+s "he pa"h !s ;opt;php;lib. Cop one o' "he "empla"e '!les "o php"ini !n "ha"
d!rec"or)
Q cp php.ini-deCelopment /opt/php/li//php.ini
$. ;d!" php"ini and se" "he date"ti+eone d!rec"!&e "o our "!me1one, 'or e/ample)
date.timeXone * 6merica/Kos$6ngeles
4ee http://php.net/manual/timeXones.php 'or "he a&a!lable &alues.
0(
'nstalling !H! on Linu%
2or "es"!ng !" !s help'ul "o ha&e displa#$errors*3n so ou see an problems !n our
code +!"hou" ha&!ng "o re&!e+ "he +eb ser&er logs. Ma(e sure ou change "h!s
con'!gura"!on op"!on "o O'' be'ore ma(!ng our appl!ca"!on a&a!lable "o users.
L. ;d!" %pacheKs con'!gura"!on '!le ;etc;httpd;con*;httpd"con* and add "he 'ollo+!ng l!nes)
Q
Q :his section will call E>E 'or .php and .phps 'iles
Q
<AilesNatch 2.php)
7et>andler application/.-httpd-php
</AilesNatch
<AilesNatch 2.phps)
7et>andler application/.-httpd-php-source
</AilesNatch
2!les +!"h "phps e/"ens!on +!ll be sho+n as h!ghl!gh"ed source code. 2or produc"!on
ss"ems, "h!s se""!ng should be om!""ed.
10. :' a Foad!odule l!ne +as no" alread !nser"ed b "he PHP !ns"all, add !" "oo)
KoadNodule php5$module /usr/li/PD/httpd/modules/li/php5.so
11. :' OC:$ +as con'!gured, se" an re>u!red Oracle en&!ronmen" &ar!ables, such as
OR%C.;NHOM;, .DN.:-R%RMNP%TH and 7.4N.%73. 4ee Setting the Oracle Environ+ent on
Finux la"er !n "h!s chap"er.
0hen runn!ng PHP, se" "he en&!ronmen" "o use "he same &ers!on o' "he Oracle l!brar!es
as +ere used dur!ng "he bu!ld process.
12. Res"ar" %pache)
Q serCice httpd start
Mou can e/per!men" +!"h PHP con'!gura"!on, comp!ler and !ns"all op"!ons un"!l ou ha&e a
b!nar bu!l" "o our s"andards. 2or e/ample, ou could benchmar( d!''eren" comp!lers and
cus"om!1e "he op"!m!1er 'lags. Produc"!on s!"es some"!mes reduce b!nar s!1es +!"h "he strip
command.
In!talling Oracle In!tant Client on 'inu *or the OCI. Eten!ion
The PHP OC:$ e/"ens!on needs access "o Oracle Dcl!en"E l!brar!es. These are con"a!ned !n "he
JO:A-FE=HO!E;lib d!rec"or. :' "he da"abase !s hos"ed on ano"her mach!ne or ou donA" ha&e
access "o !"s d!rec"or!es, "hen !ns"all "he Oracle :ns"an" Cl!en". Th!s small se" o' l!brar!es !s
a&a!lable "hrough U.7 pac(age managemen" 'or Oracle .!nu/ users, or o&er HTTP 'rom "he
Oracle Technolog 7e"+or(. 9end 4er&er alread !ncludes :ns"an" Cl!en".
To !ns"all :ns"an" Cl!en")
1. Do+nload "he -as!c and 4D6 :ns"an" Cl!en" pac(ages 'rom U.7 or OT7)
0)
'nstalling and ConAiguring !H!
http://www.oracle.com/technetwork/data/ase/'eatures/instant-client/inde.-
100@P5.html
3e" e!"her "he RPM or 9:P '!les. The e&en smaller -as!c .!"e pac(age can be subs"!"u"ed 'or
-as!c !' !"s charac"er se" and error message language res"r!c"!ons do no" !mpac" our
appl!ca"!on.
2. :' ou are us!ng "he RPMs, !ns"all "hem as "he roo" user)
Q rpm -RCh oracle-instantclient11.2-/asic-11.2.0.@.0-1..8P$PD.rpm
Q rpm -RCh oracle-instantclient11.2-deCel-11.2.0.@.0-1..8P$PD.rpm
The '!rs" RPM pu"s "he Oracle l!brar!es !n ;usr;lib;oracle;&&"2;client95;lib and "he second
crea"es headers !n ;usr;include;oracle;&&"2;client95"
I. :' ou are us!ng "he :ns"an" Cl!en" 9:P '!les, un1!p "he -as!c and "he 4D6 pac(ages "o a
d!rec"or o' our cho!ce, 'or e/ample ;opt;instantclient=&&=2. The '!les should be un1!pped
"oge"her so "he 4D6 !s !n ;opt;instantclient=&&=2;sd1.
J. :' :ns"an" Cl!en" +as !ns"alled 'rom "he 9:P '!les, crea"e a smbol!c l!n()
Q cd /opt/instantclient$11$2
Q ln -s li/clntsh.so.11.1 li/clntsh.so
:n Oracle 11.2 "he libclntsh '!le su''!/ re"a!ned "he 11.1 name "o (eep compa"!b!l!"
+!"h "ha" '!rs" release.
:' ou use Oracle :ns"an" Cl!en" "hen donA" se" "he OR%C.;NHOM; en&!ronmen" &ar!able +h!le
con'!gur!ng PHP or a" run"!me.
Con*iguration Option! *or Co1piling OCI. With PHP on 'inu
To bu!ld "he OC:$ e/"ens!on s"a"!call !n"o "he PHP b!nar +hen ou comp!le PHP Cas descr!bed
!n "he sec"!on -o+piling PHP as an Apache !odule on FinuxO, ou +!ll need "o use "he 33,ith3
oci/ op"!on +hen ou run con*igure. The help descr!p"!on 'or !" !s br!e')
--with-oci89*L5B< 5nclude 3racle %3458& support. L5B de'aults to )3B64K-$>3N-.
Rse --with-oci8*instantclient+/path/to/instant/client/li/
to use an 3racle 5nstant 4lient installation
The l!s" belo+ descr!bes ho+ "o use "he op"!on.
--with-oci8
0!"hou" an argumen", "h!s loo(s 'or Oracle Da"abase l!brar!es !n WOR%C.;NHOM;"
The &ar!able mus" pre&!ousl ha&e been se". :" l!n(s "he OC:$ e/"ens!on s"a"!call !n"o
PHP. :' WOR%C.;NHOM; !s no" se", !" +!ll loo( 'or "he :ns"an" Cl!en" RPM l!brar!es. PHP
mus" ha&e access "o "he Oracle l!brar!es and con'!gura"!on '!les +h!le bu!ld!ng and
subse>uen"l +hen runn!ng.
--with-oci8*shared
4ame as 33,ith3oci/ bu" crea"es an oci/"so shared l!brar. Th!s l!brar can be added "o,
or remo&ed 'rom, PHP +!"hou" ha&!ng "o recomp!le "he core PHP e/ecu"able.
0*
'nstalling !H! on Linu%
--with-oci8*/path/to/'ull/oracle/home
4ame as 33,ith3oci/ bu" uses "he spec!'!ed pa"h !ns"ead o' loo(!ng up
WOR%C.;NHOM;.
--with-oci8*shared+/path/to/'ull/oracle/home
Uses "he spec!'!ed Oracle Da"abase l!brar!es and crea"es a shared oci/"so e/"ens!on.
--with-oci8*instantclient
.oo(s 'or Oracle :ns"an" Cl!en" RPMs and uses "he mos" recen" &ers!on !ns"alled. .!n(s
"he OC:$ e/"ens!on s"a"!call !n"o PHP.
--with-oci8*shared+instantclient
.!(e "he pre&!ous op"!on bu" bu!lds a shared oci/"so e/"ens!on.
--with-oci8*instantclient+/path/to/instantclient/li/s
-u!lds +!"h "he :ns"an" Cl!en" !n "he spec!'!ed d!rec"or and l!n(s "he OC:$ e/"ens!on
s"a"!call !n"o PHP.
--with-oci8*shared+instantclient+/path/to/instantclient/li/s
Uses "he spec!'!ed :ns"an" Cl!en" and crea"es a shared oci/"so e/"ens!on.
To use a shared oci/"so l!brar, ed!" php"ini and add e.tension*oci8.so. %lso se"
e.tension$dir "o "he d!rec"or con"a!n!ng "he l!brar.
-e'ore bu!ld!ng OC:$ 'rom "he PHP source code, na&!ga"e "o "he ext;oci/;php=oci/"h '!le
and chec( +he"her "he &ers!on number !n "he PHPNOC:$N,;R4:O7 macro !s less "han "he
curren" release o' P;C. OC:$. :' "he P;C. OC:$ source code !s more recen", "hen !ns"all OC:$
as a shared e/"ens!on us!ng "he P;C. code.
In!talling OCI. on 'inu a! a Shared Eten!ion 0!ing PEC'
:' ou ha&e PHPAs pecl command "hen !" can be used "o 'e"ch and !ns"all OC:$ +!"h one s"ep.
4!nce P;C. pac(ages are compressed, PHP needs "o ha&e "he 1lib e/"ens!on !ns"alled C+!"h
"he 33,ith3lib op"!on "o con*igureF o"her+!se au"oma"!c !ns"alla"!on +!ll 'a!l +!"h "he error) )he
extension %lib% couldn%t be *ound"
:' ou donA" ha&e "he lib e/"ens!on !ns"alled, ou can s"!ll do+nload OC:$ 'rom "he P;C.
+ebs!"e and use phpie, as sho+n !n a la"er sec"!on.
PHP H.J needs autocon* 2.HL or la"erG earl!er &ers!ons o' PHP need autocon* 2.1I. Use
PHPN%UTOCO72 "o se" "he &ers!on, as sho+n pre&!ousl !n "h!s chap"er.
The P;C. OC:$ code can be !ns"alled on PHP J.I.L on+ards. Upgrad!ng OC:$ !s strongly
recommended !' ou mus" use PHP J. 7o"e old PHP &ers!ons are no longer ma!n"a!ned b "he
PHP commun!" and should no" be used 'or ne+ pro8ec"s.
To !ns"all PHP OC:$ us!ng "he P;C. channel)
1. 4hu"do+n %pache)
Q serCice httpd stop
2. Remo&e an e/!s"!ng OC:$ e/"ens!on)
Q pecl uninstall oci8
I. :' ou are beh!nd a '!re+all, se" "he P;%R pro/ +h!ch !s used b pecl, 'or e/ample)
Q pear con'ig-set http$pro.# http://e.ample.com:80/
0+
'nstalling and ConAiguring !H!
J. Do+nload and !ns"all OC:$)
Q pecl install oci8
Respond "o "he promp" as !' !" +ere a con*igure 33,ith3oci/ op"!on. :' ou ha&e a local
da"abase, "pe "he 'ull pa"h "o "he OR%C.;NHOM; so'"+are loca"!on, 'or e/ample)
/u01/app/oracle/product/11.2.0/.e
O"her+!se !' ou ha&e Oracle :ns"an" Cl!en" 11.2 RPMs, "pe)
instantclient+/usr/li//oracle/11.2/clientPD/li/
On I2?b!" .!nu/ +!"h :ns"an" Cl!en" RPMs "he l!ne +ould be
instantclient+/usr/li//oracle/11.2/client/li/
Use "he absolu"e pa"h because &ar!ables l!(e WOR%C.;NHOM; +!ll no" be e/panded.
:n some !n"ermed!a"e &ers!ons o' pecl !" +ould '!rs" promp" D&3&, %all%, %abort%, or Enter
to continueE. :' ou ge" "h!s promp", en"er D1E be'ore g!&!ng "he real response.
H. ;d!" php"ini and add)
e.tension*oci8.so
:' extension=dir !s no" se", se" !" "o "he d!rec"or +here oci/"so +as !ns"alled, 'or
e/ample)
e.tension$dir*/usr/li/PD/php/modules
The messages 'rom "he pecl !ns"all +!ll sho+ "he correc" d!rec"or.
O. 4e" an re>u!red Oracle en&!ronmen" &ar!ables such as .DN.:-R%RMNP%TH and 7.4N.%73.
4ee Setting the Oracle Environ+ent on Finux la"er !n "h!s chap"er.
P. Res"ar" %pache)
Q serCice httpd start
$. Chec( "he !ns"alla"!on, as sho+n a" "he end o' "h!s chap"er.
5anuall6 In!talling OCI. on 'inu a! a Shared Eten!ion
The 'ollo+!ng s"eps are "he manual e>u!&alen" "o "he pre&!ous pecl install oci/ command.
The can be used !' ou donA" ha&e "he pecl command.
The s"eps use phpie" Th!s +!ll ha&e been !ns"alled +hen ou bu!l" PHP or !" can be 'ound
!n "he php3devel or php463devel RPM pac(ages.
To !ns"all OC:$ on an e/!s"!ng PHP !ns"alla"!on as a shared l!brar)
1. 4hu"do+n %pache)
Q serCice httpd stop
2. :' OC:$ +as pre&!ousl !ns"alled, bac(up or remo&e "he oci/"so '!le
Q mC /usr/li/PD/php/modules/oci8.so /usr/li/PD/php/modules/oci8.so.old
0-
'nstalling !H! on Linu%
I. Do+nload "he OC:$ e/"ens!on 'rom P;C., http://pecl.php.net/package/oci8
J. ;/"rac" and prepare "he ne+ code)
Q tar -X.' oci8-1.D.9.tgX
Q cd oci8-1.D.9
Q phpiXe
H. Con'!gure OC:$. :' ou ha&e a local da"abase, use)
Q ./con'igure V-with-oci8*shared+)3B64K-$>3N-
O"her+!se !' ou ha&e Oracle :ns"an" Cl!en" 11.2 use "he loca"!on o' "he l!bar!es, 'or
e/ample)
Q ./con'igure V-with-oci8*2
shared+instantclient+/usr/li//oracle/11.2/clientPD/li/
O. -u!ld and !ns"all "he shared l!brar)
Q make
Q make install
P. ;d!" ;etc;php"ini and add "h!s l!ne)
e.tension*oci8.so
$. :' extension=dir !s no" se", se" !" "o "he d!rec"or +here oci/"so +as !ns"alled, 'or e/ample)
e.tension$dir*/usr/li/PD/php/modules
L. 4e" an re>u!red Oracle en&!ronmen" &ar!ables such as .DN.:-R%RMNP%TH and 7.4N.%73.
4ee "he ne/" sec"!on !n "h!s chap"er.
10. Res"ar" %pache)
Q serCice httpd start
11. Chec( "he !ns"alla"!on, as sho+n a" "he end o' "h!s chap"er.
Setting the Oracle En-iron1ent *or PHP on 'inu
The Oracle en&!ronmen" need "o be se" be'ore PHP loads Oracle l!brar!es so "ha" Oracle
con'!gura"!on '!les can be 'ound and da"a s"ruc"ures can be !n!"!al!1ed correc"l. ;n&!ronmen"
&ar!ables need "o be e/por"ed !n an shell "ha" runs command?l!ne PHP. 2or +eb appl!ca"!ons
"he need "o be e/por"ed be'ore %pache s"ar"s. :' %pache !s s"ar"ed au"oma"!call +hen our
mach!ne s"ar"s ou +!ll need "o ma(e sure "he en&!ronmen" !s se" a" boo" "!me.
4ome common +as "o se" "he en&!ronmen" 'or %pache are)
On Oracle .!nu/ and s!m!lar d!s"r!bu"!ons us!ng "he de'aul" %pache pac(age, add
en&!ronmen" &ar!ables "o ;etc;syscon*ig;httpd)
...
e.port 3B64K-$>3N-*/u01/app/oracle/product/11.2.0/.e
00
'nstalling and ConAiguring !H!
e.port KL$K5IB6B;$E6:>*)3B64K-$>3N-/li/:)KL$K5IB6B;$E6:>
e.port MK7$K6MY*6N-B546M$6N-B546.?-8N7?5M1252
On ss"ems l!(e Ubun"u ou can pu" "he &ar!ables !n ;etc;apache2;envvars.
4ome %pache 2 !ns"alla"!ons ha&e a bin;envvars scr!p" !n "he %pache d!rec"or.
4ome"!mes users dec!de "o se" "he &ar!ables !n ;etc;init"d;httpd and al+as use "ha" scr!p"
"o s"ar" "he +eb ser&er.
O"her users use %pacheAs Eass-nC d!rec"!&e !n httpd"con* "o pass "he en&!ronmen" "o PHP.
4e""!ng &alues +!"h %pacheAs 7et-nC d!rec"!&e +!ll no" +or(.
The mos" gener!c +a "o se" "he +hole en&!ronmen" !s "o crea"e a shell scr!p" such as
start=apache"sh and run !" +hene&er ou +an" "o s"ar" %pache.
Script 5' start=apache"sh
Q8 //in/sh
3B64K-$>3N-*/u01/app/oracle/product/11.2.0/.e
KL$K5IB6B;$E6:>*)3B64K-$>3N-/li/:)KL$K5IB6B;$E6:>
MK7$K6MY*6N-B546M$6N-B546.?-8N7?5M1252
e.port 3B64K-$>3N- KL$K5IB6B;$E6:> MK7$K6MY
echo "3racle >ome: )3B64K-$>3N-"
echo 7tarting 6pache
Qe.port /tmp/enCCars Q uncomment to de/ug
/usr/s/in/apachectl start
7o"e) Do no" se" Oracle en&!ronmen" &ar!ables !n PHP scr!p"s +!"h putenC%&. The +eb ser&er
ma load Oracle l!brar!es and !n!"!al!1e Oracle da"a s"ruc"ures be'ore runn!ng our scr!p". 0!"h
pers!s"en" connec"!ons "he en&!ronmen" 'rom one scr!p" ma a''ec" subse>uen" scr!p"s. Us!ng
putenC%& causes hard "o "rac( errors as "he beha&!or !s no" cons!s"en" 'or all &ar!ables, +eb
ser&ers, opera"!ng ss"ems, or OC:$ 'unc"!ons.
:' PHP +as bu!l" +!"h Oracle :ns"an" Cl!en", !ns"ead o' se""!ng .DN.:-R%RMNP%TH !" can be
con&en!en" "o se" "he l!brar pa"h ss"em +!de. Crea"e a '!le
;etc;ld"so"con*"d;instantclient"con* con"a!n!ng "he pa"h "o "he :ns"an" Cl!en" l!brar!es)
/usr/li//oracle/11.2/clientPD/li/
Run ldcon*ig "o rebu!ld "he ss"emAs l!brar search pa"h. Onl do "h!s !' "here !s no o"her
Oracle so'"+are !n use on "he mach!ne. :" remo&es "he need "o se" .DN.:-R%RMNP%TH
e&er+here, bu" upgrad!ng :ns"an" Cl!en" does re>u!re remember!ng "o upda"e
instantclient"con*.
:' ou ha&e en&!ronmen" rela"ed problems such as une/pec"ed connec"!on errors, "hen
crea"e a scr!p" phpin*o"php'
01
'nstalling !H! on Linu%
Script 4' phpin*o"php
<?php
phpin'o%&!
?
Chec( "he ou"pu" 'rom phpin*o"php. .oo( a" "he Environ+ent sec"!on Cno" "he Apache
Environ+ent sec"!onF and ma(e sure "he Oracle &ar!ables are se" "o "he &alues ou e/pec". :"
!s use'ul "o chec( "he ou"pu" us!ng bo"h command l!ne PHP and &!a a bro+ser.
:' ou are e/pec"!ng shell en&!ronmen" &ar!ables "o be passed "o %pache and PHP, do no" use
"he .!nu/ service command "o s"ar" %pache, s!nce "h!s clears "he en&!ronmen". :ns"ead,
d!rec"l res"ar" %pache b e/ecu"!ng ;etc;init"d;httpd restart or "he e>u!&alen" on our
pla"'orm.
Common Oracle Enironment !ariables on Linux
The &ar!ables needed b OC:$ depend on ho+ PHP !s !ns"alled, ho+ ou connec" "o "he
da"abase, and +ha" op"!onal se""!ngs are des!red.
)able 5' -o++on Oracle environ+ent variables on Finux"
Oracle En-iron1ent <aria$le Purpo!e
3B64K-$>3N- The d!rec"or con"a!n!ng "he Oracle da"abase so'"+are. Th!s
d!rec"or mus" be access!ble b "he %pache process. Th!s
&ar!able should no" be se" !' PHP uses Oracle :ns"an" Cl!en".
3B64K-$75L The Oracle 7e" connec" name o' "he da"abase. Onl used
+hen PHP !s on "he same mach!ne as "he da"abase and "he
connec"!on !den"!'!er !s no" spec!'!ed !n "he PHP connec"
'unc"!on. 7o" o'"en se" 'or PHP appl!ca"!ons. 7o" used +hen
PHP !s l!n(ed +!"h Oracle :ns"an" Cl!en".
KL$K5IB6B;$E6:> 4e" "h!s "o !nclude "he Oracle l!brar!es, 'or e/ample
JO:A-FE=HO!E;lib or ;opt;instantclient=&&=2" 7o" needed !'
"he l!brar!es are loca"ed b an al"erna"!&e me"hod, such as
+!"h "he ;etc;ld"so"con* l!n(er pa"h '!le. On U7:= pla"'orms ou
+!ll need "o se" "he O4 spec!'!c e>u!&alen", such as F.IPA)H or
SHF.I=PA)H.
MK7$K6MY De"erm!nes "he Dna"!onal language suppor"E global!1a"!on
op"!ons 'or OC:$. 4ee "he chap"er Globaliation 'or more
de"a!ls. :' no" se", a de'aul" &alue +!ll be chosen b Oracle.
4e""!ng "h!s !s recommended.
02
'nstalling and ConAiguring !H!
Oracle En-iron1ent <aria$le Purpo!e
MK7$MRN-B54$4>6B64:-B7 Commonl se" !n PHP appl!ca"!ons "o 'orce Oracle number?"o?
s"r!ng con&ers!ons "o use a per!od 'or "he dec!mal separa"or.
O"her+!se numer!c da"a &alues re"urned 'rom "he da"abase !n
s"r!ng 'orma" +!ll no" correc"l cas" "o a number !n PHP !n
locales +here "he dec!mal separa"or !s no" a per!od. The
&ar!able !s !gnored !' 7.4N.%73 !s no" se".
MK7$L6:-$A3BN6: O'"en se" !n PHP appl!ca"!ons "o 'orce a cons!s"en" da"e 'orma"
!ndependen" o' "he locale. The &ar!able !s !gnored !'
7.4N.%73 !s no" se".
:M7$6LN5M The loca"!on o' "he tnsna+es"ora and sDlnet"ora con'!gura"!on
'!les. 7eeded b PHP !' a da"abase connec" name 'rom a
tnsna+es"ora '!le !s used !n "he OC:$ connec" 'unc"!ons and
ou are us!ng Oracle :ns"an" Cl!en", or !' "he tnsna+es"ora '!le
!s no" !n JO:A-FE=HO!E;net,or1;ad+in. %lso needed !' us!ng
a sDlnet"ora '!le +!"h Oracle :ns"an" Cl!en", or us!ng '!les no" !n
JO:A-FE=HO!E;net,or1;ad+in.
0!"h Oracle Da"abase 11g =;, ou can se" "he Oracle en&!ronmen" !n a shell b us!ng "he
oracle=env"sh scr!p")
) source /u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
The source command allo+s "he scr!p" "o se" "he en&!ronmen" o' "he shell !"sel'. :n some
shells use a s!ngle per!od !n place o' source. :n C or "csh shells use "he oracle=env"csh '!le.
On o"her ed!"!ons o' "he Oracle da"abase, "he ;usr;local;bin;oraenv or
;usr;local;bin;coraenv scr!p"s se" "he en&!ronmen". Run one o' "hese scr!p"s be'ore s"ar"!ng
%pache. Mou +!ll be promp"ed 'or "he da"abase "o connec" "o)
) source /usr/local//in/oraenC
3B64K-$75L * 9< ? orcl
:' our da"abase !s on a remo"e mach!ne, ou +!ll ha&e "o se" our local en&!ronmen"
manuall.
%'"er se""!ng "he &ar!ables !n "he shell, ou can cop "he se""!ngs "o "he appropr!a"e
%pache con'!gura"!on '!le "o ma(e sure "he are se" no ma""er ho+ %pache !s s"ar"ed.
Signal Handling and #e*unct Proce!!e! on 'inu
:n "he earl das o' PHP some Oracle users repor"ed see!ng de'unc" @1omb!e@ proceses. The
!ssue has no" been repor"ed 'or a &er long "!me. :' !" does happen "o ou, "hen s"ar" %pache
+!"h "he Oracle 7e" op"!on I-SR-6:>$L-:64>*;-7 !n our sDlnet"ora. Or, "o (eep "he se""!ng
spec!'!c "o PHP, se" "he en&!ronmen" be'ore s"ar"!ng %pache)
e.port I-SR-6:>$L-:64>*;-7
:' "h!s doesnA" help, onl "hen cons!der bu!ld!ng PHP +!"h 33enable3sigchild.
De'unc" processes m!gh" happen !' "he Oracle code !n PHP 'or(s "he Oracle ser&er process
Ccalled @be>uea"h!ng@F and "he s!gnal handlers !n PHP, as "he paren" o' "he ser&er process, do
no" correc"l clean up "he ser&er process +hen a da"abase connec"!on !s closed. The
I-SR-6:>$L-:64>*;-7 op"!on causes "he ser&er processes "o do a double 'or( and be !nher!"ed
13
'nstalling !H! on Linu%
b @init@, +h!ch pre&en"s de'unc" 1omb!es. Oracle Da"abase 10g on+ards chec(s 'or s!gnal
handler clashes and au"oma"!call "urn on -;BU;%THND;T%CH, reduc!ng "he need 'or ou "o
se" !". :" !s no" on b de'aul" because !" adds a 'e+ e/"ra CPU ccles and "he O4 paren" process
!d becomes 1, ma(!ng !" sl!gh"l harder "o !den"!' "he rela"!onsh!p be"+een a ser&er process
and "he appl!ca"!on process us!ng !". Mou m!gh" need "o manuall se" -;BU;%THND;T%CH !'
s!gnal handlers are changed a'"er Oracle has done !"s heur!s"!c chec(.
There are some s!de e''ec"s +!"h 33enable3sigchild. PHPAs pclose%& ma re"urn 'a!lure.
4e&eral PHP bug repor"s e/!s" 'or "h!s and PHP code has been pa"ched and bro(en aga!n !n
"h!s area.
:' PHP !s @remo"e@ 'rom "he da"abase ser&er ou should ne&er need "o con'!gure PHP +!"h
33enable3sigchild or se" I-SR-6:>$L-:64>*;-7. PHP can be remo"e phs!call or because "he
PHP b!nar !s l!n(ed +!"h d!''eren" Oracle l!brar!es "o "hose used b "he da"abase, 'or e/ample
+!"h Oracle :ns"an" Cl!en".
Mou also donA" need "o change s!gnal handl!ng !' ou use Oracle shared or pooled ser&ers.
These are "he cases +here PHP does no" 'or( "he Oracle ser&er process d!rec"l. The Oracle
7e" l!s"ener does "he 'or(!ng !ns"ead and PHPAs s!gnal handl!ng +onA" a''ec" Oracle ser&er
process cleanup.
0!ing PHP79P5 With ,pache on 'inu
%ll o' "he pre&!ous .!nu/ con'!gura"!on e/amples use a PHP %pache module. The rela"!&el ne+
PHP?2PM D2as"C3: Process ManagerE module !s an al"erna"!&e "ha" !s ga!n!ng popular!". PHP?
2PM has some ad&anced process managemen" and !sola"!on con"rols.
PHP?2PM !s documen"ed !n "he PHP manual and a" http://php-'pm.org/. :" !s o'"en used
+!"h "he nginx +eb ser&er.
"uilding #$# With #$#%&#'
Th!s e/ample sho+s bu!ld!ng PHP?2PM on OJ?b!" Oracle .!nu/ us!ng "he ss"em %pache. To
&ar 'rom pre&!ous e/amples, !" bu!lds a shared OC:$ e/"ens!on d!rec"l 'rom "he PHP source.
:" assumes :ns"an" Cl!en" RPMs are !ns"alled. Mou could choose "o bu!ld OC:$ s"a"!call !n"o "he
PHP b!nar, or add !" la"er 'rom P;C. us!ng me"hods pre&!ousl d!scussed.
1. -u!ld and !ns"all PHP)
Q tar -W.' php-5.D.D.tar./X2
Q cd php-5.D.D
Q ./con'igure --ena/le-'pm --pre'i.*/opt/php5DD 2
--with-oci8*shared+instantclient
Q make
Q make install
2. 4e" up "he PHP con'!gura"!on)
Q cp php.ini-deCelopment /opt/php5DD/li//php.ini
;d!" php"ini" %dd "he OC:$ e/"ens!on shared module and se" date"ti+eone "o our
"!me1one, 'or e/ample)
e.tension*oci8.so
date.timeXone * 6merica/Kos$6ngeles
1&
'nstalling and ConAiguring !H!
I. Crea"e "he PHP?2PM ser&!ce)
Q cp sapi/'pm/init.d.php-'pm /etc/init.d/php-'pm
Q chmod H. /etc/init.d/php-'pm
Q chkcon'ig --add php-'pm
J. Crea"e "he PHP?2PM con'!gura"!on '!le)
Q cp /opt/php5DD/etc/php-'pm.con'.de'ault /opt/php5DD/etc/php-'pm.con'
H. ;d!" php3*p+"con* and uncommen" "he l!ne)
pid * run/php-'pm.pid
O. Do+nload 2as"C3: 'rom http://www.'astcgi.com/dist/mod$'astcgi-current.tar.gX
P. -u!ld 2as"C3: 'or %pache 2)
Q tar -X.' mod$'astcgi-current.tar.gX
Q cd mod$'astcgi-2.D.P
Q cp Nake'ile.6E2 Nake'ile
Q make top$dir*/usr/li/PD/httpd
$. :ns"all 2as"C3: !n"o %pache)
Q make top$dir*/usr/li/PD/httpd install
L. 4e" up %pache b enabl!ng PHP?2PM !n ;etc;httpd;con*;httpd"con*)
<5'Nodule mod$'astcgi.c
Aast4Y5-.ternal7erCer /opt/php5DD/s/in/php-'pm -host 12U.0.0.1:9000
6dd>andler php-'astcgi .php
6ction php-'astcgi /m#cgi
7cript6lias /m#cgi /opt/php5DD/s/in/php-'pm
Q Rncomment 'or the statistics page %also set pm.status$path in php-'pm.con'&
Q <KocationNatch "/status"
Q 7et>andler php-'astcgi-Cirt
Q 6ction php-'astcgi-Cirt /m#cgi Cirtual
Q </KocationNatch
</5'Nodule
10. 4"ar" PHP?2PM and %pache)
Q serCice php-'pm start
Q serCice httpd start
PHP scr!p"s !n our Docu+ent:oot d!rec"or, 'or e/ample !n ;var;,,,;ht+l, +!ll be
e/ecu"ed b PHP?2PM.
1(
'nstalling !H! on Linu%
#$#%&#' Statistics
The php3*p+"con* '!le sho+s a number o' PHP?2PMAs 'ea"ures, !nclud!ng pool and logg!ng
op"!ons. One s"ra!gh"?'or+ard PHP?2PM 'ea"ure !s !"s bu!l" !n s"a"!s"!cs ga"her!ng. To use "h!s,
'!rs" uncommen" "he Focation!atch sec"!on !n httpd"con*)
<KocationNatch "/status"
7et>andler php-'astcgi-Cirt
6ction php-'astcgi-Cirt /m#cgi Cirtual
</KocationNatch
1. ;d!" php3*p+"con* and uncommen" "he status=path d!rec"!&e)
pm.status$path * /status
2. Res"ar" PHP?2PM and %pache)
Q serCice php-'pm start
Q serCice httpd start
I. 7o+ "he s"a"!s"!cs page can be called +!"h http';;localhost;statusB*ull.
The ou"pu" +!ll be l!(e)
pool: www
process manager: d#namic
start time: 02/3ct/2012:21:55:DD -0U00
start since: D0UP
accepted conn: 10
listen "ueue: 0
ma. listen "ueue: 0
listen "ueue len: 128
idle processes: 1
actiCe processes: 1
total processes: 2
ma. actiCe processes: 1
ma. children reached: 0
JJJJJJJJJJJJJJJJJJJJJJJJ
pid: 9@22
state: 5dle
start time: 02/3ct/2012:21:55:DD -0U00
start since: D0UP
re"uests: 5
re"uest duration: @5D
re"uest method: Y-:
re"uest RB5: /status?'ull
content length: 0
user: -
script: -
last re"uest cpu: 0.00
last re"uest memor#: 2P21DD
O"her op"!ons "o ;status allo+ "he s"a"!s"!cs "o be re"urned n!cel mar(ed up !n HTM.
or !n *4O7.
1)
'nstalling and ConAiguring !H!
Oracle Enironment !ariables in #$#%&#'
To se" Oracle en&!ronmen" &ar!ables 'or PHP?2PM, add "hem "o php3*p+"con* l!(e)
enC9MK7$K6MY< * 6N-B546M$6N-B546.6K@2R:A8
enC9MK7$L6:-$A3BN6:< * ;;;;-NN-LL
:ns"ead o' us!ng cons"an"s, ou can ass!gn "erm!nal en&!ronmen" &ar!ables "o "he env arra.
Ho+e&er, be+are "ha" service clears "he en&!ronmen" so ou +!ll need "o res"ar" PHP?2PM
e/pl!c!"l l!(e)
Q /etc/init.d/php-'pm restart
:" !s be""er "o se" "he &alues e/pl!c!"l so "he al+as "a(e "he e/pec"ed &alues.
In!talling PHP With OCI. on Windo;!
Th!s sec"!on descr!bes ho+ "o !ns"all PHP and %pache on 0!ndo+s.
-e'ore ou do "h!s, cons!der !' ou are !n"end!ng "o +r!"e PHP code "ha" +!ll run on a
d!''eren" opera"!ng ss"em. Mos" +eb s!"es run "he!r produc"!on +eb ser&ers on .!nu/.
-ecause "here are numerous sub"le d!''erences be"+een PHP on 0!ndo+s and PHP on .!nu/,
par"!cularl !n '!le handl!ng and per'ormance, ou should a&o!d de&elop!ng on 0!ndo+s unless
necessar. Mou can also run !n"o l!brar clash !ssues +hen ou ha&e mul"!ple &ers!ons o'
Oracle !ns"alled on 0!ndo+s. % grea" solu"!on !n "hese cases !s "o use OracleAs 'ree ,!r"ual-o/
produc" and crea"e a &!r"ual mach!ne "ha" runs Oracle .!nu/.
Th!s e/ample sho+s !ns"all!ng PHP H.J.0 us!ng "he 2as"C3: model !n 0!ndo+s. Th!s
pre'erred me"hod o' !ns"all!ng a&o!ds an "hread?sa'e" !ssues "ha" PHPAs D9T4E C9end Thread
4a'eF 0!ndo+s b!nar!es are suspec"ed "o ha&e.
-e'ore con"!nu!ng, !ns"all %pache as sho+n !n "he pre&!ous chap"er.
Oracle 'i$rarie! on Windo;!
The PHP OC:$ D.. on 0!ndo+s re>u!res Oracle cl!en" D..s 'rom 10gR2 or la"er. Mou should
!ns"all Oracle :ns"an" Cl!en" !' ou donA" ha&e an Oracle Da"abase !ns"alled. O"her+!se PHP
OC:$ can use "he cl!en" l!brar!es con"a!ned !n a I2?b!" da"abase !ns"all such as Oracle 11g =;.
:' ou ha&e LiR2 l!brar!es, ou +!ll ha&e "o comp!le PHP OC:$ oursel', +h!ch !s ou" o' scope o'
"h!s boo(.
Ha&!ng mul"!ple cop!es o' Oracle l!brar!es !ns"alled on 0!ndo+s can cause hard "o resol&e
con'l!c"s unless our en&!ronmen" !s cleanl se". Tr!ng "o use PHP +!"h a OJ?b!" Oracle
Da"abase !s ano"her !ssue, s!nce PHP !s I2?b!". There are some ugl hac(s people ha&e used
"o resol&e "he con'l!c"s, !nclud!ng cop!ng "he :ns"an" Cl!en" l!brar!es "o "he ss"em d!rec"or.
These are no" recommended. :ns"ead, +r!"e a scr!p" "ha" se"s "he en&!ronmen" and "hen s"ar"s
%pache. There are "!ps on "h!s !n
https:///logs.oracle.com/opal/entr#/using$php$oci8$with$@2-/it$php
In!talling Oracle In!tant Client on Windo;!
:' ou are no" us!ng Oracle l!brar!es 'rom a da"abase !ns"alla"!on, !ns"all Oracle :ns"an" Cl!en"
+!"h "he 'ollo+!ng s"eps)
1. Do+nload "he :ns"an" Cl!en" -as!c pac(age 'or M!croso'" 0!ndo+s CI2?b!"F 'rom "he :ns"an"
Cl!en" page on "he Oracle Technolog 7e"+or()
1*
'nstalling !H! With .C'1 on Windo/s
http://www.oracle.com/technetwork/data/ase/'eatures/instant-
client/inde.-09UD80.html
The 0!ndo+s I2?b!" 9:P '!le !s called instantclient3basic3nt3&&"2"A"6"A"ip and !s around
H0 M- !n s!1e. :' ou need "o connec" "o Oracle Da"abase $i, "hen !ns"all "he Oracle
10gR2 :ns"an" Cl!en". On some 0!ndo+s !ns"alla"!ons, "o use Oracle 10gR2 :ns"an"
Cl!en" ou ma need "o loca"e a cop o' +svcr?&"dll and pu" !" !n our P%TH.
Crea"e a ne+ d!rec"or, 'or e/ample, -'Kinstantclient=&&=2. Un1!p "he do+nloaded '!le
!n"o "he ne+ d!rec"or.
2. ;d!" "he 0!ndo+s en&!ronmen" and add "he loca"!on o' "he Oracle :ns"an" Cl!en" '!les,
-'Kinstantclient=&&=2, "o "he P%TH en&!ronmen" &ar!able, be'ore an o"her Oracle
d!rec"or!es. 2or e/ample, on 0!ndo+s =P, use #tart 9 #ettings 9 Control !anel 9
#ystem 9 Ad$anced 9 4n$ironment @aria5les" and ed!" P%TH !n "he 4s"em ,ar!ables
l!s". Reboo" "o ma(e "h!s "a(e e''ec". 7o" reboo"!ng !s a common source o' !ns"alla"!on
"ee"h!ng "roubles.
I. :' ou are us!ng a tnsna+es"ora '!le "o de'!ne Oracle 7e"+or( connec" names, cop our
tnsna+es"ora '!le "o -'Kinstantclient=&&=2, and se" "he user en&!ronmen" &ar!able
T74N%DM:7 "o -'Kinstantclient=&&=2.
J. 4e" an o"her re>u!red Oracle global!1a"!on language en&!ronmen" &ar!ables, such as
7.4N.%73. :' no"h!ng !s se", "he de'aul" local en&!ronmen" !s used. 4ee "he Globaliation
chap"er, 'or more !n'orma"!on on global!1a"!on +!"h PHP and Oracle.
Unse" an Oracle en&!ronmen" &ar!ables "ha" are no" re>u!red and should no" be se"
+!"h Oracle :ns"an" Cl!en", such as OR%C.;NHOM; and OR%C.;N4:D.
In!talling PHP on Windo;!
Canon!cal PHP bu!lds are d!s"r!bu"ed 'rom http://windows.php.net/download !n 9:P '!les. :n
"he pas", PHP M4: !ns"aller '!les e/!s"ed, bu" "he are no" a&a!lable 'rom PHP H.J on+ards.
To !ns"all PHP, per'orm "he 'ollo+!ng s"eps, subs"!"u"!ng "he curren" &ers!on o' PHP. Mou
mus" be an adm!n!s"ra"!&e user)
1. Do+nload "he PHP H.J.0 @,CL /$O 7on Thread 4a'e@ 9:P pac(age php34"5"A3nts3Win623
7-83x/9"ip 'rom http://windows.php.net/download/.
Use "he non?"hread sa'e bundle because !" +!ll be used +!"h 2as"C3:.
:n 0!ndo+s ;/plorer, go "o "he d!rec"or +here ou do+nloaded "he 1!p '!le.
2. Un1!p "he PHP pac(age "o a d!rec"or called -'Kphp34"5"A
I. Cop php"ini3develop+ent "o -'Kphp34"5"AKphp"ini
J. ;d!" php"ini and ma(e "he 'ollo+!ng changes)
%dd our localhos" "!me1one, 'or e/ample)
date.timeXone * 6merica/Kos$6ngeles
%dd "he d!rec"or con"a!n!ng "he PHP e/"ens!ons)
e.tension$dir * "4:2php-5.D.02e.t"
%lso !n "h!s '!le remo&e "he sem!colon 'rom "he beg!nn!ng o' "he l!ne)
e.tension*php$oci8$11g.dll
1+
'nstalling and ConAiguring !H!
Th!s e/"ens!on can be used +hen our Oracle cl!en" l!brar!es Ce!"her 'rom "he
da"abase !ns"all or 'rom :ns"an" Cl!en"F are Oracle 11gR2 or grea"er. :' ou are onl
us!ng 10gR2 Oracle cl!en" l!brar!es, "hen !ns"ead uncommen" "he l!ne)
e.tension*php$oci8.dll
Onl one o' php=oci/"dll and php=oci/=&&g"dll can be enabled a" an "!me.
H. ;d!" "he httpd"con* '!le, 'or e/ample -'KProgra+ (ilesKApache So*t,are
(oundationKApache2"2Kcon*Khttpd"con*, and add "he 'ollo+!ng l!nes. Ma(e sure ou use
'or+ard slashes A<A and no" bac( slashes AXA)
Acgid5nitial-nC E>EB4 "4:/php-5.D.0"
6dd>andler 'cgid-script .php
Acgid?rapper "4:/php-5.D.0/php-cgi.e.e" .php
The PHPRC op"!on "ells PHP +h!ch d!rec"or "he php"ini '!le !s loca"ed !n. The o"her
op"!ons se" up "he 2as"C3: handler.
O. Ma(e sure +od=*cgid"so !s loaded and "he ;/ecC3: op"!on se" as descr!bed !n "he pre&!ous
chap"er.
P. Res"ar" "he %pache 4er&er so "ha" ou can "es" our PHP !ns"alla"!on. :' ou ha&e errors,
double chec( our httpd"con* and php"ini '!les. :' ou al"ered "he P%TH en&!ronmen"
&ar!able ma(e sure ou reboo" "he mach!ne and chec( P%TH !ncludes "he Oracle l!brar
d!rec"or.
$. Chec( "he !ns"alla"!on, as sho+n a" "he end o' "h!s chap"er.
In!talling OCI. With Oracle HTTP Ser-er
The Oracle HTTP 4er&er COH4F !s based on %pache. :" +as par" o' OracleAs %ppl!ca"!on 4er&er,
and !s one o' "he +eb ser&ers "ha" can be used b Oracle 0eb.og!c 4er&er C0.4F. Mou can
!ns"all or upgrade PHP on OH4.
7o"e) :ns"all!ng or upgrad!ng PHP !n Oracle HTTP 4er&er !s no" suppor"ed Cand hence !s no"
recommendedF bu" !s "echn!call poss!ble !n some c!rcums"ances. 2or an suppor" calls,
regardless o' +he"her "he are PHP rela"ed, Oracle 4uppor" ma as( ou "o re&er" "he
changes be'ore beg!nn!ng !n&es"!ga"!on.
The "+o sec"!ons belo+ sho+ ho+ "o bu!ld PHP as an %pache module 'or OH4 on .!nu/.
:' ou +an" "o !ns"all PHP on Oracle 0eb.og!c 4er&er and do no" ha&e a +eb "!er, "hen
cons!der us!ng one and !ns"all!ng PHP !n"o %pache or ng!n/. Mour load balancer or +eb ser&er
can d!rec" HTTP re>ues"s as appropr!a"e "o 0.4 or PHP. Th!s +!ll ma(e l!cens!ng, !ns"alla"!on,
managemen" and upgrad!ng o' 0.4 eas!er. Mou can also use a 0.4 +eb ser&er plug?!n, as
descr!bed !n "he 0.4 documen"a"!on. The plug?!n can pro/ re>ues"s 'rom, 'or e/ample,
%pache "o 0.4. Mou can !ns"all PHP !n"o %pache as sho+n earl!er !n "h!s chap"er.
1-
'nstalling .C'1 With .racle HTT! #er$er
In!talling OCI. With Oracle HTTP Ser-er 11g on 'inu
0!"h OH4 11g, PHP !s no" !ncluded and ou mus" bu!ld !" oursel'. The "echn!cal problem 'aced
+!"h bu!ld!ng PHP !s "ha" "he Oracle l!brar!es +!"h Oracle HTTP 4er&er do no" !nclude header
'!les. Th!s can be o&ercome b l!n(!ng PHP +!"h Oracle :ns"an" Cl!en" bu" care needs "o be
"a(en so "ha" %4 !"sel' does no" use "he :ns"an" Cl!en" l!brar!es. O"her+!se ou +!ll ge" errors or
unpred!c"able beha&!or.
These s"eps are &er &ers!on and pla"'orm spec!'!c. The ma no" be "echn!call 'eas!ble !n
all deplomen"s.
To !ns"all PHP on OH4 11g)
1. .og on as "he oracle user and shu"do+n OH4)
) )3B64K-$5M7:6M4-//in/opmnctl stopproc ias-component*ohs1
2. Change "o "he home d!rec"or)
) cd )>3N-
I. 4e" "he Oracle en&!ronmen")
) e.port 3B64K-$>3N-*/#our/path/to/#our/3racle/>ome
) e.port 3B64K-$5M7:6M4-*/#our/path/to/3>7
) e.port 43MA5Y$A5K-$E6:>*)3B64K-$5M7:6M4-/con'ig/3>7/ohs1
) e.port KL$K5IB6B;$E6:>*)3B64K-$>3N-/li/:)3B64K-$>3N-/ohs/li/:2
)KL$K5IB6B;$E6:>
OR%C.;NHOM; !s "he d!rec"or +!"h "he OH4 b!nar!es !n JO:A-FE=HO!E;ohs;bin.
OR%C.;N:74T%7C; !s our d!rec"or con"a!n!ng "he Oracle HTTP 4er&er componen"
@ohs1@.
J. Op"!onall se" "he PHP comp!ler en&!ronmen", 'or e/ample !' ou are us!ng a non 37U "ool
cha!n)
) e.port 4AK6Y7*#our-compiler-'lags
) e.port 44*/path/to/#our/compiler
H. Do+nload and e/"rac" "he Oracle :ns"an" Cl!en" 11.1.0.P 4D6 9:P '!le 'rom
http://www.oracle.com/technetwork/data/ase/'eatures/instant-client/inde.-
09UD80.html
O. Cop "he ne+ header '!les 'rom :ns"an" Cl!en" "o "he Oracle home)
) cp instantclient$11$1/sdk/include/J.h )3B64K-$>3N-/rd/ms/demo
P. Do+nload PHP 'rom http://php.net/downloads.php and e/"rac" "o a +or(!ng d!rec"or,
'or e/ample +!"h PHP H.I)
) tar -WX' php-5.@.1@.tar./X2
$. Change "o "he e/"rac"ed PHP d!rec"or
) cd php-5.@.1@
L. :' our &ers!on o' PHP !s H.I.1P or earl!er, "hen pa"ch our con*igure scr!p". Change all
10
'nstalling and ConAiguring !H!
occurrences o')
6E64>-$Z-B753M*\e.pr )D 2J 1000000 H )5 2J 1000 H )P\
"o
6E64>-$Z-B753M*\e.pr )P 2J 1000000 H )U 2J 1000 H )8\
Th!s !s because OH4As %pache repor"s !"s &ers!on number d!''eren"l 'rom pure
%pache. 0!"hou" "h!s change, PHP +!ll "h!n( %pache !s &ers!on 1.I and "he !ns"alla"!on
+!ll 'a!l.
10. Con'!gure PHP +!"h our cho!ce o' e/"ens!ons. %s a s"ar"!ng po!n" beg!n +!"h "he bas!c
con'!gura"!on)
) ./con'igure --disa/le-all --with-ap.s2*)3B64K-$>3N-/ohs//in/ap.s 2
--with-oci8*)3B64K-$>3N- --disa/le-rpath 2
--pre'i.*)3B64K-$>3N- --with-con'ig-'ile-path*)43MA5Y$A5K-$E6:>
11. Ma(e "he PHP command l!ne b!nar and %pache module)
) make
12. Cop a de'aul" php"ini '!le 'or PHP)
) cp php.ini-deClopment )43MA5Y$A5K-$E6:>/php.ini
or
) cp php.ini-production )43MA5Y$A5K-$E6:>/php.ini
1I. ;d!" J-O2(.G=(.FE=PA)H;php"ini and add a "!me1one l!ne)
date.timeXone * 6merica/Kos$6ngeles
1J. :' ou +an" "o run OC:$ "es"s, ed!" php"ini and add - "o Caria/les$order. Th!s allo+s PHPAs
run3tests"php scr!p" "o pass "he Oracle en&!ronmen" correc"l)
Caria/les$order * "-YE47"
Th!s change can be re&er"ed la"er.
1H. ;d!" ext;oci/;tests;details"inc and se" "he 4M4T;M pass+ord and connec"!on s"r!ng "o our
Oracle da"abase.
1O. Tes" "he PHP command?l!ne b!nar)
) make test
1P. :' all !s O6, "hen !ns"all "he PHP b!nar!es)
) make install
The !ns"alla"!on cop!es "he b!nar!es and upda"es J-O2(.G=(.FE=PA)H;httpd"con*,
au"oma"!call add!ng "he l!ne)
11
'nstalling .C'1 With .racle HTT! #er$er
KoadNodule php5$module li/e.ec/li/php5.so
1$. ;d!" J-O2(.G=(.FE=PA)H;httpd"con* and add "he l!nes)
<AilesNatch 2.php)
7et>andler application/.-httpd-php
</AilesNatch
1L. Res"ar" OH4)
) )3B64K-$5M7:6M4-//in/opmnctl startproc ias-component*ohs1
In!talling OCI. With Oracle HTTP Ser-er 1/g on 'inu
Oracle !ncluded PHP +!"h !"s m!d?"!er %ppl!ca"!on 4er&er 10g Release I, g!&!ng an ou"?o'?"he?
bo/ me"hod o' us!ng "he same +eb ser&er 'or PHP and 'or *2;; appl!ca"!ons.
,ers!on 10.1.I.0 o' "he %ppl!ca"!on 4er&er C%4F comes +!"h PHP J.I.11. The %4 10.1.I.2
pa"chse" adds PHP H.1.2. To use a d!''eren" &ers!on o' PHP ou ma be able "o comp!le our
o+n PHP release us!ng "hese s"eps. The same ca&ea"s abou" chang!ng %4 e/!s" as 'or &ers!on
11.
% pre&!ous !ns"alla"!on o' %4 10.1.I !s assumed !n "he s"eps belo+. To upgrade "he &ers!on
o' PHP !n "h!s !ns"alla"!on)
1. .og on as "he oracle user and shu" do+n "he Oracle HTTP 4er&er)
) )3B64K-$>3N-/opmn//in/opmnctl stopproc ias-component*>::E$7erCer
2. Change "o "he home d!rec"or)
) cd )>3N-
I. 4e" "he OR%C.;NHOM; en&!ronmen" &ar!able "o our %4 !ns"all d!rec"or)
) e.port 3B64K-$>3N-*)>3N-/product/10.1.@/3racle67$1
J. Do+nload "he Oracle 10g or 11g -as!c and 4D6 :ns"an" Cl!en" 9:P pac(ages 'rom "he
:ns"an" Cl!en" page on "he Oracle Technolog 7e"+or()
http://www.oracle.com/technolog#/tech/oci/instantclient/instantclient.html
H. ;/"rac" "he 9:P '!les, 'or e/ample, !' on a I2?b!" .!nu/)
) unXip /asic-linu.-10.2.0.5.0.Xip
) unXip sdk-linu.-10.2.0.5.0.Xip
O. Change "o "he :ns"an" Cl!en" d!rec"or and smbol!call l!n( libclntsh"so"&A"& "o
libclntsh"so)
) cd instantclient$10$2
) ln -s li/clntsh.so.10.1 li/clntsh.so
The :ns"an" Cl!en" RPMs could also be used, !n +h!ch case "h!s las" s"ep !s unnecessar.
12
'nstalling and ConAiguring !H!
-e +ar o' ha&!ng :ns"an" Cl!en" in ;etc;ld"so"con* s!nce :ns"an" Cl!en" l!brar!es can
cause con'l!c"s +!"h %4. The op+nctl "ool ma 'a!l +!"h "he error !ain' 2FS
.nitialiation (ailedPP"
P. Do+nload PHP 'rom http://php.net/downloads.php and e/"rac" "he '!le "o a +or(!ng
d!rec"or, 'or e/ample +!"h PHP H.2.P)
) tar -W.' php-5.2.1U.tar./X2
$. ;d!" JO:A-FE=HO!E;Apache;Apache;con*;httpd"con* and commen" ou" "he PHP
Foad!odule l!ne b pre'!/!ng !" +!"h Q)
Q KoadNodule phpD$module li/e.ec/li/phpD.so
:' ou had enabled PHP H 'or %4 10.1.I.2, "he commen"ed l!ne should be)
Q KoadNodule php5$module li/e.ec/li/php5.so
L. -ac( up "he libphp5"so or libphp4"so l!brar !n JO:A-FE=HO!E;Apache;Apache;libexec
s!nce !" +!ll be replaced.
10. 4e" en&!ronmen" &ar!ables re>u!red 'or "he bu!ld "o comple"e)
) e.port E-BK5K5I*)3B64K-$>3N-/perl/li/
) e.port KL$K5IB6B;$E6:>*)3B64K-$>3N-/li/:)KL$K5IB6B;$E6:>
) e.port 4AK6Y7*-LK5MR,
There !s no need "o se" C2.%34 !' ou ha&e %4 10.1.I.2. :" !s needed +!"h %4 10.1.I.0 "o
a&o!d a dupl!ca"e pro"o"pe error +!"h gethostna+eNO "ha" resul"s !n comp!la"!on 'a!lure.
11. Con'!gure PHP)
) cd php-5.2
) ./con'igure 2
--pre'i.*)3B64K-$>3N-/php 2
--with-con'ig-'ile-path*)3B64K-$>3N-/6pache/6pache/con' 2
--with-ap.s*)3B64K-$>3N-/6pache/6pache//in/ap.s 2
--with-oci8*instantclient+)>3N-/instantclient$10$2
0!"h %4 10.1.2 and older :ns"an" Cl!en" releases, some users also spec!' 33disable3rpath"
12. Ma(e PHP)
) make
1I. Tes" "he PHP command?l!ne b!nar)
) make test
1J. :' all !s O6, "hen !ns"all PHP)
) make install
The !ns"alla"!on cop!es "he b!nar!es and upda"es
JO:A-FE=HO!E;Apache;Apache;con*;httpd"con*, au"oma"!call add!ng "he l!ne)
23
'nstalling .C'1 With .racle HTT! #er$er
KoadNodule php5$module li/e.ec/li/php5.so
1H. -ac( up and upda"e JO:A-FE=HO!E;Apache;Apache;con*;php"ini +!"h op"!ons 'or PHP H,
'or e/ample all "he ne+ OC:$ d!rec"!&es. Re'er "o php"ini3reco++ended 'or ne+ op"!ons.
Par"!cularl !' ou are us!ng PHP H.I, se" "he date"ti+eone d!rec"!&e "o our "!me1one, 'or
e/ample)
date.timeXone * 6merica/Kos$6ngeles
4ee http://php.net/manual/en/timeXones.php 'or "he a&a!lable &alues.
1O. The Oracle HTTP 4er&er can no+ be res"ar"ed)
) )3B64K-$>3N-/opmn//in/opmnctl startproc ias-component*>::E$7erCer
Rem!nder) "hese s"eps !n&al!da"e all suppor" 'or %4, no" 8us" 'or "he PHP componen", and "he
should no" be used !n produc"!on en&!ronmen"s.
The Oracle HTTP 4er&er documen" roo" !s
)3B64K-$>3N-/6pache/6pache/htdocs
CMes, Apache !s repea"ed "+!ceF. 2!les +!"h "php e/"ens!ons !n "h!s d!rec"or +!ll be e/ecu"ed b
PHP. 2!les +!"h a "phps e/"ens!on +!ll be d!splaed as 'orma""ed source code.
In!talling the P#O Eten!ion
The PDONOC: dr!&er 'or PHPAs PDO e/"ens!on !s a separa"e !n"er'ace "o "he Oracle Da"abase.
Us!ng !" !s no" recommend bu" ou ma +!sh "o e/per!men" +!"h !". PDONOC: m!sses some
&er !mpor"an" scal!ng and per'ormance 'ea"ures a&a!lable !n OC:$, !" !snA" s"able, and
curren"l !" has no ma!n"a!ner.
To use PDONOC: +!"h Oracle, !ns"all "he PDO e/"ens!on and "he PDONOC: da"abase dr!&er.
The PDO e/"ens!on and dr!&ers are !ncluded !n PHP 'rom release H.1.
Mou can !ns"all PDONOC: and OC:$ a" "he same "!me b comb!n!ng "he appropr!a"e op"!ons
"o con*igure. 7o PHP code !s shared b "he OC:$ e/"ens!on and PDONOC: dr!&er.
In!talling P#OAOCI on 'inu
The s"eps sho+n belo+ sho+ comp!l!ng PDO 'or PHP H.J on Oracle .!nu/. Th!s procedure
+or(s 'or all &ers!ons o' PHP a'"er release H.1.
1. Do+nload PHP H.J.J 'rom http://php.net/downloads.php.
2. .og !n as "he root user and e/"rac" "he PHP source code us!ng "he 'ollo+!ng commands)
Q tar -W.' php-5.D.D.tar./X2
Q cd php-5.D.D
:' ou do+nloaded "he "tar"g '!le, e/"rac" !" +!"h tar -X.'.
I. Con'!gure PHP +!"h op"!ons l!(e)
2&
'nstalling and ConAiguring !H!
Q e.port 3B64K-$>3N-*/u01/app/oracle/product/11.2.0/.e
Q ./con'igure 2
--with-ap.s2*/usr/s/in/ap.s 2
--ena/le-pdo 2
--with-pdo-oci*)3B64K-$>3N-
7o"e "here !s no D$E !n "he 33,ith3pdo3oci op"!on name. Re&!e+ "he ou"pu" o' con*igure and
chec( "ha" "he e/"ens!on +as enabled success'ull be'ore con"!nu!ng.
:' ou +an" "o bu!ld PDONOC: +!"h "he Oracle :ns"an" Cl!en" RPMs, change "he 33,ith3pdo3
oci op"!on "o)
--with-pdo-oci*instantclient+/usr+11.2
Th!s !nd!ca"es "o use "he :ns"an" Cl!en" !n ;usr;lib;oracle;&&"2.
:' :ns"an" Cl!en" 9:P '!les are used, "he op"!on should be, 'or e/ample)
--with-pdo-oci*instantclient+/opt/instantclient$11$2+11.2
The "ra!l!ng &ers!on number !n "h!s command 'or 9:P !ns"alls o' :ns"an" Cl!en" !s onl used
'or san!" chec(!ng and d!spla purposes.
0!"h :ns"an" Cl!en" 9:P '!les, !' "he error .%+ too du+b to *igure out ,here the libraries are
in your .nstant -lient install !s sho+n !" means "he smbol!c l!n( 'rom libclntsh"so "o
libclntsh"so"&&"& Cor "he appropr!a"e &ers!onF !s m!ss!ng. Th!s l!n( needs "o be manuall
crea"ed 'or "he 9:P '!le !ns"all.
J. -u!ld and !ns"all PHP.
Q make
Q make install
H. 2ollo+!ng s"eps s!m!lar "o "he pre&!ous OC:$ sec"!ons "o crea"e "he php"ini con'!gura"!on
'!le and con'!gure "he Oracle en&!ronmen" 'or %pache.
In!talling P#OAOCI on Windo;!
:' ou +an" "o use "he PDONOC: dr!&er 'or "he PDO e/"ens!on 'ollo+ "he pre&!ous s"eps 'or
!ns"all!ng OC:$ on 0!ndo+s and add "he e/"ens!on "o php"ini)
e.tension*php$pdo$oci.dll
Mou can ha&e bo"h PDONOC: and OC:$ enabled "oge"her.
Chec=ing OCI. and P#OAOCI In!tallation
To con'!rm PHP +as !ns"alled correc"l, crea"e a scr!p" phpin*o"php "ha" sho+s "he PHP
con'!gura"!on se""!ngs. The '!le should be !n a d!rec"or %pache can read, such as "he
documen" roo". Th!s !s spec!'!ed b "he Documen"Roo" se""!ng !n "he httpd"con* '!le. On Oracle
.!nu/ "he d!rec"or !s ;var;,,,;ht+l.
Script 9' phpin*o"php
<?php
2(
Checking .C'1 and !D.C.C' 'nstallation
phpin'o%&!
?
.oad "he scr!p" !n our bro+ser us!ng http';;localhost;phpin*o"php. %l"erna"!&el, "he scr!p" can
be run !n a "erm!nal +!ndo+ +!"h command l!ne PHP, a'"er add!ng "he d!rec"or con"a!n!ng
PHP "o our P%TH en&!ronmen" &ar!able, and add!ng "he Oracle l!brar d!rec"or "o
.DN.:-%R%MNP%TH 'or .!nu/)
) php phpin'o.php
or ou could s!mpl run
) php -i
:' ou ha&e more "han one &ers!on o' PHP on our ss"em be+are "he ou"pu" !n a bro+ser and
'rom "he command l!ne m!gh" be d!''eren".
:n "he ou"pu", chec( "he Foaded -on*iguration (ile en"r sho+s "he php"ini "ha" "he
pre&!ous !ns"alla"!on s"eps crea"ed.
The ;n&!ronmen" sec"!on should sho+ "he Oracle en&!ronmen" &ar!ables. 4ee Setting the
Oracle Environ+ent on Finux earl!er !n "h!s chap"er.
:' OC:$ +as !ns"alled, "here +!ll be a sec"!on 'or !")
The parame"er &alues are d!scussed !n la"er chap"ers.
:' PDONOC: +as !ns"alled, !"s con'!gura"!on sec"!on +!ll loo( l!(e)
2)
(igure 45' phpin*oNO output ,hen O-./ is enabled"
'nstalling and ConAiguring !H!
The chap"er -onnecting to Oracle #sing O-./ sho+s ho+ "o use OC:$ "o connec" "o Oracle
Da"abase.
2*
(igure 44' phpin*oNO ,hen PDO=O-. is enabled"
CH,PTE: %
INST,''ING PHP ,N# ,P,CHE ON
O:,C'E SO',:IS
Th!s chap"er d!scusses !ns"all!ng %pache and PHP :P4 pac(ages on Oracle 4olar!s 11.1. 4olar!s
!ncludes %pache 2.2, PHP H.2 and PHP H.I :P4 pac(ages, along +!"h se&eral PHP e/"ens!ons.
PHP !s curren"l onl a&a!lable 'or I2?b!".
%" "!me o' +r!"!ng, no :P4 pac(ages are a&a!lable 'or Oracle :ns"an" Cl!en" or PHP OC:$ so
"he mus" be !ns"alled manuall. Chec( OT7 'or "he la"es" !n'orma"!on,
http://www.oracle.com/technetwork/serCer-storage/solaris11/oCerCiew/inde..html
Oracle Da"abase =; !s no" a&a!lable on 4olar!s, bu" ou can !ns"all and connec" "o ano"her
ed!"!on o' Oracle, or connec" "o a da"abase on a d!''eren" mach!ne.
In!talling ,pache on Oracle Solari! 11.1
The %pache +ebser&er can be !ns"alled 'rom an :P4 repos!"or. To !ns"all %pache, 'ollo+ "hese
s"eps)
O. Chec( "ha" a 4olar!s :P4 repos!"or !s con'!gured. 2or e/ample)
) pkg pu/lisher
ERIK57>-B :;E- 7:6:R7 E K346:53M
solaris origin online A
http://ipkg.us.oracle.com/solaris11/release/
P. Chec( !' %pache !s alread !ns"alled)
) pkg in'o apache-22
Mame: we//serCer/apache-22
7ummar#: 6pache ?e/ 7erCer Z2.2
Lescription: :he 6pache >::E 7erCer Zersion 2.2
4ategor#: ?e/ 7erCices/6pplication and ?e/ 7erCers
7tate: 5nstalled
Eu/lisher: solaris
Zersion: 2.2.22
Iuild Belease: 5.11
Iranch: 0.1U5.1.0.0.2D.0
Eackaging Late: 6ugust 20+ 2012 0@:@D:D5 EN
7iXe: 9.15 NI
ANB5: pkg://solaris/we//serCer/apache-22O2.2.22+5.11-
0.1U5.1.0.0.2D.0:20120820:15@DD5]
Commonl %pache +!ll be presen", so "he ne/" s"ep can be s(!pped.
$. :' %pache !s no" !ns"alled, "hen !ns"all !" us!ng "he appropr!a"e pr!&!leges, 'or e/ample +!"h
su, sudo, or p*exec)
Q pkg install we//serCer/apache-22
2+
'nstalling !H! and Apache on .racle #olaris
L. %pache can be s"ar"ed +!"h)
Q sCcadm ena/le apache22
10. To shu" %pache do+n, d!sable !" +!"h)
Q sCcadm disa/le apache22
11. The s"a"us o' %pache can be chec(ed +!"h)
Q sCcs apache22
7:6:- 7:5N- ANB5
disa/led 15:DD:11 sCc:/network/http:apache22
:' %pache !s runn!ng, !"s 4T%T; +!ll be online"
In!talling PHP on Oracle Solari! 11.1
Oracle 4olar!s 11.1 curren"l !ncludes PHP &ers!ons H.2 and H.I. ;!"her or bo"h ma be
!ns"alled, ho+e&er onl one o' "hem can be used b %pache a" an one "!me. 4olar!s 11.0 onl
has PHP H.2 :P4 pac(ages.
1. To '!nd all o' PHPAs :P4 pac(ages !n "he remo"e repos!"or do)
) pkg search -o pkg.name -r pkg.'mri:we//phpJ 3B 2
pkg.'mri:we//serCer/JphpJ
EGY.M6N-
we//php-52
we//php-52/documentation
we//php-52/e.tension/php-apc
we//php-52/e.tension/php-idn
we//php-52/e.tension/php-memcache
we//php-52/e.tension/php-m#s"l
we//php-52/e.tension/php-pear
we//php-52/e.tension/php-suhosin
we//php-52/e.tension/php-tcpwrap
we//php-52/e.tension/php-.de/ug
we//php-5@
we//php-5@/documentation
we//php-5@/e.tension/php-apc
we//php-5@/e.tension/php-idn
we//php-5@/e.tension/php-memcache
we//php-5@/e.tension/php-m#s"l
we//php-5@/e.tension/php-pear
we//php-5@/e.tension/php-suhosin
we//php-5@/e.tension/php-tcpwrap
we//php-5@/e.tension/php-.de/ug
we//php-common
we//serCer/apache-22/module/apache-php5
we//serCer/apache-22/module/apache-php52
we//serCer/apache-22/module/apache-php5@
2. :ns"all PHP H.I +!"h p1g us!ng appropr!a"e pr!&!leges such as &!a su, sudo, or p*exec)
2-
'nstalling !H! on .racle #olaris &&D&
Q pkg install we//php-5@ we//serCer/apache-22/module/apache-php5@
Eackages to install: 10
Eackages to update: 1
Nediators to change: 1
4reate /oot enCironment: Mo
4reate /ackup /oot enCironment: Mo
L3?MK36L EGY7 A5K-7 ,A-B %NI&
7E--L
4ompleted 11/11 P0P/P0P 22.2/22.2
2.0N/s
E>67- 5:-N7
BemoCing old actions 1/1
5nstalling new actions 9P2/9P2
Rpdating package state data/ase Lone
Rpdating image state Lone
4reating 'ast lookup data/ase Lone
I. 4!m!larl, PHP H.2 pac(ages can be !ns"alled +!"h)
Q pkg install we//php-52 we//serCer/apache-22/module/apache-php52
J. Re&!e+ all "he PHP pac(ages !ns"alled)
Q pkg list 0JphpJ0
M6N- %ERIK57>-B& Z-B753M 5A3
we//php-52 5.2.1U-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-apc @.0.19-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-idn 0.2.0-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-memcache 2.2.5-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-m#s"l 5.2.1U-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-pear 5.2.1U-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-suhosin 0.9.29-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-tcpwrap 1.1.@-0.1U5.1.0.0.2D.0 i--
we//php-52/e.tension/php-.de/ug 2.0.5-0.1U5.1.0.0.2D.0 i--
we//php-5@ 5.@.1D-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-apc @.1.9-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-idn 0.2.0-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-memcache @.0.P-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-m#s"l 5.@.1D-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-pear 5.@.1D-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-suhosin 0.9.@@-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-tcpwrap 1.1.@-0.1U5.1.0.0.2D.0 i--
we//php-5@/e.tension/php-.de/ug 2.2.0-0.1U5.1.0.0.2D.0 i--
we//php-common 11.1-0.1U5.1.0.0.2D.0 i--
we//serCer/apache-22/module/apache-php52 5.2.1U-0.1U5.1.0.0.2D i--
we//serCer/apache-22/module/apache-php5@ 5.@.1D-0.1U5.1.0.0.2D i--
H. %s re>u!red !n PHP H.I, ed!" ;etc;php;4"6;php"ini and se" "he "!me1one, 'or e/ample)
date.timeXone * 6merica/Kos$6ngeles
4ee http://php.net/manual/timeXones.php 'or a&a!lable &alues.
O. 4"ar" %pache)
20
'nstalling !H! and Apache on .racle #olaris
Q sCcadm ena/le apache22
P. Con'!rm %pache s"ar"ed +!"h)
Q sCcs apache22
7:6:- 7:5N- ANB5
online 15:D@:01 sCc:/network/http:apache22
$. Chec( PHPAs con'!gura"!on +!"h "he command l!ne)
) php -i
%l"erna"!&el crea"e a scr!p" !n "he +ebser&er documen" roo" d!rec"or,
;var;apache2;2"2;htdocs;phpin*o"php)
<?php
phpin'o%&!
?
7o+, !n a +eb bro+ser, open "he UR. http://localhost/phpin'o.php" :' PHP !s
!ns"alled, "he ou"pu" +!ll sho+ "he &ers!on o' PHP and "he e/"ens!ons "ha" are
con'!gured.
Changing the <er!ion o* PHP u!ed $6 ,pache
:' more "han one &ers!on o' PHP !ns"alled, ou can choose +h!ch one !s used b %pache. To see
"he curren" &ers!on o' PHP use phpin'o%& or "he pac(age med!a"or command)
) pkg mediator
N-L56:3B Z-B. 7B4. Z-B753M 5NEK. 7B4. 5NEK-N-M:6:53M
WaCa s#stem 1.U s#stem
php s#stem 5.@ s#stem
p#thon Cendor 2.P Cendor
Th!s e/ample sho+s "ha" %pache !s us!ng PHP H.I.
To see all "he poss!ble &alues 'or "he pac(age med!a"or)
) pkg mediator -a
N-L56:3B Z-B. 7B4. Z-B753M 5NEK. 7B4. 5NEK-N-M:6:53M
WaCa s#stem 1.P s#stem
WaCa s#stem 1.U s#stem
php s#stem 5.2 s#stem
php s#stem 5.@ s#stem
p#thon Cendor 2.P Cendor
To change "he &ers!on o' PHP used b %pache, '!rs" d!sable %pache)
Q sCcadm disa/le apache22
Then s+!"ch "o PHP H.2)
Q pkg set-mediator -Z 5.2 php
Res"ar" %pache)
21
Changing the @ersion oA !H! used 5y Apache
Q sCcadm ena/le apache22
In!talling Oracle In!tant Client on Oracle Solari! 11.1
Oracle cl!en" l!brar!es mus" be a&a!lable 'or OC:$. :' "here !s no Oracle Da"abase !ns"alled on
our mach!ne, !ns"all "he l!gh"+e!gh" Oracle :ns"an" Cl!en")
1. Do+nload "he Oracle :ns"an" Cl!en" 'or 4olar!s I2?b!" 'rom OT7, choos!ng 4P%RC or /$O as
appropr!a"e) http://www.oracle.com/technetwork/data/ase/'eatures/instant-
client/inde.-09UD80.html
:ns"all "he instantclient3basic3solaris and instantclient3sd13solaris pac(ages.
%l"erna"!&el, !ns"ead o' "he Dbas!cE pac(age, ou can !ns"all instantclient3basiclite3
solaris.
2. Un1!p "he pac(ages !n"o ;opt;instantclient=&&=2, 'or e/ample)
Q cd /opt
Q unXip instantclient-/asic-solaris.sparc@2-11.2.0.@.0.Xip
Q unXip instantclient-sdk-solaris.sparc@2-11.2.0.@.0.Xip
I. Crea"e a smbol!c l!n( 'or "he cl!en" shared l!brar)
Q cd /opt/instantclient$11$2
Q ln -s li/clntsh.so.11.1 li/clntsh.so
The '!nal d!rec"or laou" 'or "he Dbas!cE and Dsd(E pac(ages should loo( l!(e)
Q ls /opt/instantclient$11$2
adrci li/clntsh.so.11.1 li/ociWd/c11.so uidrCci
I6754$B-6LN- li/nnX11.so oWd/c5.War .streams.War
geneXi li/occi.so.11.1 oWd/cP.War
li/clntsh.so li/ociei.so sdk
In!talling OCI. on Oracle Solari! 11.1
The OC:$ e/"ens!on can be !ns"alled 'rom P;C. as a shared extens!on.
1. Ma(e sure autocon* and syste+;header are !ns"alled.
Q pkg install autocon'
Q pkg install s#stem/header
2. % C comp!ler !s needed "o bu!ld OC:$. :ns"all 4olar!s 4"ud!o b do+nload!ng !" and 'ollo+!ng
"he documen"a"!on)
http://www.oracle.com/technetwork/inde.es/downloads/inde..htmlQtools
:' necessar, add "he 4olar!s 4"ud!o b!nar d!rec"or "o our P%TH, 'or e/ample,
Q e.port E6:>*)E6:>:2
/opt/7olaris7tudio12.@-solaris-.8P-/in/solarisstudio12.@//in
4olar!s 4"ud!o !s pre'erred because o' !"s op"!m!1a"!ons bu" ou could al"erna"!&el,
!ns"all 3CC)
22
'nstalling !H! and Apache on .racle #olaris
Q pkg install gcc-deC
I. 4hu"do+n %pache)
Q sCcadm disa/le apache22
J. :' ou are beh!nd a '!re+all, se" "he P;%R pro/ +h!ch !s used b P;C.. 2or e/ample)
Q /usr/php//in/pear con'ig-set http$pro.# http://#our-pro.#.com:80
H. Do+nload and !ns"all OC:$)
Q /usr/php//in/pecl install oci8
0hen promp"ed 'or "he pa"h "o OR%C.;NHOM; respond +!"h "he 'ull pa"h "o "he
Oracle home d!rec"or or, !' ou !ns"alled Oracle :ns"an" Cl!en", en"er
instantclient+/opt/instantclient$11$2. 7o"e "he !ns"aller +!ll no" e/pand
en&!ronmen" &ar!ables !n our response.
O. 2or PHP H.I ed!" ;etc;php;4"6;php"ini and add)
e.tension*oci8.so
:' ou !ns"alled PHP H.2 "hen add "h!s d!rec"!&e "o ;etc;php;4"2;php"ini"
P. 4e" an re>u!red en&!ronmen" &ar!ables, such as .DN.:-R%RMNP%TH, !n our shell. 2or
%pache "he &ar!ables mus" be se" !n ;etc;apache2;2"2;envvars'
e.port KL$K5IB6B;$E6:>*/opt/instantclient$11$2
4ee Setting the Oracle Environ+ent 7ariables on Finux !n "he pre&!ous chap"er. Oracle
4olar!s uses s!m!lar &ar!ables as .!nu/, such as 7.4N.%73 and T74N%DM:7.
$. Res"ar" %pache)
Q sCcadm ena/le apache22
Call!ng "he pre&!ous phpin*o"php scr!p" +!ll sho+ "he OC:$ e/"ens!on and !"s op"!ons. The
&ar!able .DN.:-R%RMNP%TH should be seen !n "he Environ+ent sec"!on.
Mou can remo&e "he OC:$ e/"ens!on b re&er"!ng "he e/"ens!on en"r !n php"ini and
phs!call remo&!ng "he e/"ens!on +!"h)
Q /usr/php//in/pecl uninstall oci8
The ne/" chap"er sho+s ho+ "o use OC:$ "o connec" "o Oracle Da"abase.
&33
CH,PTE: 1/
CONNECTING TO O:,C'E 0SING OCI.
Th!s chap"er co&ers connec"!ng "o an Oracle da"abase 'rom our PHP appl!ca"!on, sho+!ng "he
'orms o' Oracle connec"!on and ho+ "o "une "hem. % la"er chap"er PHP -onnection Pooling
and High Availability d!scusses connec"!on pool!ng and ho+ !" appl!es "o connec"!on
managemen".
-e'ore a""emp"!ng "o connec", re&!e+ "he sec"!on Setting the Oracle Environ+ent on Finux
!n Chap"er $ and ma(e sure "ha" our en&!ronmen" !s con'!gured appropr!a"el.
The e/amples use "he Dhuman resourcesE HR schema, a demons"ra"!on user accoun"
!ns"alled +!"h "he da"abase. Use 4B.SPlus "o unloc( "he accoun" and se" a pass+ord, as
descr!bed !n "he chap"er SEF With Oracle Database"
Depend!ng on "he &ers!on o' "he Oracle Cl!en" l!brar!es "ha" OC:$ !s l!n(ed +!"h, ou can
connec" "o &ar!ous &ers!ons o' Oracle Da"abase. Oracle 4uppor" 7o"e 20PI0I.1 de"a!ls "he 'ull
Oracle cl!en"?ser&er compa"!b!l!" ma"r!/.
Oracle Connection Ea1ple
Once ou ha&e !ns"alled PHP OC:$, %pache, and ha&e "he creden"!als "o access a local or
remo"e da"abase, "hen ou can "es" an OC:$ scr!p". Crea"e oci/"php !n %pacheAs
Documen"Roo" d!rec"or, +here ou crea"ed phpin*o"php !n "he pre&!ous chap"er)
Script ?' oci/"php
<?php
)c * oci$pconnect%"hr"+ "welcome"+ "localhost/,-"&!
i' %8)c& (
)e * oci$error%&!
trigger$error%04ould not connect to data/ase: 0. )e90message0<+-$R7-B$-BB3B&!
=
)s * oci$parse%)c+ "select cit# 'rom locations order /# cit#"&!
i' %8)s& (
)e * oci$error%)c&!
trigger$error%04ould not parse statement: 0. )e90message0<+ -$R7-B$-BB3B&!
=
)r * oci$e.ecute%)s&!
i' %8)r& (
)e * oci$error%)s&!
trigger$error%04ould not e.ecute statement: 0. )e90message0<+ -$R7-B$-BB3B&!
=
echo "<ta/le /order*0102n"!
)ncols * oci$num$'ields%)s&!
echo "<tr2n"!
'or %)i * 1! )i <* )ncols! HH)i& (
)colname * oci$'ield$name%)s+ )i&!
echo " <th</".htmlentities%)colname+ -M:$SR3:-7&."<//</th2n"!
&3&
Connecting to .racle Bsing .C'1
=
echo "</tr2n"!
while %%)row * oci$'etch$arra#%)s+ 345$67734H345$B-:RBM$MRKK7&& 8* 'alse& (
echo "<tr2n"!
'oreach %)row as )item& (
echo " <td".%)item8**null?htmlentities%)item+
-M:$SR3:-7&:"^n/sp!"&."</td2n"!
=
echo "</tr2n"!
=
echo "</ta/le2n"!
?
The scr!p" connec"s as "he HR user "o "he local !ns"alla"!on o' Oracle 11g =;. The pass+ord !s
D+elcomeE. .oad !" !n a bro+ser +!"h) http';;localhost;oci/"php" The ou"pu" !s l!(e)
:' ou ha&e errors, read 'ur"her !n "h!s chap"er abou" connec"!ons and "roubleshoo"!ng.
Oracle Connection T6pe!
There are "hree +as "o connec" "o an Oracle da"abase !n a PHP appl!ca"!on) us!ng s"andard
connec"!ons, un!>ue connec"!ons, or pers!s"en" connec"!ons. ;ach me"hod re"urns a
connec"!on resource "ha" !s used !n subse>uen" OC:$ calls.
&3(
(igure 49' Output *ro+ oci/"php"
.racle Connection Types
:ndependen" o' +h!ch one o' "hese PHP connec"!on me"hods are used !n appl!ca"!ons, "he
da"abase ser&er can be con'!gured "o handle !"s end o' "he connec"!on !n d!''eren" +as. The
bes" prac"!ce 'or mos" PHP +eb appl!ca"!ons !s 'or "he da"abase "o use Da"abase Res!den"
Connec"!on Pool!ng CDRCPF connec"!on pool!ng. Th!s !s d!scussed !n "he chap"er PHP
-onnection Pooling and High Availability"
Standard Connection!
2or bas!c connec"!on "o Oracle use PHPKs oci$connect%& call)
)c * oci$connect%)username+ )password+ )d/name&!
Mou can call oci$connect%& more "han once !n a scr!p". :' ou do "h!s and use "he same
connec"!on de"a!ls, "hen ou ge" a po!n"er "o "he or!g!nal connec"!on.
0niBue Connection!
To ge" a "o"all !ndependen" connec"!on use oci$new$connect%&)
)c * oci$new$connect%)username+ )password+ )d/name&!
;ach connec"!on !s separa"e 'rom an o"her. Th!s le"s ou ha&e more "han one da"abase
sess!on open a" "he same "!me, +h!ch !s use'ul +hen ou +an" "o do da"abase opera"!ons
!ndependen"l 'rom each o"her.
Per!i!tent Connection!
Pers!s"en" connec"!ons can be made +!"h oci$pconnect%&)
)c * oci$pconnect%)username+ )password+ )d/name&!
Pers!s"en" connec"!ons are no" au"oma"!call closed a" "he end o' a PHP scr!p" +hen "he HTTP
re>ues" '!n!shes. The rema!n open !n PHPKs pers!s"en" connec"!on cache 'or reuse b la"er
scr!p"s. Th!s ma(es oci$pconnect%& 'as" 'or 're>uen"l used +eb appl!ca"!ons. Reconnec"!on
does no" re>u!re re?au"hen"!ca"!on "o "he da"abase.
;ach cache en"r uses "he da"abase username, "he da"abase connec" s"r!ng, "he hashed
pass+ord, "he charac"er se" and "he connec"!on pr!&!lege "o ensure reconnec"!on !n la"er Cor
"he sameF PHP scr!p"s reuses "he correc" cached da"abase connec"!on.
&3)
Connecting to .racle Bsing .C'1
.!m!"s on "he number o' pers!s"en" connec"!ons !n "he cache can be se", and connec"!ons can
be au"oma"!call e/p!red "o 'ree up resources. The parame"ers 'or "un!ng pers!s"en"
connec"!ons are d!scussed la"er !n "h!s chap"er.
0hen "he PHP process "erm!na"es, "he connec"!on cache !s des"roed and all da"abase
connec"!ons closed. Th!s means "ha" 'or command l!ne PHP scr!p"s, pers!s"en" connec"!ons are
e>u!&alen" "o normal connec"!ons and "here !s no per'ormance bene'!".
:' "he da"abase !s shu"do+n +!"h "he 7ORM%. op"!on, "he shu"do+n +!ll hang un"!l all
da"abase connec"!ons are closed. :' pers!s"en" connec"!ons ha&e been used !n PHP, %pache
+!ll '!rs" need "o be shu"do+n "o close "hose connec"!ons.
Oracle #ata$a!e Na1e Connection Identi*ier!
The )d/name connec"!on !den"!'!er !s "he name o' "he local or remo"e da"abase "ha" ou +an"
"o a""ach "o. :" !s !n"erpre"ed b Oracle 7e", "he componen" o' Oracle "ha" handles "he
underl!ng connec"!on "o "he da"abase and es"abl!shes a connec"!on "hrough "o "he ne"+or(
Dl!s"enerE on "he da"abase ser&er. The connec"!on !den"!'!er can be one o')
%n ;as Connec" s"r!ng
% Connec" Descr!p"or s"r!ng
% Connec" 7ame
Ea!6 Connect String
:' ou are runn!ng Oracle Da"abase =; on a mach!ne called +y+achine, ou could connec" "o
"he HR schema +!"h)
)c * oci$connect%0hr0+ 0welcome0+ 0m#machine/,-0&!
:n "h!s gu!de, +e assume "he da"abase !s on "he same mach!ne as %pache and PHP so +e use
localhost)
&3*
(igure 4?' Persistent connections are cached in PHP and held open to
the database ,hen the ,eb user is idle"
.racle Data5ase Name Connection 'dentiAiers
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
Depend!ng on our ne"+or( con'!gura"!on, ou ma need "o use "he e>u!&alen" :P address)
)c * oci$connect%0hr0+ 0welcome0+ 012U.0.0.1/,-0&!
The ;as Connec" s"r!ng !s *D-C?l!(e. The Oracle 10g sn"a/ !s)
9//<host$name9:port<9/serCice$name<
:' "he PHP b!nar !s l!n(ed +!"h Oracle 11g cl!en" l!brar!es, "he enhanced 11g sn"a/ can be
used)
9//<host$name9:port<9/serCice$name<9:serCer$t#pe<9/instance$name<
The pre'!/ // !s op"!onal. The por" number de'aul"s "o OracleKs s"andard por", 1H21. The
ser&!ce name de'aul"s "o "he same name as "he da"abaseAs hos" compu"er name. The ser&er
!s "he "pe o' process "ha" Oracle uses "o handle "he connec"!on, see "he chap"er PHP
-onnection Pooling and High Availability co&er!ng Da"abase Res!den" Connec"!on Pool!ng 'or
an e/ample. The !ns"ance name !s used +hen connec"!ng "o a spec!'!c mach!ne !n a clus"ered
en&!ronmen".
0h!le !" !s common 'or Oracle da"abase s!"es "o use por" 1H21, !" !s rela"!&el rare "ha" a
da"abase +!ll be !ns"alled +!"h "he ser&!ce name se" "o "he hos" name. Mou +!ll mos"l need "o
spec!' "he connec"!on !den"!'!er as host=na+e;service=na+e"
The lsnrctl command on "he da"abase ser&er sho+s "he ser&!ce names "ha" "he Oracle 7e"
l!s"ener accep"s re>ues"s 'or. The e/ample belo+ sho+s "he ser&!ce =; !s a&a!lable.
) lsnrctl serCices
K7MB4:K 'or Kinu.: Zersion 11.2.0.2.0 - Eroduction on 05-Tun-2011 1P:2D:52
4op#right %c& 1991+ 2011+ 3racle. 6ll rights reserCed.
4onnecting to %L-74B5E:53M*%6LLB-77*%EB3:343K*5E4&%G-;*-,:EB34$A3B$,-&&&
7erCices 7ummar#...
7erCice "EK7-.tEroc" has 1 instance%s&.
5nstance "EK7-.tEroc"+ status RMGM3?M+ has 1 handler%s& 'or this serCice...
>andler%s&:
"L-L546:-L" esta/lished:0 re'used:0
K346K 7-BZ-B
Service "XE" has 1 instance(s).
5nstance ",-"+ status B-6L;+ has 1 handler%s& 'or this serCice...
>andler%s&:
"L-L546:-L" esta/lished:18 re'used:0 state:read#
K346K 7-BZ-B
. . .
More !n'orma"!on on "he sn"a/ can be 'ound !n "he OracleQ Database 2et Services
Ad+inistrator%s Guide &&g :elease 2 N&&"2O.
#ata$a!e Connect #e!criptor String
The 'ull Oracle 7e" connect descriptor s"r!ng g!&es "o"al 'le/!b!l!" o&er "he connec"!on.
)d/ * 0%L-74B5E:53M *
&3+
Connecting to .racle Bsing .C'1
%6LLB-77 * %EB3:343K * :4E&
%>37: * m#machine.m#domain&%E3B: * 1521&&
%43MM-4:$L6:6 *
%7-BZ-B * L-L546:-L&
%7-BZ54-$M6N- * N;LI.N;L3N65M&&&0!
)c * oci$connect%)username+ )password+ )d/&!
The sn"a/ can be more comple/ "han "h!s e/ample, depend!ng on "he Oracle 7e" 'ea"ures
used. 2or e/ample, ou can enable 'ea"ures l!(e load balanc!ng and "+ea( pac(e" s!1es. The
;as Connec" sn"a/ does no" allo+ "h!s 'le/!b!l!".
#ata$a!e Connect Na1e
Mou can s"ore "he connect descriptor s"r!ng !n a commonl used Oracle '!le called
tnsna+es"ora and re'er "o !" !n PHP us!ng a connect na+e)
Q tnsnames.ora
N;L * %L-74B5E:53M *
%6LLB-77 * %EB3:343K * :4E&
%>37: * m#machine.m#domain&%E3B: * 1521&&
%43MM-4:$L6:6 *
%7-BZ-B * L-L546:-L&
%7-BZ54-$M6N- * N;LI.N;L3N65M&&&
:n PHP ou +ould use "he connect na+e MMD "o connec" "o "he da"abase)
)c * oci$connect%)username+ )password+ 0N;L0&!
PHP needs "o be able "o '!nd "he tnsna+es"ora '!le "o resol&e "he MMD name. The d!rec"or
pa"hs "ha" Oracle searches 'or tnsna+es"ora depend on our opera"!ng ss"em. On .!nu/, "he
search pa"h !ncludes)
):M7$6LN5M/tnsnames.ora
/etc/tnsnames.ora
)3B64K-$>3N-/network/admin/tnsnames.ora
:' PHP +as comp!led us!ng "he Oracle l!brar!es !n an OR%C.;NHOM;?s"le !ns"all, "hen se"
OR%C.;NHOM; be'ore s"ar"!ng "he +eb ser&er. The pre?suppl!ed
JO:A-FE=HO!E;net,or1;ad+in;tnsna+es"ora +!ll "hen au"oma"!call be 'ound. :n Oracle
Da"abase =;, "he &alue o' WOR%C.;NHOM; !s)
/u01/app/oracle/product/11.2.0/.e
:' PHP +as bu!l" +!"h Oracle :ns"an" Cl!en" "hen pu" tnsna+es"ora !n ;etc, or se" T74N%DM:7 "o
"he d!rec"or con"a!n!ng !" pr!or "o s"ar"!ng "he +eb ser&er.
Ma(e sure %pache has read perm!ss!ons on tnsna+es"ora. :n some OR%C.;NHOM;?s"le
!ns"alls, "he de'aul" perm!ss!ons on "he '!le are res"r!c"!&e.
&3-
Commonly #een Connection and 4n$ironment 4rrors
Co11onl6 Seen Connection and En-iron1ent Error!
;s"abl!sh!ng a da"abase connec"!on !s "he common place 'or !ns"alla"!on and con'!gura"!on
errors "o man!'es" "hemsel&es.
Common errors +hen runn!ng PHP +!"h "he OC:$ e/"ens!on are due "o an !ncorrec"l se"
en&!ronmen". Chec( "he en&!ronmen" &ar!ables are se" and e/por"ed, see Setting the Oracle
Environ+ent on Finux, !n "he chap"er .nstalling and -on*iguring PHP. On 0!ndo+s "he
common problem !s ha&!ng mul"!ple &ers!ons o' Oracle l!brar!es !ns"alled.
The bo""om l!ne !s "ha" our en&!ronmen" should be se" correc"l and cons!s"en"l. The
%pache process mus" ha&e access "o Oracle l!brar!es and con'!gura"!on '!les. ;n&!ronmen"
&ar!ables mus" be se" !n "he shell "ha" s"ar"s %pache, no" !n PHP scr!p"s.
Chec( the )pache Error Log &ile
4"ar" "roubleshoo"!ng b chec(!ng "he %pache error=log '!le 'or errors so ou "r "o resol&e "he
underl!ng cause, no" some conse>uen"!al smp"om.
Chec( *untime Errors
:' php"ini !s no" con'!gured "o d!spla errors !n normal ou"pu" "hen our +eb pages ma s!mpl
sho+ as blan( page !n our bro+ser. ;nable ou"pu" +!"h display=errors !n php"ini.
%l"erna"!&el, chec( "he +eb ser&er or PHP logs 'or "he error messages.
Chec( php+ini is Loaded
Chec( "ha" "he correc" php"ini '!le !s be!ng loaded. To '!nd "he php"ini loca"!on run a scr!p"
phpin*o"php'
Script /' phpin*o"php
<?php
phpin'o%&!
?
7ear "he "op o' !"s ou"pu" are l!nes l!(e)
...
4on'iguration Aile %php.ini& Eath * /opt/php5D/li/
Koaded 4on'iguration Aile * /opt/php5D/li//php.ini
...
Th!s !mmed!a"el !nd!ca"es "he php"ini d!rec"or and, !n "h!s e/ample, "ha" !" !s be!ng correc"l
read. :' "he d!rec"or d!d no" con"a!n a php"ini '!le, "he loaded &alue +ould read DCnoneFE.
Older &ers!ons o' PHP ma onl sho+ one l!ne)
4on'iguration Aile %php.ini& Eath * /opt/php/li//php.ini
:' php"ini +as no" 'ound, "he old ou"pu" +ould onl sho+ "he d!rec"or name)
4on'iguration Aile %php.ini& Eath * /opt/php/li/
Chec( "he phpin*o"php ou"pu" +!"h bo"h command l!ne PHP and &!a a bro+ser.
&30
Connecting to .racle Bsing .C'1
Mou can o&err!de "he de'aul" loca"!on o' php"ini b add!ng "he des!red '!le loca"!on "o our
httpd"con*)
E>E5niLir "/#our/path/to/php.ini"
The pa"h should !nclude "he '!lename.
Chec( OCI, is enabled in php+ini
Chec( "ha" OC:$ !s enabled !n php"ini, !' re>u!red.
On 0!ndo+s e/ac"l one o' "he l!nes e.tension*php$oci8.dll or or
e.tension*php$oci8$11g.dll mus" be !n php"ini.
On .!nu/, !' OC:$ +as s"a"!call comp!led !n"o "he PHP b!nar "hen no d!rec"!&e !s needed
bu" !' OC:$ +as bu!l" as a shared l!brar "he l!ne should be e.tension*oci8.so.
:' all !s +ell !n our php"ini, "he ou"pu" o' phpin'o%& +!ll con"a!n a sec"!on sho+!ng OC:$
parame"ers. 4ee "he sec"!on on -hec1ing O-./ and PDO=O-. .nstallation !n "he chap"er
.nstalling and -on*iguring PHP.
Set Oracle Enironment !ariables
7e&er use Eut-nC%& "o se" Oracle en&!ronmen" &ar!able !n PHP scr!p"s. Th!s !s "he number one
cause o' une/pec"ed user problem. ,ar!ables should be se" and e/por"ed !n "he en&!ronmen"
"ha" s"ar"s "he +eb ser&er.
:' ou "h!n( our en&!ronmen" &ar!ables are no" se", re'er "o Setting the Oracle
Environ+ent on Finux !n "he chap"er .nstalling and -on*iguring PHP.
:' ou are e/pec"!ng shell en&!ronmen" &ar!ables "o be passed "o PHP +hen s"ar"!ng
%pache, do no" use "he .!nu/ service command "o s"ar" %pache, s!nce "h!s clears "he
en&!ronmen".
Chec( )pache $as Oracle &ile )ccess
The OC:$ e/"ens!on al+as needs "o '!nd Oracle l!brar!es, global!1a"!on da"a, error message
da"a and op"!onall needs "he Oracle 7e"+or( tnsna+es"ora and sDlnet"ora '!les. 7o" '!nd!ng
"he l!brar!es can lead "o %pache s"ar"up errors abou" OC:$ no" be!ng !n!"!al!1ed, such as
DO-.Env2ls-reateNO *ailedE, or "o scr!p" run"!me errors l!(e)
E>E Aatal error: 4all to unde'ined 'unction oci$connect%&
Th!s par"!cular error means "ha" "he OC:$ e/"ens!on !s no" loaded !n PHP.
Chec( "ha" OR%C.;NHOM; and<or .DN.:-R%RMNP%TH on .!nu/, or P%TH on 0!ndo+s are
&al!d. :' ou bu!l" PHP +!"h an OR%C.;NHOM;, "hen chec( "he Oracle home d!rec"or !s
readable b "he %pache process o+ner. :' ou are us!ng an Oracle Da"abase 10g Release 2
da"abase o"her "han "he ;/press ;d!"!on, re'er "o "he JO:A-FE=HO!E;install;changePer+"sh
scr!p" !n la"er Oracle pa"ch se"s.
Chec( "ha" "he tnsna+es"ora '!le C!' ou use one 'or connec"!onF !s readable. Res"ar"
%pache a'"er ma(!ng changes "o Oracle 7e"+or( con'!gura"!on '!les so "ha" PHP re?reads "he
upda"ed '!les.
% "ool such as strace or truss can be used on PHP "o see +h!ch '!les PHP needs access "o.
&31
Commonly #een Connection and 4n$ironment 4rrors
)oid 'ultiple Oracle Librar- Clashes
% po"en"!al source o' problems on 0!ndo+s !s ha&!ng mul"!ple !ns"alla"!ons o' Oracle l!brar!es.
Us!ng m!sma"ched &ers!ons o' Oracle l!brar!es and '!les can lead "o PHP re"urn!ng errors such
as)
3B6-12U05: 4annot access MK7 data 'iles or inCalid enCironment speci'ied
or)
345-nCMls4reate%& 'ailed. :here is something wrong with #our s#stem
Users o' older &ers!ons o' OC:$ ma see "he one o' "he e>u!&alen" errors)
345-nC4reate%& 'ailed. :here is something wrong with #our s#stem
or
345-nC5nit%& 'ailed. :here is something wrong with #our s#stem
:ns"ead o' s"ar"!ng %pache as a ser&!ce "ha" !nher!"s "he m!/ed Oracle en&!ronmen", +r!"e a
scr!p" "ha" se"s P%TH +!"h "he correc" Oracle l!brar!es and "hen s"ar"s %pache. 0!"h "he ::4 +eb
ser&er, use "he ::4 manager and se" P%TH !n "he php3cgi"exe en"r !n "he 2as"C3: se""!ngs.
4ome users mo&e "he :ns"an" Cl!en" D..s "o "he 4s"em, %pache, or PHP d!rec"or as a
>u!c( solu"!on, bu" "h!s !s no" recommended as a long "erm solu"!on.
Us!ng a dependenc chec(er program can help de"erm!ne +h!ch Oracle l!brar!es are be!ng
loaded on 0!ndo+s.
Use the *ight #$# "inar-
On 0!ndo+s OJ?b!" !' ou use Oracle OJ?b!" l!brar!es ou m!gh" ge" an 345-nCMK74reate%&
error or ou m!gh" see)
Rna/le to load d#namic li/rar# 04:2Erogram Ailes %.8P&2E>E2e.t2php$oci8$11g.dll0
- F1 is not a Calid ?in@2 application.
There !s onl a I2?b!" &ers!on o' PHP on 0!ndo+s so ou need "o ma(e sure "o use Oracle I2?
b!" cl!en" l!brar!es.
Use the *ight Connection String
Mour oci$connect%& calls need "o (no+ +h!ch da"abase "o connec" "o. :' an error l!(e "h!s
occurs)
-rror while tr#ing to retrieCe te.t 'or error 3B6-1215D
!" means "+o problems happened. 2!rs", a connec"!on error OR%?121HJ occurred. The second
problem !s "he D;rror +h!le "r!ng "o re"r!e&e "e/"E message, !nd!ca"!ng OracleKs message '!les
+ere no" 'ound, mos" l!(el because OR%C.;NHOM; !s no" correc"l se".
The e/pec"ed descr!p"!on 'or OR%?121HJ !s ac"uall)
3B6-1215D: :M7:could not resolCe serCice name
&32
Connecting to .racle Bsing .C'1
Th!s error !nd!ca"es "ha" "he connec"!on s"r!ng !s no" &al!d, or "he tnsna+es"ora '!le C!' one !s
be!ng usedF +asnA" readable. The resul" !s "ha" OC:$ does no" (no+ +h!ch mach!ne "o connec"
"o. % s!m!lar error)
3B6-1251D :M7:listener does not currentl# know o' serCice re"uested in connect
descriptor
means "ha" OC:$ +as able "o con"ac" a mach!ne hos"!ng Oracle, bu" "he e/pec"ed da"abase !s
no" runn!ng on "ha" compu"er. 2or e/ample, !' Oracle Da"abase 11g =; !s curren"l runn!ng on
our compu"er and ou "r "o connec" "o localhost;abc "hen ou +!ll ge" "h!s error.
Other Troubleshooting Tips
Here are some 'ur"her "h!ngs "o chec( !' ou are ha&!ng problems connec"!ng or con'!gur!ng
OC:$)
Turn on error repor"!ng !n php"ini Cremember "o "urn !" o'' 'or produc"!on deplomen"F or
do !" !n each scr!p" +!"h)
error$reporting%-$6KK&! // 5n E>E 5.@ use -$6KK[-$7:B54:
ini$set%0displa#$errors0+ 03n0&!
Mou m!gh" ge" DO-.Env2ls-reateNO *ailedE !' PHP l!n(s +!"h an older Oracle &ers!on a"
run"!me "han "he one !" +as comp!led +!"h. :' ou ha&e mul"!ple &ers!ons o' Oracle
!ns"alled on .!nu/ "hen ou m!gh" be able "o use .DNPR;.O%D or e>u!&alen" "o 'orce
%pache "o load "he des!red Oracle libclntsh"so '!le.
:' scr!p"s some"!me 'a!l +!"h O:A3&24&9 )2S'listener could not *ind available handler ,ith
+atching protocol stac1 "hen use DRCP connec"!on pool!ng or !ncrease "he Oracle
Da"abase processes parame"er. Pool!ng !s d!scussed !n "he chap"er PHP -onnection
Pooling and High Availability. Chang!ng "he da"abase parame"er !s d!scussed !n "he
chap"er )esting PHP and the O-./ Extension"
On 0!ndo+s ma(e sure "o reboo" a'"er mod!'!ng "he P%TH en&!ronmen" &ar!able.
:' ou cop!ed tnsna+es"ora 'rom 0!ndo+s "o .!nu/ ou +!ll ge" an error !' !" s"!ll con"a!ns)
7SKM-:.6R:>-M:546:53M$7-BZ54-7 * %M:7&
:' "here !s a cl!en" sDlnet"ora C+h!ch +ould be !n "he same d!rec"or as tnsna+es"oraF,
chec( +ha" "he names.de'ault$domain &alue !s. Th!s &alue +!ll be au"oma"!call appended
"o "he T74 s"r!ng !n PHP be'ore be!ng loo(ed up !n tnsna+es"ora. 2or e/ample, !'
sDlnet"ora had names.de'ault$domain * oracle.com and "he connec"!on call +as
oci$connect%)u+ )p+ 0,-0&, "hen tnsna+es"ora +ould need "o ha&e an en"r
0,-.oracle.com * %L-74B5E:53M ...&0.
Onl one &ers!on o' "he PHP module can be loaded !n %pache a" a "!me. :" !s poss!ble "o
ge" "he error DO-.Env2ls-reateNO *ailedE !' httpd"con* has "+o .oadModule l!nes l!(e)
KoadNodule php5$module modules/li/php5.so
KoadNodule phpP$module modules/li/phpP.so
&&3
Closing .racle Connections
Clo!ing Oracle Connection!
%" "he end o' each scr!p", connec"!ons opened +!"h oci$connect%& or oci$new$connect%& are
au"oma"!call closed. Mou can also e/pl!c!"l close "hese connec"!ons b call!ng)
oci$close%)c&!
%n uncomm!""ed da"a !s rolled bac(. The 'unc"!on has no e''ec" on pers!s"en" connec"!ons.
C4ee "he sec"!on on connec"!on pool!ng !n "he PHP -onnection Pooling and High Availability
chap"er 'or ca&ea"sF.
:' a long runn!ng scr!p" onl spends a small amoun" o' "!me !n"erac"!ng +!"h "he da"abase,
close connec"!ons as soon as poss!ble "o 'ree da"abase resources 'or o"her users. 0hen "he
%pache or PHP command l!ne process "erm!na"es, all da"abase connec"!ons are closed.
The oci$close%& 'unc"!on +as a Dno?opE pr!or "o "he re?'ac"or!ng o' OC:$ !n PHP H.1. Tha"
!s, !" had no 'unc"!onal code, and ne&er ac"uall closed a connec"!on. Mou could no" e/pl!c!"l
close connec"!ons e&en !' ou +an"ed "oT Mou can re&er" "o "h!s old beha&!or +!"h a php"ini
se""!ng)
oci8.old$oci$close$semantics * 3n
Clo!ing Connection! and <aria$le Scope
PHP resources such as connec"!on resources +or( b re'erence coun"!ng. Onl +hen all PHP
re'erences "o "he da"abase connec"!on are '!n!shed +!ll !" ac"uall be closed and da"abase
resources 'reed. Th!s e/ample sho+s "he e''ec" o' re'erence coun"!ng)
Script 8' close"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "select J 'rom locations"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
// oci$'ree$statement%)s&! // Rncomment this 'or the oci$close%& to work
oci$close%)c&!
echo "7leeping . . ."!
sleep%10&!
echo "Lone"!
?
0h!le close"php !s sleep!ng, !' ou >uer "he da"abase as a pr!&!leged user)
7SK select username 'rom C)session where username is not null!
ou +!ll see "ha" HR !s s"!ll sho+n as connec"ed un"!l "he sleep%& '!n!shes and "he scr!p"
"erm!na"es. Th!s !s because "he oci$parse%& call crea"!ng "he s"a"emen" resource )s !n"ernall
!ncreases "he re'erence coun" on )c. The da"abase connec"!on !s no" closed un"!l PHPAs end?o'?
scr!p" process!ng des"ros )s.
&&&
Connecting to .racle Bsing .C'1
%n oci$'ree$statement%)s& call +!ll e/pl!c!"l decrease "he re'erence coun" on )c allo+!ng
"he oci$close%& "o ha&e an !mmed!a"e e''ec". :' "h!s 'ree!ng call !s uncommen"ed !n "he
e/ample, "he 4B.SPlus >uer +!ll sho+ "he da"abase connec"!on +as e/pl!c!"l closed be'ore
"he sleep%& s"ar"s.
%no"her commonl seen !d!om "o close resources !s "o ass!gn null "o "hem)
)s * null!
,ar!ables and o"her (!nds o' resources ma also !ncrease "he re'erence coun" on a connec"!on,
and !n "urn ha&e "he!r o+n re'erence coun" +h!ch mus" be 1ero be'ore "he can des"roed.
The re'erence coun" +!ll decrease !' "he &ar!ables goes ou" o' scope or are ass!gned ne+
&alues.
:n "he ne/" e/ample scr!p", close2"php, "he &ar!ables )c1 and )c2 are "he same da"abase
connec"!on because oci$connect%& re"urns "he same connec"!on resource +hen called more
"han once !n a scr!p" +!"h "he same creden"!als. :' ou >uer C)session +h!le "he scr!p" !s
runn!ng ou +!ll onl see one open connec"!on. The phs!cal da"abase connec"!on !s released
onl +hen )c1 and c2 are bo"h closed. %lso "he s"a"emen" resource mus" be 'reed, +h!ch
happens au"oma"!call +hen do$"uer#%& comple"es and )s goes ou" o' scope.
Script &A' close2"php
<?php
'unction do$"uer#%)c+ )"uer#&
(
)s * oci$parse%)c+ )"uer#&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
echo "<pre"!
Car$dump%)res&!
echo "</pre"!
=
)c1 * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)c2 * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&! // Beuses )c1 LI connection
do$"uer#%)c1+ 0select user 'rom dual0&! // Suer# 1 works
oci$close%)c1&! // LI connection doesn0t get closed
do$"uer#%)c1+ 0select user 'rom dual0&! // Suer# 2 'ails
do$"uer#%)c2+ 0select user 'rom dual0&! // Suer# @ works
oci$close%)c2&! // LI connection is now closed
?
,ar!able )c1 !s no" usable a'"er oci$close%)c1& !s e/ecu"ed) PHP has d!ssoc!a"ed !" 'rom "he
connec"!on. -u" "he da"abase connec"!on rema!ns open because )c2 s"!ll re'erences !". The
scr!p" ou"come !s "ha" "he '!rs" and "h!rd >uer!es succeed bu" "he second one 'a!ls.
Tran!action! and Connection!
Uncomm!""ed da"a !s rolled bac( +hen a connec"!on !s closed or a" "he end o' a scr!p". 2or
oci$pconnect%& "h!s means subse>uen" scr!p"s reus!ng a cached da"abase connec"!on +!ll no"
see an da"a "ha" should no" be shared.
&&(
Closing .racle Connections
%&o!d le""!ng da"abase "ransac"!ons rema!n open !' a second oci$connect%& or
oci$pconnect%& call +!"h "he same user creden"!als !s e/ecu"ed +!"h!n a scr!p", or !'
oci$close%& !s used. Ma(!ng sure da"a !s comm!""ed or rolled bac( '!rs" can pre&en" hard "o
debug edge cases +here da"a !s no" be!ng s"ored as e/pec"ed.
The ne/" chap"er co&ers da"abase "ransac"!ons !n more de"a!l.
Se!!ion State With Per!i!tent Connection!
:" !s poss!ble 'or a scr!p" "o change sess!on a""r!bu"es 'or oci$pconnect%& "ha" are no" rese" a"
"he end o' "he scr!p". CThe Oracle "erm session !s e''ec"!&el "he same as "he PHP "erm
connectionF. One e/ample !s "he global!1a"!on se""!ng 'or "he da"e 'orma")
)c * oci$pconnect%"hr"+ "welcome"+ "localhost/,-"&!
do$"uer#%)c+ "select s#sdate 'rom dual"&!
)s * oci$parse%)c+ "alter session set nls$date$'ormat*_;;;;-NN-LL >>2D:N5:77_"&!
)r * oci$e.ecute%)s&!
do$"uer#%)c+ "select s#sdate 'rom dual"&!
The '!rs" "!me "h!s !s called !n a bro+ser, "he "+o da"es re"urned b "he >uer!es are)
18-6EB-0U
200U-0D-18 1D:21:09
The '!rs" da"e has "he Oracle de'aul" 'orma". The second !s d!''eren" because "he %.T;R
4;44:O7 command changed "he 'orma".
Call!ng "he scr!p" a second "!me g!&es)
200U-0D-18 1D:21:10
200U-0D-18 1D:21:10
The pers!s"en" connec"!on has re"a!ned "he sess!on se""!ng and "he '!rs" >uer no longer uses
"he ss"em de'aul" 'orma". Th!s onl happens !' "he same %pache process ser&es bo"h HTTP
re>ues"s. :' a ne+ %pache process ser&es "he second re>ues" "hen !" +!ll open a ne+
connec"!on "o "he da"abase, +h!ch +!ll ha&e "he or!g!nal de'aul" da"e 'orma". C%lso "he ss"em
+!ll ha&e "+o pers!s"en" connec"!ons le'" open !ns"ead o' one.F
4ess!on changes l!(e "h!s ma no" be a concern. Mour appl!ca"!ons ma ne&er need "o do
an"h!ng l!(e !", or all connec"!ons ma need "he same &alues an+a. :' "here !s a poss!b!l!"
!ncorrec" se""!ngs +!ll be !nher!"ed, ma(e sure our appl!ca"!on rese"s &alues a'"er connec"!ng.
Optional Connection Para1eter!
The oci$connect%&, oci$new$connect%& and oci$pconnect%& 'unc"!ons "a(e an op"!onal e/"ra
"+o parame"ers)
Connec"!on charac"er se"
Connec"!on sess!on mode
Connection Character Set
The charac"er se" !s a s"r!ng con"a!n!ng an Oracle charac"er se" name, 'or e/ample, T61PR-4 or
6K@2R:A8)
&&)
Connecting to .racle Bsing .C'1
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"+ "6K@2R:A8"&!
0hen no" spec!'!ed or MRKK !s passed, "he 7.4N.%73 en&!ronmen" &ar!able se""!ng !s used.
The charac"er se" de"erm!nes ho+ Oracle "ransla"es da"a +hen !" !s "rans'erred 'rom "he
da"abase "o PHP. :' "he da"abase charac"er se" !s no" e>u!&alen" "o "he OC:$ charac"er se",
some da"a ma ge" con&er"ed abnormall. :" !s recommended "o se" "h!s parame"er "o
!mpro&e per'ormance and guaran"ee a (no+n &alue !s used.
:" !s up "o our appl!ca"!on "o handle re"urned da"a correc"l, perhaps b us!ng PHPKs
+b=string, iconv or intl e/"ens!ons. 3lobal!1a"!on !s d!scussed !n more de"a!l !n "he
Globaliation chap"er.
Connection Se!!ion 5ode
The sess!on mode parame"er allo+s pr!&!leged or e/"ernall au"hen"!ca"ed connec"!ons "o be
made. 2or e/ample)
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"+ "6K@2R:A8"+ 345$7;7LI6&!
Connection #riilege Leel
The OC:$ e/"ens!on allo+s pr!&!leged 4M4D-% and 4M4OP;R connec"!ons. Pr!&!leged
connec"!ons are d!sabled b de'aul". The can be enabled !n php"ini us!ng)
oci8.priCileged$connect * 1
The 4M4D-% and 4M4OP;R pr!&!leges g!&e ou "he ab!l!" "o change "he s"a"e o' "he da"abase,
per'orm da"a reco&er, and e&en access "he da"abase +hen !" has no" 'ull s"ar"ed. -e &er
care'ul abou" e/pos!ng "h!s on cus"omer 'ac!ng +eb s!"es, "ha" !s, do no" do !"T :" m!gh" be
use'ul 'or command l!ne PHP scr!p"s !n &er spec!al c!rcums"ances.
0hen ou !ns"alled Oracle, "he 4M4 adm!n!s"ra"!&e user accoun" +as au"oma"!call crea"ed
+!"h "he pass+ord "ha" ou suppl!ed. %ll base "ables and &!e+s 'or "he da"abase da"a
d!c"!onar are s"ored !n "he 4M4 schema Y "he are cr!"!cal 'or "he opera"!on o' Oracle. -
de'aul", "he 4M4D-% pr!&!lege !s ass!gned onl "o user 4M4, bu" !" and 4M4OP;R can manuall
be gran"ed "o o"her users.
Operating S-stem )uthenticated #riileged Connections
Mou can ha&e "he opera"!ng ss"em per'orm "he au"hen"!ca"!on 'or pr!&!leged connec"!ons
based around "he opera"!ng ss"em user "ha" !s runn!ng "he +eb ser&er ss"em process. %n
opera"!ng ss"em au"hen"!ca"ed pr!&!leged connec"!on !n PHP !s e>u!&alen" "o "he 4B.SPlus
connec"!on)
) s"lplus / as s#d/a
2or / as s#sd/a access C+here no username and pass+ord !s usedF !n PHP, all "hese mus" be
"rue)
The opera"!ng ss"em process user !s a member o' "he O4 dba group
PHP !s l!n(ed +!"h "he same OR%C.;NHOM; so'"+are "ha" "he da"abase !s us!ng Cno"
Oracle :ns"an" Cl!en"F
&&*
.ptional Connection !arameters
The da"abase !s our de'aul" local da"abase, 'or e/ample, spec!'!ed b "he OR%C.;N4:D
en&!ronmen" &ar!able
oci8.priCileged$connect * 1 !n php"ini"
4cr!p"s "ha" con"a!n opera"!ng ss"em au"hen"!ca"ed pr!&!leged connec"!on calls +!ll connec"
success'ull)
)c * oci$connect%"/"+ ""+ null+ null+ 345$7;7LI6&!
:' PHP !s !n&o(ed b %pache, "he l!brar pa"h needs "o con"a!n "he same Oracle l!brar!es as
used b "he da"abase. %lso "he nobody user mus" be !n "he pr!&!leged Oracle group, 'or
e/ample, !n "he opera"!ng ss"em dba group. Th!s !s no" recommended.
4!m!larl, %4 4M4OP;R access !s a&a!lable 'or members o' "he oper group. :n PHP use
OC:N4M4OP;R !n oci$connect%&.
On 0!ndo+s, "he opera"!ng ss"em groups are called O:A=DIA and O:A=OPE:.
*emote #riileged )ccess
0hen OC:$ uses Oracle :ns"an" Cl!en", a username and pass+ord mus" be g!&en +hen
connec"!ng "o a da"abase. These connec"!ons are cons!dered Dremo"eE 'rom "he da"abase
because "he l!brar!es used b PHP are no" "hose used b "he runn!ng da"abase.
Remo"e users can ma(e pr!&!leged connec"!ons onl +hen "he ha&e been g!&en "he
appropr!a"e Oracle access. :n 4B.SPlus a pr!&!leged sess!on +ould be s"ar"ed l!(e)
) s"lplus username/passwordOsid as s#sd/a
The da"abase +!ll no" perm!" "he Cposs!bl phs!callF Dremo"eE opera"!ng ss"em "o au"hor!1e
access. %n e/"ra Oracle pass+ord '!le needs "o be crea"ed and a pass+ord needs "o be used !n
"he da"abase connec"!on.
To se" up a pass+ord '!le, chec( "he da"abase !n!"!al!1a"!on parame"er
re+ote=login=pass,ord*ile !s ;=C.U4:,;. Th!s !s "he de'aul" &alue. To do "h!s, log !n "o "he
opera"!ng ss"em shell as "he Oracle da"abase so'"+are o+ner, and s"ar" 4B.SPlus)
) s"lplus / as s#sd/a
7SK show parameter remote$login$password'ile
M6N- :;E- Z6KR-
----------------------------- ----------- ------------
remote$login$password'ile string -,4KR75Z-
% se""!ng o' ;=C.U4:,; means "he pass+ord '!le !s onl used +!"h one da"abase and no"
shared among se&eral da"abases on "he hos". :" enables ou "o ha&e mul"!ple users connec" "o
"he da"abase as "hemsel&es, and no" 8us" as 4M4. :' "h!s parame"er !s no" se" "o ;=C.U4:,;,
ou can change "he &alue !n 4B.SPlus b en"er!ng a command s!m!lar "o)
7SK alter s#stem set remote$login$password'ile*0e.clusiCe0
2 scope*sp'ile sid*0J0!
2rom "he opera"!ng ss"em shell, crea"e an Oracle pass+ord '!le)
) )3B64K-$>3N-//in/orapwd 'ile*)3B64K-$>3N-/d/s/acct.pwd 2
password*secret entries*10
&&+
Connecting to .racle Bsing .C'1
Th!s crea"es a pass+ord '!le named acct"p,d "ha" allo+s up "o 10 pr!&!leged users +!"h
d!''eren" pass+ords C"h!s number can be changed la"erF. The '!le !s !n!"!all crea"ed +!"h "he
pass+ord secret 'or users connec"!ng +!"h "he username 4M4.
To add a ne+ user "o "he pass+ord '!le use 4B.SPlus)
7SK create user c1 identi'ied /# c1pw!
7SK grant connect to c1!
7SK grant s#sd/a to c1!
7SK select J 'rom C)pw'ile$users!
R7-BM6N- 7;7LI6 7;73E-B
------------------------------ ------ -------
7;7 :BR- :BR-
41 :BR- A6K7-
7o+ !n PHP ou can use "he 'ollo+!ng connec"!on command)
)c * oci$connect%"c1"+ "c1pw"+ 0localhost/,-0+ null+ 345$7;7LI6&!
One 'ea"ure o' a pr!&!leged connec"!on !s "ha" !' ou !ssue a 7-K-4: R7-B AB3N LR6K
s"a"emen", an OC:N4M4D-% connec"!on +!ll sho+ "he user as 4M4 no" C1. % connec"!on made
+!"h OC:N4M4OP;R +!ll sho+ a user o' PU-.:C.
Pa!!;ord Handling in PHP ,pplication!
The e/amples !n "h!s boo( hard code "he da"abase pass+ord !n each PHP scr!p". Real
appl!ca"!ons need "o be more care'ul +!"h pass+ord managemen".
PHP opera"es !n a s"a"eless +a bu" a "p!cal appl!ca"!on needs da"abase access o&er a
number o' se>uen"!al HTTP re>ues"s. Once "he user has logged !n"o "he +eb appl!ca"!on ou
donA" +an" "o s"ore "he!r pla!n"e/" pass+ord !n a coo(!e and reuse !" 'or da"abase connec"!on
on "he!r ne/" +eb re>ues" because s"or!ng !" "h!s +a !s a secur!" r!s(. 4o +eb appl!ca"!ons
"p!call connec" "o "he da"abase us!ng one pre?de"erm!ned da"abase schema and do "he!r
o+n appl!ca"!on?spec!'!c au"hor!1a"!on.
The '!rs" problem !s ho+ "o pro"ec" "ha" schema. % "p!cal PHP approach "o a&o!d hard
cod!ng "he da"abase pass+ord !n scr!p"s !s "o se" !" !n an en&!ronmen" &ar!able. The &ar!able !s
passed "hrough "o PHP +!"h %pacheAs Pass;n&. 0hene&er %pache !s s"ar"ed or "he mach!ne
reboo"ed, "he &ar!able mus" be manuall se". The &alue !s "hen a&a!lable "o PHP scr!p"s !n "he
WN;7, global)
)c * oci$connect%0hr0+ )$-MZ90>BE677?3BL0<+ 0localhost/,-0&!
7o"e "ha" on .!nu/ "he service httpd start command onl passes "he .%73 and T;RM
&ar!ables, so %pache mus" be s"ar"ed +!"h ;usr;sbin;apachectl 'or "h!s "o +or( on Oracle .!nu/.
Eternal ,uthentication With PHP OCI.
:ns"ead o' s"or!ng "he da"abase username and pass+ord !n PHP scr!p"s or en&!ronmen"
&ar!ables, da"abase access can be au"hen"!ca"ed b an ou"s!de ss"em. Once "h!s
au"hen"!ca"!on ss"em !s con'!gured, PHP scr!p"s connec" l!(e)
)c * oci$connect%"/"+ ""+ "m#netalias"+ null+ 345$4B-L$-,:&!
+here +ynetalias !s a connec" name con'!gured !n a tnsna+es"ora '!le. 7o username or
pass+ord !s s"ored !n "he PHP code.
&&-
!ass/ord Handling in !H! Applications
One such e/"ernal s"orage mechan!sm !s Oracle 0alle" +h!ch crea"es a secre" +alle" s"ore.
Onl "he opera"!ng ss"em user runn!ng "he %pache process needs "o be gran"ed read access
"o "he +alle", +h!ch can be done us!ng %ccess Con"rol .!s"s C%C.F. Th!s 'ur"her helps pro"ec"
"he da"abase pass+ord.
The 'ollo+!ng e/ample !s an o&er&!e+ o' us!ng Oracle 0alle" Manager. -ecause "he de"a!ls
&ar 'rom &ers!on "o &ers!on and "he op"!ons ma be spec!'!c "o our appl!ca"!on, &er!' "he
s"eps be'ore "rus"!ng "h!s. 7o"e "h!s !s no" suppor"ed !n Oracle =;, and also "ha" "he e/"ernal
au"hen"!ca"!on 'ea"ure o' OC:$ !s no" a&a!lable on 0!ndo+s.
1. 2!rs" crea"e a +alle" d!rec"or as "he Oracle user)
) mkstore -wrl /home/oracle/wallet$dir -create
Th!s +!ll promp" 'or a ne+ pass+ord 'or "he s"ore.
2. Crea"e "he +alle" 'or "he username and pass+ord "ha" are curren"l hardcoded !n our
PHP scr!p"s)
) mkstore -wrl "/home/oracle/wallet$dir" -create4redential m#112 hr welcome
Th!s +!ll promp" 'or "he +alle" pass+ord pre&!ousl se". The al!as (e +y&&2
!mmed!a"el 'ollo+!ng "he ?create-redential op"!on +!ll be "he connec" name "o be
used !n PHP scr!p"s. :' our appl!ca"!on connec"s +!"h mul"!ple d!''eren" da"abase
users, ou could crea"e a +alle" en"r +!"h d!''eren" connec" names 'or each.
Mou can see "he ne+l crea"ed creden"!al +!"h)
) mkstore -wrl "/home/oracle/wallet$dir" -list4redential
I. Crea"e a tnsna+es"ora '!le, 'or e/ample !n ;opt;oracle;tnsna+es"ora. Th!s +!ll be used b
PHP appl!ca"!ons)
m#112 *
%L-74B5E:53M *
%6LLB-77 * %EB3:343K * :4E&%>37: * localhost&%E3B: * 1521&&
%43MM-4:$L6:6 *
%7-BZ-B * L-L546:-L&
%7-BZ54-$M6N- * orcl&
&
&
The '!le uses "he descr!p"!on 'or our e/!s"!ng da"abase and se"s "he connec" name
al!as "o +y&&2, +h!ch !s "he ne+ !den"!'!er used !n "he +alle".
J. :n "he same d!rec"or as "he tnsna+es"ora '!le, crea"e a sDlnet"ora '!le con"a!n!ng "he
+alle" loca"!on)
?6KK-:$K346:53M *
%73RB4- *
%N-:>3L * A5K-&
%N-:>3L$L6:6 *
%L5B-4:3B; * /home/oracle/wallet$dir&
&
&
7SKM-:.?6KK-:$3Z-BB5L- * :BR-
&&0
Connecting to .racle Bsing .C'1
77K$4K5-M:$6R:>-M:546:53M * A6K7-
77K$Z-B753M * 0
H. 4e" T74N%DM:7 "o "he d!rec"or con"a!n!ng "hese "+o '!les, and e/por" "he &ar!able. On
Oracle .!nu/ !" +ould be e/por"ed !n ;etc;syscon*ig;httpd 'or PHP, 'or e/ample:
e.port :M7$6LN5M*/opt/oracle
O. %pache needs access "o "he +alle")
Q set'acl -m u:apache:r. /home/oracle/wallet$dir
Q set'acl -m u:apache:r /home/oracle/wallet$dir/(cwallet.sso+ewallet.p12=
P. Res"ar" %pache)
Q serCice httpd restart
$. Crea"e an OC:$ scr!p" o' our cho!ce, pass!ng "he 'lag OC:NCR;DN;=T as "he session=+ode
parame"er "o oci$connect%&, oci$new$connect%& or oci$pconnect%&)
)c * oci$connect%"/"+ ""+ "m#112"+ null+ 345$4B-L$-,:&!
The OC:NCR;DN;=T mode can onl be used +!"h a username o' "/" and an emp"
pass+ord. The php"ini parame"er oci/"privileged=connection ma be On or O**. The
OC:NCR;DN;=T mode ma be comb!ned +!"h "he OC:N4M4OP;R or OC:N4M4D-%
modes, 'or e/ample)
)c * oci$connect%"/"+ ""+ )d/+ null+ 345$4B-L$-,:H345$7;73E-B&!
The php"ini d!rec"!&e oci/"privileged=connection does need "o be On 'or OC:N4M4D-%
and OC:N4M4OP;R use.
L. .oad our scr!p" !n a bro+ser.
Tuning Connection! to )uild Scala$le S6!te1!
Oracle ach!e&ed !"s +ell?(no+n scalab!l!" !n par" "hrough a mul"!?"hreaded arch!"ec"ure. PHP
!ns"ead has a mul"!?process arch!"ec"ure. Th!s des!gn d!''erence means care !s re>u!red +hen
des!gn!ng scalable appl!ca"!ons because, !ns"ead o' connec"!ons be!ng shared &!a a m!d?"!er
connec"!on pool, large numbers o' PHP processes each ha&e one or more da"abase
connec"!ons. The number o' connec"!ons open !s a 'ac"or 'or da"abase ser&er memor
re>u!remen"s. Crea"!ng ne+ connec"!ons !s also rela"!&el slo+ !n Oracle. Connec"!ng pool!ng
!n OC:$ and Oracle Da"abase helps resol&e "hese !ssues.
% general connec"!on "!p !s "o ma(e appl!ca"!ons as e''!c!en" as poss!ble. Th!s m!n!m!1es
"he leng"h o' "!me connec"!ons are held. The 'ollo+!ng sub?sec"!ons g!&e some de"a!led "!ps.
0!e the )e!t Connection 9unction
Us!ng oci$pconnect%& ma(es a b!g !mpro&emen" !n o&erall connec"!on speed o' 're>uen"l
used appl!ca"!ons because !" uses "he connec"!on cache !n PHP. % ne+, phs!cal connec"!on "o
"he da"abase does no" ha&e "o be crea"ed !' one alread e/!s"s !n PHPKs cache. Us!ng
pers!s"en" connec"!ons !s common 'or +eb s!"es "ha" ha&e h!gh numbers o' connec"!ons be!ng
&&1
Tuning Connections to >uild #cala5le #ystems
es"abl!shed. Reus!ng a pre&!ousl opened connec"!on !s s!gn!'!can"l 'as"er "han open!ng a
'resh one.
O&erall da"abase load ma be reduced !' !dle connec"!ons are closed +!"h %pache process
"!meou"s, al"hough "h!s needs "o be balanced aga!ns" "he e/pense o' crea"!ng ne+
connec"!ons a" pea( user log!n "!me.
:' unused?bu"?s"!ll?open pers!s"en" connec"!ons consume "oo much memor on "he
da"abase ser&er, cons!der us!ng connec"!on pool!ng.
0!e Connection Pooling
The general bes" prac"!ce sugges"!on !s "o use pers!s"en" OC:$ connec"!ons +!"h Oracle
Da"abase Res!den" Connec"!on Pool!ng. DRCP drama"!call reduces "he da"abase ser&er
memor used 'or each connec"!on, allo+!ng more memor "o be alloca"ed "o shared
s"ruc"ures !n "he da"abase !"sel'. DRCP can be use'ul e&en 'or small s!"es because !" allo+s
da"abase ser&ers "o handle rela"!&el large numbers o' connec"!ons. :' DRCP !s no" a&a!lable
"hen Oracle 4hared 4er&ers also (no+n as DMul"! Threaded 4er&ersE CMT4F m!gh" g!&e some
bene'!"s. 4ee "he chap"er PHP -onnection Pooling and High Availability 'or !n'orma"!on on
us!ng DRCP +!"h OC:$.
5ini1i8e the nu1$er o* data$a!e u!er credential! u!ed
;ach pers!s"en" connec"!on "ha" uses a d!''eren" se" o' creden"!als +!ll crea"e a separa"e
process on "he da"abase hos". :' "he appl!ca"!on connec"s +!"h a large number o' d!''eren"
schemas, "hen "he number o' pers!s"en" connec"!ons can be reduced b connec"!ng as one
user +ho has been gran"ed perm!ss!on "o "he or!g!nal schemasA ob8ec"s.
The appl!ca"!on can e!"her be recoded "o use e/pl!c!" schema names !n >uer!es)
7SK select J 'rom olduser.m#ta/le!
Or, !' "he appl!ca"!on !s "oo e/"ens!&e "o mod!', "he '!rs" s"a"emen" e/ecu"ed can se" "he
de'aul" schema)
7SK alter session set current$schema * olduser!
4e""!ng "he de'aul" schema "h!s +a re>u!res an e/"ra da"abase opera"!on per connec"!on bu",
depend!ng on "he appl!ca"!on, !" ma be bundled !n a P.<4B. bloc( or "r!gger "ha" does o"her
opera"!ons.
Connect With a Character Set
;/pl!c!"l pass!ng "he cl!en" charac"er se" name as "he 'our"h parame"er "o "he connec"!on
'unc"!ons reduces "he "!me "o connec")
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"+ "?-8L-4"&!
:' ou do no" en"er a charac"er se", PHP has "o de"erm!ne one "o use. Th!s ma !n&ol&e a
po"en"!all e/pens!&e en&!ronmen" loo(up. Use "he appropr!a"e charac"er se" 'or our
global!1a"!on re>u!remen"s.
&&2
Connecting to .racle Bsing .C'1
Tune the ,0#SESC SeBuence Generator
2or s!"es +!"h hundreds o' connec"!ons per second, "une "he cache s!1e o' "he !n"ernal
se>uence genera"or, 4M4.%UD4;4W. % s"ar"!ng po!n" !s "o change !" "o perhaps 10000)
7SK alter se"uence s#s.audses) cache 10000!
Th!s !s also recommended !' ou are us!ng Oracle R%C CDReal %ppl!ca"!on Clus"ersEF.
#o Not Set the #ate or Nu1eric 9or1at 0nnece!!aril6
%&o!d e/ecu"!ng %.T;R 4;44:O7 s"a"emen"s a'"er each connec"!on. %ppl!ca"!ons commonl se"
7.4ND%T;N2ORM%T and 7.4N7UM;R:CNCH%R%CT;R4 "o guaran"ee da"a &alues are re"urned
'rom Oracle !n a (no+n 'orma". Cons!der an e/!s"!ng connec"!on rou"!ne "ha" al+as se"s "he
da"e 'orma")
'unction m#$connect%)un+ )pw+ )d/&
(
)c * oci$pconnect%)un+ )pw+ )d/&!
)s * oci$parse%)c+ "alter session set nls$date$'ormat*0;;;;-NN-LL0"&!
oci$e.ecute%)s&!
return )c!
=
One +a "o op"!m!1e "h!s !s s!mpl "o se" "he en&!ronmen" &ar!able 7.4ND%T;N2ORM%T !n "he
shell "ha" s"ar"s "he +eb ser&er. ;ach PHP connec"!on +!ll ha&e "he re>u!red da"e 'orma"
au"oma"!call. 7o"e, +hen se""!ng Oracle 7.4NS global!1a"!on en&!ronmen" &ar!ables ou also
need "o se" 7.4N.%73 o"her+!se "he +!ll be !gnored.
4ome"!mes d!''eren" da"abase users should ha&e d!''eren" sess!on &alues so se""!ng
7.4ND%T;N2ORM%T globall !s no" poss!ble. 0!"h pers!s"en" connec"!ons "he %.T;R 4;44:O7
can be mo&ed "o a logon "r!gger. Th!s !s because sess!on se""!ngs are re"a!ned !n cached
connec"!ons read 'or "he ne/" scr!p" "ha" ma(es an oci$pconnect%& call. Us!ng a "r!gger
means "he da"e 'orma" !s onl se" +hen "he phs!cal da"abase connec"!on !s crea"ed "he &er
'!rs" "!me oci$pconnect%& !s called !n "he l!'e"!me o' "he %pache<PHP process. The "r!gger does
no" '!re +hen subse>uen" oci$pconnect%& calls re"urn a cached connec"!on. :" !s also a
da"abase procedure and does no" re>u!re an !n"erac"!on be"+een "he PHP scr!p" and "he
da"abase. Th!s reduces load on "he +hole ss"em. The same solu"!on +!ll help +hen a
s"andard connec"!on oci$connect%& !s called mul"!ple "!mes !n "he one scr!p"
% logon "r!gger can be crea"ed us!ng 4B.SPlus b connec"!ng as a pr!&!leged da"abase
user)
) s"lplus s#stemOlocalhost/,-
Then run logontrig"sDl)
Script &&' logontrig"sDl
create or replace trigger m#$set$date a'ter logon on data/ase
/egin
i' %user * 0>B0& then
e.ecute immediate 0alter session set nls$date$'ormat * 00;;;;-NN-LL00 0!
end i'!
end m#$set$date!
/
&(3
Tuning Connections to >uild #cala5le #ystems
Th!s "r!gger se"s "he sess!onKs da"e 'orma" e&er "!me HR connec"s "o "he da"abase 'rom an
cl!en" "ool. 7o"e "he use o' s!ngle >uo"es. The da"e 'orma" s"r!ng !s enclosed !n a pa!r o' "+o
>uo"es, +h!ch !s "he Oracle me"hod o' nes"!ng s!ngle >uo"es !ns!de a >uo"ed s"r!ng.
0!"h "he "r!gger, Oracle does all "he +or( se""!ng "he da"e 'orma" +hen "he phs!cal
da"abase connec"!on !s or!g!nall es"abl!shed and '!rs" used. 0hen PHP la"er uses a cached
connec"!on !" +!ll alread ha&e "he des!red da"e 'orma".
:n PHP, "he connec"!on 'unc"!on 'rom "he s"ar" o' "h!s sec"!on can be s!mpl!'!ed and
per'ormance !mpro&ed because !" no longer needs "o se" "he da"e 'orma".
Script &2' logontrig"php
<?php
'unction m#$connect%)un+ )pw+ )d/&
(
return%oci$pconnect%)un+ )pw+ )d/&&!
=
)c * m#$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ 0select s#sdate 'rom dual0&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo )row907;7L6:-0< . "</r2n"!
?
The scr!p" logontrig"php connec"s as HR us!ng "he no+ "r!&!al!1ed +y=connectNO and >uer!es
"he curren" da"e. :" sho+s "he ne+ 'orma" se" b "he "r!gger)
200U-05-0D
:' "he connec"!on !s an user o"her "han HR "he s"andard de'aul" da"e 'orma" +!ll be d!splaed,
'or e/ample)
0D-N6;-0U
Us!ng a "r!gger l!(e "h!s onl +or(s +hen "he re>u!red sess!on se""!ng !s "he same 'or all PHP
appl!ca"!on users "ha" share "he same da"abase user name.
The sugges"ed prac"!ce !s "o use .O3O7 "r!ggers onl 'or se""!ng sess!on a""r!bu"es and no"
'or e/ecu"!ng per PHP?connec"!on log!c such as cus"om logon aud!"!ng.
:' ou canno" use a "r!gger because each PHP !n&oca"!on needs d!''eren" se""!ngs, and ou
need more "han one 4B. s"a"emen" e/ecu"ed, ou can pu" "he s"a"emen"s !ns!de a P.<4B.
procedure. %'"er connec"!ng ou can call "he P.<4B. procedure, +h!ch !s one oci$e.ecute%&
call "o "he da"abase, !ns"ead o' mul"!ple calls "o e/ecu"e o"her 4B. s"a"emen"s.
5anage Per!i!tent Connection!
Pers!s"en" connec"!ons are grea" !' "he cos" o' open!ng a connec"!on !s h!gh. 0ha" ou
cons!der h!gh depends on our appl!ca"!on re>u!remen"s and on !mplemen"a"!on !ssues such
as +he"her "he +eb ser&er and da"abase are on "he same hos", +h!ch +!ll a''ec" "he "!me
"a(en "o es"abl!sh a connec"!on, and on memor a&a!lab!l!". The dra+bac( !s pers!s"en"
connec"!ons use Oracle resources e&en +hen no one !s access!ng "he appl!ca"!on or da"abase.
%nd !' %pache spa+ns a number o' ser&er processes, each o' "hem ma ha&e !"s o+n se" o'
connec"!ons "o "he da"abase. The prol!'era"!on o' connec"!ons can be con"rolled "o some
&(&
Connecting to .racle Bsing .C'1
e/"en" +!"h php"ini d!rec"!&es and %pache con'!gura"!on se""!ngs. :' connec"!on pool!ng !s used,
"he number o' connec"!ons can be (ep" small.
'aximum .umber o/ #ersistent Connections )llowed
oci8.ma.$persistent
Th!s parame"er l!m!"s "he number o' pers!s"en" connec"!ons cached b each !nd!&!dual
%pache?PHP process. :" !s a no" a ss"em?+!de res"r!c"!on on da"abase usage. 0hen "he l!m!" !s
reached b a PHP process, "hen all ne+ oci$pconnect%& calls are "rea"ed l!(e oci$connect%&
calls and are closed a" "he end o' "he scr!p". 4e""!ng !" "o ?1 C"he de'aul"F means "here !s no
l!m!". :' our PHP scr!p"s connec" us!ng "he same da"abase creden"!als, each PHP process +!ll
onl ha&e one connec"!on en"r !n !"s cache so "h!s se""!ng +!ll ha&e no e''ec" on our
appl!ca"!onAs resource usage.
Timeout /or Unused #ersistent Connections
oci8.persistent$timeout
Th!s parame"er !s "he leng"h !n seconds "ha" an %pache process ma!n"a!ns an !dle pers!s"en"
connec"!on. 4e""!ng "h!s parame"er "o ?1 C"he de'aul"F means "here !s no "!meou". :' a
connec"!on has been e/p!red, "he ne/" "!me oci$pconnect%& !s called a ne+ connec"!on !s
crea"ed.
:" !s no" an asnchronous "!mer. The e/p!r chec( happens +hene&er an PHP scr!p"
'!n!shes, regardless o' +he"her OC:$ calls +ere made. Onl "he pers!s"en" connec"!ons !n "he
!n&o(ed %pache process +!ll be chec(ed. Th!s !s an unresol&able +ea(ness +!"h PHP) ou +an"
!dle connec"!ons "o be closed, bu" !' PHP !s !dle "hen no scr!p"s e/ecu"e and "he "!meou" !s no"
"r!ggered. .uc(!l Oracle 11g DRCP ma(es "h!s !ssue !rrele&an".
#inging /or Closed #ersistent Connections
oci8.ping$interCal
There !s no guaran"ee "ha" "he connec"!on descr!p"or re"urned b oci$pconnect%& represen"s
a usable connec"!on "o "he da"abase. Dur!ng "he "!me PHP s"ored an unaccessed connec"!on
resource !n !"s cache, "he connec"!on "o "he da"abase ma ha&e become unusable due "o a
ne"+or( error, a da"abase error, or be!ng e/p!red b "he D-%. :' "h!s happens, oci$pconnect%&
appears "o be success'ul bu" an error !s "hro+n +hen "he connec"!on !s la"er used, 'or
e/ample !n oci$e.ecute%&. The p!ng !n"er&al !s an eas +a "o !mpro&e connec"!on rel!ab!l!"
'or pers!s"en" connec"!ons.
Th!s parame"er !s "he number o' seconds "ha" pass be'ore OC:$ does a p!ng dur!ng a
oci$pconnect%& call. :' "he p!ng de"erm!nes "he connec"!on !s no longer usable, a ne+
connec"!on !s "ransparen"l crea"ed and re"urned b oci$pconnect%&. To d!sable p!ng!ng, se"
"he &alue "o ?1. 0hen se" "o 0, PHP chec(s "he da"abase each "!me oci$pconnect%& !s called.
The de'aul" &alue !s O0 seconds.
Regardless o' "he &alue o' oci/"ping=interval, an oci$pconnect%& call +!ll al+as chec( an
!n"ernal Oracle cl!en"?s!de &alue "o see !' "he ser&er +as (no+n "o be a&a!lable "he las" "!me
an"h!ng +as rece!&ed 'rom "he da"abase. Th!s !s a >u!c( opera"!on. 4e""!ng oci/"ping=interval
&((
Tuning Connections to >uild #cala5le #ystems
phs!call sends a message "o "he ser&er, caus!ng a Dround?"r!pE o&er "he ne"+or(. Th!s !s a
Dbad "h!ngE 'or scalab!l!".
3ood appl!ca"!on des!gn grace'ull reco&ers 'rom 'a!lures. :n an appl!ca"!on "here are a
number o' po"en"!al po!n"s o' 'a!lure !nclud!ng "he ne"+or(, "he hard+are and user ac"!ons
such as shu""!ng do+n "he da"abase. Oracle !"sel' ma be con'!gured "o close !dle connec"!ons
and release "he!r da"abase resources. The da"abase adm!n!s"ra"or ma ha&e !ns"alled user
pro'!les +!"h CR;%T; PRO2:.; :D.;NT:M;OUT, or "he Oracle ne"+or( laer ma "!me ou" "he
ne"+or(.
Mou need "o balance per'ormance Cno p!ngsF +!"h ha&!ng "o handle d!sconnec"ed Oracle
sess!ons Cor o"her changes !n "he Oracle en&!ronmen"F !n our PHP code. 2or h!ghes" rel!ab!l!"
and scalab!l!" !" !s generall recommended "ha" ou do no" use oci/"ping=interval, bu" do
error reco&er !n our appl!ca"!on code.
)pache Con/iguration #arameters
Mou can "une %pache "o (!ll !dle processes, +h!ch +!ll 'ree up Oracle resources used b
pers!s"en" connec"!ons. Table H l!s"s some %pache pre?'or( model con'!gura"!on parame"ers
"ha" can be used "o "une PHP.
)able 4' Apache pre3*or1 con*iguration para+eters"
Para1eter Purpo!e
Na.Be"uestsEer4hild 4e"s ho+ man re>ues"s %pache +!ll ser&e be'ore res"ar"!ng.
Na.7pare7erCers 4e"s ho+ man ser&ers "o (eep !n memor "ha" are no" handl!ng
re>ues"s.
Geep6liCe De'!nes +he"her %pache can ser&e a number o' documen"s "o "he
one user o&er "he same HTTP connec"!on.
4e""!ng !ax:eDuestsPer-hild "oo lo+ +!ll cause pers!s"en" connec"!ons "o be closed more
o'"en "han perhaps necessar, remo&!ng an po"en"!al per'ormance ga!n o' cach!ng. Man
s!"es use !ax:eDuestsPer-hild "o res"ar" PHP occas!onall, a&o!d!ng an po"en"!al memor
lea(s or o"her un+an"ed beha&!ors.
Changing the #ata$a!e Pa!!;ord
The OC:$ e/"ens!on allo+s Oracle da"abase pass+ords "o be changed.
-e cau"!ous abou" chang!ng pass+ords +hen PHP pers!s"en" connec"!ons are used. Th!s !s
because a pers!s"en" connec"!on !s cached !n a PHP process us!ng "he or!g!nal pass+ord as
par" o' "he loo(?up (e. Th!s (e !s no" upda"ed +hen "he pass+ord !s changed. PHP
appl!ca"!ons +ould "here'ore allo+ an open pers!s"en" D- connec"!on "o be reused onl +hen
oci$pconnect%& !s g!&en "he old pass+ord. Th!s !s a secur!" !ssue s!nce (no+!ng "he old
pass+ord !s su''!c!en" "o ge" access "o "he da"abase. :" can also cause e/"ra da"abase load
because users connec"!ng +!"h "he ne+ pass+ord +!ll crea"e a ne+ pers!s"en" connec"!on "o
"he da"abase, lea&!ng "he or!g!nal connec"!on !dle.
Changing Pa!!;ord! on #e1and
%'"er connec"!ng, a pass+ord can be changed +!"h oci$password$change%&)
&()
Connecting to .racle Bsing .C'1
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
oci$password$change%)c+ 0hr0+ 0welcome0+ 0new$password0&!
4ubse>uen" scr!p"s ma no+ connec" us!ng)
)c * oci$connect%0hr0+ 0new$password0+ 0localhost/,-0&!
Changing Epired Pa!!;ord!
4ome"!mes connec"!on ma 'a!l because "he pass+ord !s no longer &al!d. 2or e/ample, "he
D-% ma ha&e se" a pass+ord pol!c us!ng CR;%T; PRO2:.; "o e/p!re pass+ords a" a cer"a!n
"!me, or "he ma ha&e e/p!red a pass+ord !mmed!a"el +!"h %.T;R U4;R, 'orc!ng "he user "o
choose a ne+ pass+ord "he ne/" "!me "he connec". 0hen "he user "r!es "o connec", "he!r
pass+ord !s recogn!1ed bu" "he ge" an O:A32/AA&' the pass,ord has expired message and
+!ll no" be able "o comple"e "he!r log on. :n "h!s case, !ns"ead o' "he user ha&!ng "o bo"her "he
D-% "o manuall rese" "he e/p!red pass+ord, oci$password$change%& can be used "o re?
connec" and change "he pass+ord one opera"!on. The ne/" e/ample sho+s "h!s !n ac"!on.
Script &6' connectexpired"sDl
drop user peregrine cascade!
create user peregrine identi'ied /# a/c!
grant create session to peregrine!
alter user peregrine password e.pire!
Script &5' connectexpired"php
<?php
)un * "peregrine"! // Mew temporar# user to /e created.
)pw * "a/c"! // 5nitial password 'or )un
)d/ * "localhost/,-"! // Lata/ase to connect to
'unction do$connect%)un+ )pw+ )d/&
(
echo "4alling oci$connect%&</r2n"!
)c * oci$connect%)un+ )pw+ )d/&!
i' %)c& (
echo "4onnected success'ull#</r2n"!
=
else (
)e * oci$error%&!
i' %)e90code0< ** 28001& (
// 4onnect and change the password to a new one 'ormed /#
// appending 0.0 to the original password.
// 5n an application #ou could prompt the user to choose
// the new password.
echo "4onnection 'ailed: the password 'or )un has e.pired</r2n"!
)c * change$and$connect%)un+ )pw+ )pw."."+ )d/&!
=
else (
echo "-rror: "+ )e9"message"<+ "</r2n"!
&(*
Changing the Data5ase !ass/ord
e.it!
=
=
return%)c&!
=
'unction change$and$connect%)un+ )oldpw+ )newpw+ )d/&
(
echo "4alling oci$password$change%& to connect</r2n"!
// Mote )d/ is a connection identi'ier string+ not a E>E connection resource
)c * oci_password_change($db $!n $o"dpw $newpw)!
i' %8)c& (
)e * oci$error%&!
echo "-rror: "+ )e9"message"<+ "</r2n"!
=
else (
echo "4onnected and changed password to )newpw</r2n"!
=
return%)c&!
=
'unction show$user%)c&
(
)s * oci$parse%)c+ "select user 'rom dual"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
echo ";ou are connected as ()res90R7-B0<90<=</r2n"!
=
// 4onnect as )un and con'irm connection succeeded
)c * do$connect%)un+ )pw+ )d/&!
show$user%)c&!
?
-e'ore runn!ng "he PHP scr!p", '!rs" run connectexpired"sDl as a pr!&!leged user)
) s"lplus s#stemOlocalhost/,- Oconnecte.pired.s"l
:n "he PHP scr!p", +hen oci$connect%& !n do$connect%& 'a!ls +!"h an O:A32/AA&' the
pass,ord has expired error, change$and$connect%& !s called "o change "he pass+ord and
connec" !n a s!ngle s"ep. :n "h!s e/ample, "he ne+ pass+ord !s s!mpl 'ormed b
conca"ena"!ng an D/E "o "he curren" pass+ord. :n an appl!ca"!on, "he user +ould be promp"ed
'or "he ne+ pass+ord.
The ou"pu" o' connectexpired"php !s)
4alling oci$connect%&
4onnection 'ailed: the password 'or peregrine has e.pired
4alling oci$password$change%& to connect
4onnected and changed password to a/c.
;ou are connected as E-B-YB5M-
The pass+ord change call oci$password$change%)d/+ )un+ )oldpw+ )newpw& d!''ers 'rom "he
e/ample !n "he pre&!ous sec"!on -hanging Pass,ords On De+and !n "ha" !" passes a da"abase
connec"!on !den"!'!er !den"!'!er s"r!ng, 0localhost/,-0, as "he '!rs" parame"er !ns"ead o'
&(+
Connecting to .racle Bsing .C'1
pass!ng "he connec"!on resource o' an alread opened connec"!on. Th!s ne+ usage connec"s
"o "he da"abase and changes "he pass+ord "o )newpw all a" "he same "!me. 4ubse>uen" scr!p"s
+!ll be able "o connec" us!ng "he ne+ pass+ord.
Th!s me"hod o' connec"!ng +!"h oci$password$change%& also +or(s !' "he pass+ord has
not e/p!red.
,uthori8ation and ,uthentication With Client Identi*ier!
%ppl!ca"!ons "ha" connec" "o "he da"abase &!a "he one se" o' Oracle creden"!als should use
oci$set$client$identi'ier%& so "he da"abase can d!s"!ngu!sh be"+een !nd!&!dual +eb
appl!ca"!on users.
The @cl!en" !den"!'!er@ !s a small s"r!ng !den"!'!er "o(en ou se" 'or each connec"!on and
+h!ch !s passed !n"o "he da"abase. 2or e/ample, !' our +eb appl!ca"!on phs!call connec"s "o
"he da"abase as "he da"abase user phpuser, and !' "+o d!''eren" people AChr!sA and A%l!sonA are
us!ng "he s!"e, "hese "+o user names could be se" as "he!r respec"!&e cl!en" !den"!'!ers.
- assoc!a"!ng a un!>ue cl!en" !den"!'!er +!"h each +eb user, Oracle Da"abase can)
Pro&!de an aud!" "ra!l on !nd!&!dual +eb users, 'or e/ample on AChr!sA and A%l!sonA
%u"oma"!call appl rules "o !nd!&!dual +eb users "o res"r!c" "he!r da"a access
Mon!"or and "race appl!ca"!ons per +eb user
:' ou donA" se" cl!en" !den"!'!ers, all da"abase ac"!&!" !s onl recorded as com!ng 'rom
phpuser"
Setting Client Identi*ier!
;ach PHP '!le !n a "p!cal Oracle PHP appl!ca"!on calls oci$pconnect%& +!"h an !den"!cal
da"abase user name. Once "he appl!ca"!onAs o+n au"hen"!ca"!on ss"em dec!des a par"!cular
+eb user !s O6, "hen a un!>ue "o(en !s passed bac( and 'or"h !n HTTP responses and re>ues"s
so "ha" "he +eb user doesnA" ha&e "o re?au"hen"!ca"e each "!me a ne+ +eb page !s loaded..
Cl!en" !den"!'!ers should be se" +!"h oci$set$client$identi'ier%& a'"er connec"!ng bu"
be'ore e/ecu"!ng an s"a"emen"s or OC:$ calls on behal' o' "he +eb user. %" !"s mos" bas!c, "he
cl!en" !den"!'!er could be "he +eb userAs name +h!ch +as &al!da"ed and s"ored !n PHPAs sess!on
da"a b a pre&!ous au"hen"!ca"!on scr!p" re>ues")
session$start%&!
)c * oci$pconnect%0phpuser0+ 0welcome0+ 0localhost/orcl0&!
oci$set$client$identi'ier%)c+ )$7-7753M90app$user$name0<&!
. . .
:' "he !den"!" o' "he end user al"ers dur!ng "he run "!me o' "he scr!p" Cperhaps !' PHP !s
e/ecu"!ng a long runn!ng command?l!ne process, or perhaps !n an adm!n!s"ra"!&e +eb page
"ha" runs d!''eren" componen"s represen"!ng d!''eren" end usersF "hen
oci$set$client$identi'ier%& can be called a" each po!n" "he end?user !den"!" changes)
)c * oci$pconnect%0phpuser0+ 0welcome0+ 0localhost/orcl0&!
)m#user * 04hris0!
oci$set$client$identi'ier%)c+ )m#user&!
. . .
)m#user * 06lison0!
oci$set$client$identi'ier%)c+ )m#user&!
&(-
Authorization and Authentication With Client 'dentiAiers
. . .
:n prac"!ce, cons!der us!ng more secure &alues 'or !den"!'!ers.
Cl!en" !den"!'!ers can be se" +hen us!ng oci$connect%&, oci$new$connect%&, or
oci$pconnect%& connec"!on calls. :den"!'!ers can be used +hen "he da"abase !s con'!gured "o
use an o' "he "hree "pes o' ser&er processes) @Ded!ca"ed@ ser&ers, @4hared@ ser&ers, and
+hen us!ng Da"abase Res!den" Connec"!on Pool!ng CDRCPF ser&ers.
The oci$set$client$identi'ier%& 'unc"!on +as !n"roduced !n PHP OC:$ 1.J C'!rs" !ncluded
!n PHP H.I.1F. 0!"h older &ers!ons o' OC:$ ou can use "he P.<4B. D-M4N4;44:O7 pac(age
!ns"ead)
session$start%&!
)c * oci$pconnect%0phpuser0+ 0welcome0+ 0localhost/orcl0&!
)s * oci$parse%)c+ "/egin d/ms$session.set$identi'ier%:id&! end!"&!
oci$/ind$/#$name%)s+ ":id"+ )$7-7753M90app$user$name0<&!
oci$e.ecute%)s&!
The oci$set$client$identi'ier%& 'unc"!on !s pre'erred because unl!(e
D-M4N4;44:O7.4;TN:D;7T:2:;R !" doesnA" 'orce a da"abase round?"r!p re>ues"?and?response.
0!"h "he PHP 'unc"!on, "he !den"!'!er !s p!gg?bac(ed on an subse>uen" OC:$ call "ha" ac"uall
does reach "he da"abase 'rom PHP. Th!s a&o!ds unnecessar round?"r!ps +h!ch slo+ do+n each
PHP page and !mpac" appl!ca"!on scalab!l!".
PHP OC:$ does no" clear "he cl!en" !den"!'!er a" "he end o' an HTTP re>ues" s!nce "he
o&erhead o' a round?"r!p "o clear "he &alue +ould !mpac" scalab!l!" o' e&er appl!ca"!on. Th!s
!s no" de"r!men"al 'or s"andard oci$connect%& connec"!ons s!nce "he da"abase connec"!on !s
des"roed a" "he end o' "he HTTP re>ues" and "he !den"!'!er &alue !s cleared as a resul".
Ho+e&er !den"!'!ers ma rema!n !n e''ec" across +eb re>ues"s "ha" use oci$pconnect%&
pers!s"en" connec"!ons. To a&o!d an !ncorrec" or no !den"!'!er be!ng recorded b "he da"abase,
all PHP '!les "ha" connec" "o "he da"abase should se" "he !den"!'!er so !" !s correc" 'or "he
dura"!on o' "he re>ues"As e/ecu"!on. :' man connec"!ons are !dle caus!ng mon!"or!ng "o be
a''ec"ed b sho+!ng apparen"l s"!ll connec"ed +eb users, "hen e&er scr!p" "ha" se"s "he
cl!en" !den"!'!er should 'orce'ull clear !" a" "he scr!p" end +!"h)
)s * oci$parse%)c+ "/egin d/ms$session.clear$identi'ier! end!"&!
oci$e.ecute%)s&!
Th!s causes a round?"r!p "o "he da"abase, +h!ch +!ll !mpac" scalab!l!".
PHPAs oci$set$client$identi'ier%& corresponds "o se""!ng OracleAs C le&el
OC:N%TTRNC.:;7TN:D;7T:2:;R a""r!bu"e. Oracle l!"era"ure on "h!s, and on P.<4B.As e>u!&alen"
D-M4N4;44:O7.4;TN:D;7T:2:;R, pro&!des good re'erences abou" cl!en" !den"!'!ers.
, Sa1ple ,pplication 0!ing Client Identi*ier!
% sample PHP @Par"s@ appl!ca"!on !llus"ra"es ho+ cl!en" !den"!'!ers can be used !n "he OC:$
e/"ens!on. O&erall, "he appl!ca"!on sho+s an !n&en"or o' elec"r!cal and plumb!ng par"s. %n
appl!ca"!on?le&el au"hen"!ca"!on ss"em handles +eb user log!ns. 2or success'ul log!ns, an
!den"!'!er "ha" !s un!>ue 'or each +eb user !s passed be"+een HTTP re>ues"s !n PHPAs sess!on
da"a. :" !s used 'or "he cl!en" !den"!'!er &alue. The appl!ca"!on has 8us" enough comple/!" so
"he Oracle "echnolog!es be!ng d!scussed are no" abs"rac", bu" !" !s no ,here near a produc"!on
e/ample. The sample appl!ca"!on !s s!mpl !n"ended "o sho+ "he rela"!onsh!p be"+een "he +eb
user and "he da"abase user, and "o sho+ ho+ a cl!en" !den"!'!er can be used !n "he da"abase.
PHP sess!on managemen" re>u!res care'ul des!gn "o m!n!m!1e secur!" !ssues. There are man
&(0
Connecting to .racle Bsing .C'1
e/"ernal re'erences d!scuss!ng "h!s problem +h!ch should be closel s"ud!ed b e&er PHP
de&eloper. M!chael Mc.aughl!nAs OT7 ar"!cle Database3Iased Authentication *or PHP Apps !s a
good place "o beg!n read!ng more.
The core o' "he Par"s appl!ca"!on !s a setup"sDl '!le "ha" crea"es "he da"abase ob8ec"s. %ll
"he PHP scr!p"s !n "he appl!ca"!on +!ll connec" "o "he da"abase us!ng "he PHPU4;R schema,
+h!ch o+ns "he P%RT4 appl!ca"!on "able. The 4B. scr!p" crea"es a second user
PHPN4;CN%DM:7 "o hold secur!" !n'orma"!on abou" "he appl!ca"!on. Th!s user !s g!&en some
e/"ra da"abase pr!&!leges needed 'or "he aud!"!ng e/ample, sho+n la"er. The
PHPN%UTH;7T:C%T:O7 "able con"a!ns "he appl!ca"!on user names and pass+ords. Buer
access on "h!s "able !s gran"ed "o "he PHPU4;R user so "he PHP appl!ca"!on onl has "o open
one connec"!on "o "he da"abase, bu" "ha" connec"!on canno" mod!' "he secur!" !n'orma"!on.
Script &4' setup"sDl
set echo on
-- 4reate E>E application user
connect s#stem/s#stempwd
-- 4reate the E>E application user
drop user phpuser cascade!
create user phpuser identi'ied /# welcome!
grant connect+ resource to phpuser!
alter user phpuser de'ault ta/lespace users
temporar# ta/lespace tnt unlock!
-- 4reate user owner securit# in'ormation a/out the application
drop user php$sec$admin cascade!
create user php$sec$admin identi'ied /# welcome!
alter user php$sec$admin de'ault ta/lespace s#stem
temporar# ta/lespace temp account unlock!
grant create procedure+ create session+ create ta/le+
resource+ select an# dictionar# to php$sec$admin!
connect phpuser/welcome
-- "Earts" ta/le 'or the application demo
create ta/le parts
%id num/er primar# ke#+
categor# Carchar2%20&+
name Carchar2%20&&!
insert into parts Calues %1+ 0electrical0+ 0lamp0&!
insert into parts Calues %2+ 0electrical0+ 0wire0&!
insert into parts Calues %@+ 0electrical0+ 0switch0&!
insert into parts Calues %D+ 0plum/ing0+ 0pipe0&!
insert into parts Calues %5+ 0plum/ing0+ 0sink0&!
insert into parts Calues %P+ 0plum/ing0+ 0toilet0&!
commit!
connect php$sec$admin/welcome
-- 6uthentication ta/le with the we/ user user names ^ passwords.
-- 6 real application would M-Z-B store plain-te.t passwords /ut this
&(1
Authorization and Authentication With Client 'dentiAiers
-- article is a/out uses o' client identi'iers and not a/out
-- authentication.
create ta/le php$authentication
%app$username Carchar2%20& primar# ke#+
app$password Carchar2%20& not null&!
insert into php$authentication Calues %0chris0+ 0tiger0&!
insert into php$authentication Calues %0alison0+ 0red0&!
commit!
grant select on php$authentication to phpuser!
Produc"!on appl!ca"!ons +ould no" use such s!mple pass+ords and +ould never s"ore clear
"e/" pass+ords !n "ables. %ppl!ca"!ons could do end user au"hen"!ca"!on !n a number o' +as,
!nclud!ng us!ng .D%P.
;ach scr!p" !n "he PHP appl!ca"!on needs "o (no+ "he Oracle D- creden"!als so "he are
s"ored !n a common !nclude '!le dbin*o"inc"php)
Script &9' dbin*o"inc"php
<?php
// 6ll connections to the data/ase use these credentials
de'ine%"3B6$43M$RM"+ "phpuser"&!
de'ine%"3B6$43M$E?"+ "welcome"&!
de'ine%"3B6$43M$LI"+ "localhost/orcl"&!
?
:n real l!'e, cons!der us!ng Oracle 0alle" Manager and connec"!ng +!"h OC:NCR;DN;=T !ns"ead
o' hard cod!ng "he da"abase pass+ord.
The appl!ca"!on log!n page !s a "p!cal s!mple PHP scr!p" "ha" +hen '!rs" loaded d!splas a
'orm)
The code "ha" genera"es "h!s 'orm loo(s l!(e)
Script &?' login"php
<?php
re"uire$once%0./d/in'o.inc.php0&!
session$start%&!
'unction login$'orm%)message&
&(2
(igure 4/' Fogin page o* login"php"
Connecting to .racle Bsing .C'1
(
echo <<<-3L
</od# st#le*"'ont-'amil#: 6rial+ sans-seri'!"
<h2Kogin Eage</h2
<p)message</p
<'orm action*"login.php" method*"E37:"
<pRsername: <input t#pe*"te.t" name*"username"</p
<pEassword: <input t#pe*"te.t" name*"password"</p
<input t#pe*"su/mit" Calue*"Kogin"
</'orm
<//od#
-3L!
=
i' %8isset%)$E37:90username0<& [[ 8isset%)$E37:90password0<&& (
login$'orm%0?elcome0&!
= else (
// 4heck Calidit# o' the supplied username ^ password
)c * oci$pconnect%3B6$43M$RM+ 3B6$43M$E?+ 3B6$43M$LI&!
// Rse a "/ootstrap" identi'ier 'or this administration page
oci$set$client$identi'ier%)c+ 0admin0&!
)s * oci$parse%)c+ 0select app$username
'rom php$sec$admin.php$authentication
where app$username * :un$/C
and app$password * :pw$/C0&!
oci$/ind$/#$name%)s+ ":un$/C"+ )$E37:90username0<&!
oci$/ind$/#$name%)s+ ":pw$/C"+ )$E37:90password0<&!
oci$e.ecute%)s&!
)r * oci$'etch$arra#%)s+ 345$67734&!
i' %)r& (
// :he password matches: the user can use the application
// 7et the user name to /e used as the client identi'ier in
// 'uture >::E re"uests:
)$7-7753M90username0< * )$E37:90username0<!
echo <<<-3L
</od# st#le*"'ont-'amil#: 6rial+ sans-seri'!"
<h2Kogin was success'ul</h2
<p<a hre'*"application.php"Bun the 6pplication</a<p
<//od#
-3L!
=
else (
// Mo rows matched so login 'ailed
login$'orm%0Kogin 'ailed. Zalid usernames/passwords 0 .
0are "chris/tiger" and "alison/red"0&!
=
=
&)3
Authorization and Authentication With Client 'dentiAiers
?
:' ou cop "h!s code, ma(e sure "he -3L @heredoc@ "o(ens are a" "he &er s"ar" o' "he!r l!nes.
2or 'orm subm!ss!on, "he scr!p" calls bac( "o !"sel', +h!ch no+ &al!da"es "he en"ered user
name and pass+ord aga!ns" "he users !n "he PHPN%UTH;7T:C%T:O7 "able. % cl!en" !den"!'!er o'
admin !s se" as a boo"s"rap &alue s!nce a" "h!s !n!"!al po!n" +e donA" (no+ !' +e ha&e a &al!d
end user and also "he log!n scr!p" !s an adm!n!s"ra"!&e componen" no" do!ng an ac"ual
appl!ca"!on +or( on behal' o' an end user.
2rom "he log!n page, au"hen"!ca"ed users can cl!c( "o "he appl!ca"!on !n&en"or page)
The user name !s passed "o "he appl!ca"!on page !n PHP sess!on da"a as
)$7-7753M90username0<. Th!s &alue +!ll be used as "he cl!en" !den"!'!er 'or "he +eb user. :n a
real appl!ca"!on a less ob&!ous !den"!'!er +ould be recommended. 2or e/ample, as par" o'
appl!ca"!on au"hen"!ca"!on 'or a success'ul end?user log!n, an !n!"!al loo(?up >uer or P.<4B.
'unc"!on could re"urn a pre?compu"ed obscure &alue "o be used as "he userAs cl!en" !den"!'!er.
Th!s &alue +ould "hen be s"ored !n "he PHP sess!on !n'orma"!on 'or use !n subse>uen" @real@
appl!ca"!on +or(. %n obscure &alue +ould ma(e !" harder 'or a""ac(ers "o pred!c" !den"!'!er
&alues. %lso an !den"!'!er could be >u!c(l changed !' "here +as e&er a concern abou" "he
au"hen"!c!" o' HTTP re>ues"s us!ng !".
The appl!ca"!on page application"php chec(s "ha" "he user !s au"hen"!ca"ed ? "h!s
appl!ca"!onAs de'!n!"!on o' an au"hen"!ca"ed user !s s!mpl "ha" a user name !s se". The code
"hen se"s "he cl!en" !den"!'!er and sho+s "he !n&en"or l!s" b >uer!ng "he P%RT4 "able)
Script &/' application"php
<?php
re"uire$once%0./d/in'o.inc.php0&!
session$start%&!
// 4heck the user is logged in according to our application authentication
i' %8isset%)$7-7753M90username0<&& (
echo <<<-3L
<h2RnauthoriXed</h2
<p;ou are not authenticated.</r
Zalid usernames/passwords are "chris/tiger" and "alison/red"<p
<p<a hre'*"login.php"Kogin Eage</a<p
-3L!
e.it!
=
// Yenerate the application page
)c * oci$pconnect%3B6$43M$RM+ 3B6$43M$E?+ 3B6$43M$LI&!
&)&
(igure 48' Success*ul login in login"php
Connecting to .racle Bsing .C'1
// 7et the client identi'ier a'ter eCer# connection call
// using a Calue uni"ue 'or the we/ end user.
oci$set$client$identi'ier%)c+ )$7-7753M90username0<&!
)username * htmlentities%)$7-7753M90username0<+ -M:$SR3:-7&!
echo <<<-3L
</od# st#le*"'ont-'amil#: 6rial+ sans-seri'!"
<h2Earts 4ompan#</h2
<ta/le /order*010
<caption</5nCentor# 'or )username <//</caption
-3L!
)s * oci$parse%)c+ "select J 'rom parts order /# id"&!
oci$e.ecute%)s&!
while %%)row * oci$'etch$arra#%)s+ 345$67734H345$B-:RBM$MRKK7&&
8* 'alse& (
echo "<tr2n"!
'oreach %)row as )item& (
echo " <td" .
%)item8**null?htmlentities%)item+ -M:$SR3:-7&:"^n/sp!"& .
"</td2n"!
=
echo "</tr2n"!
=
echo <<<-3L
</ta/le
<p<a hre'*"logout.php"Kogout</a</p
<//od#
-3L!
?
0hen logged !n as Chr!s, "he appl!ca"!on sho+s)
&)(
(igure 9A' Parts report *or -hris"
Authorization and Authentication With Client 'dentiAiers
% logou" scr!p" clears PHPAs sess!on !n'orma"!on)
Script &8' logout"php
<?php
session$start%&!
unset%)$7-7753M90username0<&!
echo <<<-3L
</od# st#le*"'ont-'amil#: 6rial+ sans-seri'!"
<h2Yood/#e</h2
<p;ou are logged out.<p
<p<a hre'*"login.php"Kogin Eage</a<p
<//od#
-3L!
?
The logou" page does no" call d/ms$session.clear$identi'ier "o clear "he da"abase
connec"!onAs !den"!'!er) "ha" +ould need "o be done a" "he end o' all "he '!les "ha" use a
da"abase connec"!on !' "here +as concern abou" "he e''ec" on mon!"or!ng due "o "he !den"!'!ers
no" be!ng cleared.
The same appl!ca"!on code +!ll be used !n "he ne/" sec"!ons +!"hou" an mod!'!ca"!ons.
To summar!1e, "h!s s!mple appl!ca"!on !s des!gned "o sho+ "he rela"!onsh!p be"+een
da"abase users and end users so "ha" cl!en" !den"!'!ers can be d!scussed. :" does no"
cons"!"u"e a su!"able e/ample 'or produc"!on use. The appl!ca"!on se"s a cl!en" !den"!'!er +!"h
oci$set$client$identi'ier%& !mmed!a"el a'"er each oci$pconnect%& connec"!on call. Th!s
!den"!'!er un!>uel !den"!'!es "he end user +ho !s s!""!ng a" h!s or her +eb bro+ser. 2or e/!s"!ng
real?l!'e appl!ca"!ons, add!ng a call "o oci$set$client$identi'ier%& +!"h a un!>ue !den"!'!er
per +eb user !s "he onl appl!ca"!on change "ha" needs "o be made "o "a(e ad&an"age o' cl!en"
!den"!'!ca"!on.
0!ing a Client Identi*ier in PHP *or ,uditing
%ud!"!ng le"s ou)
:den"!' !nappropr!a"e da"abase changes
:n&es"!ga"e susp!c!ous ac"!&!"
,er!' au"hor!1a"!on or access con"rol pol!c!es
4a"!s' bus!ness compl!ance regula"!ons
3a"her da"a abou" da"abase ac"!&!"!es 'or use !n capac!" and resource alloca"!on plann!ng
Oracle aud!"!ng !s po+er'ul and mul"!?'ace"ed. Mou can aud!" general ac"!&!"!es such as "he
"pe o' 4B. s"a"emen" e/ecu"ed. Mou can aud!" '!ne gra!ned ac"!&!"!es such as +hen spec!'!c
&alues occur, or +ha" :P address !n!"!a"ed a re>ues". %ud!"!ng can occur on bo"h success'ul
and 'a!led ac"!&!"!es. The aud!" "ra!l can be s"ored !ns!de "he da"abase or ou"s!de !", su!"able 'or
anals!s +!"h &ar!ous "ools. %ud!"!ng !s a&a!lable !s &ar!ous 'orms !n d!''eren" ed!"!ons o' "he
da"abase. The 'ull D2!ne 3ra!ned %ud!"!ngE 'ea"ure !s a&a!lable +!"h Oracle Da"abase
;n"erpr!se ;d!"!on.
&))
Connecting to .racle Bsing .C'1
4e""!ng a cl!en" !den"!'!er allo+s aud!"!ng "o be assoc!a"ed +!"h un!>ue +eb users, and no"
8us" +!"h "he da"abase schema o+ner +ho au"hen"!ca"ed "he PHP OC:$ oci$pconnect%& call "o
"he da"abase.
The auditon"sDl scr!p" !s a bas!c e/ample o' >uer aud!"!ng on "he P%RT4 "able)
Script 2A' auditon"sDl
-- :urn on o/Wect auditing 'or the E6B:7 ta/le
connect s#stem/s#stempwd
audit select on phpuser.parts /# access!
Run autiton"sDl !n 4B.SPlus. Then run "he appl!ca"!on and log!n as Achr!sA or Aal!sonA C"he!r
pass+ords are se" "o A"!gerA and AredA respec"!&el !n setup"sDlF. Mou can e&en >uer "he "able
as "he 4M4T;M user !n 4B.SPlus ou"s!de "he appl!ca"!on)
7SK select J 'rom phpuser.parts!
Th!s re"urns "he e/pec"ed par"s l!s".
To sho+ "he aud!" "ra!l 'rom all "hese "able accesses, "he 4B. scr!p" auditreport"sDl >uer!es
"he D-%N%UD:TNTR%:. &!e+, +h!ch con"a!ns "he aud!" da"a +hen "he da"abase !n!"!al!1a"!on
parame"er %UD:TNTR%:. !s se" "o D-.
Script 2&' auditreport"sDl
-- Ziew the audit trail 'or the E6B:7 ta/le
connect s#stem/s#stempwd
set pagesiXe 100
col app$username 'ormat a1@
col username 'ormat a1@
col e.tended$timestamp 'ormat a@U
col action$name 'ormat a1@
select auth.app$username+
dat.username+
e.tended$timestamp+
action$name
'rom d/a$audit$trail dat
le't outer Woin
php$sec$admin.php$authentication auth
on auth.app$username * client$id
where o/W$name * 0E6B:70
order /# e.tended$timestamp!
Runn!ng "he repor" sho+s "he "!me each +eb user accessed "he P%RT4 "able)
6EE$R7-BM6N- R7-BM6N- -,:-ML-L$:5N-7:6NE 64:53M$M6N-
------------- ------------- ------------------------------------- -------------
chris E>ER7-B 1P-6RY-10 12.25.D2.8DP15@ EN -0U:00 7-K-4:
alison E>ER7-B 1P-6RY-10 12.25.50.8U0UU@ EN -0U:00 7-K-4:
7;7:-N 1P-6RY-10 12.25.58.PP0922 EN -0U:00 7-K-4:
&)*
Authorization and Authentication With Client 'dentiAiers
There !s no %PPNU4;R7%M; sho+n 'or "he 4M4T;M user because "here +as no cl!en" !den"!'!er
se" !n "he 4B.SPlus sess!on. 4ome"!mes !den"!'!ng da"a accesses +here "he cl!en" !den"!'!er !s
no" correc"l se" !s "he des!red aud!"!ng goal. OracleAs 2!ne?3ra!ned %ud!"!ng can be used "o
aud!" spec!'!c e&en"s l!(e "h!s, help!ng mon!"or susp!c!ous ac"!&!". Th!s can be use'ul +hen
cl!en" !den"!'!ers are used b ,!r"ual Pr!&a"e Da"abases "o res"r!c" da"a access bu" comple"e
aud!"!ng !s no" re>u!red.
0hen ou are '!n!shed e/plor!ng "he e/ample, ou can "urn aud!"!ng o'' us!ng "he M36RL5:
command !n 4B.SPlus)
Script 22' audito**"sDl
-- :urn o'' o/Wect auditing 'or the E6B:7 ta/le
connect s#stem/s#stempwd
noaudit all on phpuser.parts!
More !n'orma"!on abou" aud!"!ng can be 'ound !n "he 7eri*ying Security Access ,ith Auditing
chap"er o' "he Oracle Database Security Guide &&g :elease 2 N&&"2O manual.
0!ing a Client Identi*ier in PHP With a <P# *or :e!tricting #ata ,cce!s
.!m!"!ng access "o a&o!d m!suse o' sens!"!&e da"a !s an arch!"ec"ural goal o' all appl!ca"!ons.
Oracle PHP appl!ca"!ons can use "he cl!en" !den"!'!er "o res"r!c" da"a access !n a manuall
coded or an au"oma"!c +a. The manual +a !s "o mod!' e&er 4B. and P.<4B. s"a"emen" "o
use s#s$conte.t%&, +h!ch re"urns "he cl!en" !den"!'!er o' "he PHP connec"!on. 2or e/ample,
>uer!es could be +r!""en "o re"urns ro+s 'rom P%RT4 onl +hen "he !den"!'!er o' "he curren"
connec"!on !s Achr!sA)
select J 'rom parts
where s#s$conte.t%0userenC0+ 0client$identi'ier0& * 0chris0!
0hen %l!son Cor an user +!"h a d!''eren" cl!en" !den"!'!erF !s connec"ed, "hen "he 0H;R;
clause e&alua"es "o 'alse and no ro+s +!ll be re"urned. Th!s (!nd o' log!c !s cumbersome "o
code and error prone "o cons!s"en"l !mplemen" e&er+here. Oracle Da"abase ;n"erpr!se
;d!"!onAs ,!r"ual Pr!&a"e Da"abase C,PDF "echnolog comes "o "he rescue. :" +!ll au"oma"!call
add a 0H;R; pred!ca"e "o each s"a"emen" "he appl!ca"!on e/ecu"es.
To se" up ,PD, a P.<4B. 'unc"!on "ha" re"urns "he des!red "e/" o' "he res"r!c"!&e 0H;R;
clause needs "o be crea"ed. To au"oma"!call res"r!c" da"a re"urned 'rom "he >uer select J
'rom parts "he P.<4B. 'unc"!on +ould 8us" need "o re"urn "he s"r!ng)
s#s$conte.t%0userenC0+ 0client$identi'ier0& * 0chris0
0!"h ,PD enabled "o use such a 'unc"!on, "he >uer 'rom P%RT4 +ould be e/ecu"ed b Oracle
as !' !" had "he res"r!c"!&e 0H;R; clause, resul"!ng !n "he same appl!ca"!on beha&!or as
d!scussed abo&e 'or "he manual !mplemen"a"!on. Techn!call Oracle uses a "rans!en" &!e+ "ha"
en'orces "he 0H;R; clause and re+r!"es "he appl!ca"!on >uer "o use "he &!e+ !ns"ead o' "he
base "able, as descr!bed !n "he ,PD documen"a"!on. Regardless o' "he !mplemen"a"!on de"a!ls,
Oracle "ransparen"l handles "he au"hor!1a"!on, so secur!" !s cons!s"en" and programmers
can be more produc"!&e on o"her "as(s. Remember "ha" 'rom "he da"abase perspec"!&e, cl!en"
!den"!'!ers are @!nsecure@ because "he da"abase has "o rel on e/"ernall pro&!ded !n'orma"!on
'or pol!c en'orcemen". Th!s !s "he ou"come o' us!ng shared da"abase connec"!ons and m!ddle?
"!er au"hen"!ca"!on !n a s"a"eless +eb arch!"ec"ure and !" places a rel!ance on ha&!ng correc"
appl!ca"!on code.
&)+
Connecting to .racle Bsing .C'1
2or "he Par"s appl!ca"!on, "he 4B. scr!p" vpdon"sDl se"s up ,PD. 2!rs" !" crea"es an
appl!ca"!on spec!'!c "able o' pr!&!leges. :n "h!s e/ample Chr!s can onl see elec"r!cal !"ems bu"
%l!son can see elec"r!cal and plumb!ng suppl!es. The ,PD pol!c 'unc"!on 2NPO.:CMNP%RT4
re"urns a sub>uer "ha" chec(s "he curren" cl!en" !den"!'!er has access "o "he par" ca"egor o'
"he ro+. %l"hough 2NPO.:CMNP%RT4 !s passed "he schema and "able name "ha" "he pol!c !s
be!ng appl!ed "o, !n "h!s e/ample "he pol!c !s onl used 'or one "able so "he 'unc"!on
parame"ers are no" re'erenced. 0!"h "he pol!c 'unc"!on de'!ned, "he D-M4NR.4.%DDNPO.:CM
procedure !s used "o enable !" 'or "he P%RT4 "able.
Script 26' vpdon"sDl
set echo on
connect / as s#sd/a
grant e.ecute on s#s.d/ms$rls to php$sec$admin!
connect php$sec$admin/welcome
-- 6pplication polic# ta/le
drop ta/le php$priCs!
create ta/le php$priCs %username Carchar2%PD&+ categor# Carchar2%20&&!
-- 4hris should onl# see electrical items. 6lison can see
-- electrical and plum/ing items
insert into php$priCs Calues %0chris0+ 0electrical0&!
insert into php$priCs Calues %0alison0+ 0electrical0&!
insert into php$priCs Calues %0alison0+ 0plum/ing0&!
commit!
grant select on php$priCs to phpuser!
-- Eolic# 'unction A$E3K54;$E6B:7 returns a "?>-B-" clause to restrict access
create or replace 'unction '$polic#$parts
%schema in Carchar2+ ta/ in Carchar2& return Carchar2
as
predicate Carchar2%D00&!

/egin
predicate :*
0categor# in
%select categor#
'rom php$sec$admin.php$priCs
where username * s#s$conte.t%00userenC00+ 00client$identi'ier00&&0!
return predicate!
end!
/
show errors
/egin
d/ms$rls.add$polic# %
o/Wect$schema * 0E>ER7-B0+
o/Wect$name * 0E6B:70+
polic#$name * 0644-77$43M:B3K$E6B:70+
&)-
Authorization and Authentication With Client 'dentiAiers
'unction$schema * 0E>E$7-4$6LN5M0+
polic#$'unction * 0A$E3K54;$E6B:70+
polic#$t#pe * LIN7$BK7.7:6:54&!
end!
/
The pol!c 'unc"!ons !n an appl!ca"!on can be as comple/ as needed. Mour o+n +eb s!"es can
!mplemen" pol!c rules !n "he mos" su!"able +a 'or "hem, +h!ch !s l!(el "o be comple"el
d!''eren" "o "ha" used !n "h!s e/ample. Ta(e care +!"h "he PO.:CMNTMP; argumen". Here "he
pol!c 'unc"!on re"urns a s!mple s"r!ng, ma(!ng "he 'unc"!on !den"!cal 'or all uses. Th!s means
"he "pe can be spec!'!ed as D-M4NR.4.4T%T:C allo+!ng "he 'unc"!on "o be cached. The cl!en"
!den"!'!er !s no" cons!dered par" o' "he user de'!ned appl!ca"!on con"e/" so !' "he pol!c
'unc"!on log!c e&alua"es "he !den"!'!er &alue "hen ou +!ll need "o se" "he "pe "o
D-M4NR.4.DM7%M:C.
.og!n "o "he Par"s appl!ca"!on as Chr!s see ho+ "he !n&en"or l!s" no+ onl sho+s elec"r!cal
suppl!es)
0hen logged !n as %l!son ou can con"!nue "o see e&er"h!ng)
&)0
(igure 9&' 7PD auto+atically restricts the report *or -hris"
(igure 92' )he 7PD policy allo,s Alison to see everything"
Connecting to .racle Bsing .C'1
Oracle Da"abase has a number o' &!e+s 'or ,PD managemen". One !s "he ,W,PDNPO.:CM &!e+
"ha" can be used "o '!nd "he pol!c!es "ha" +ere appl!ed "o e/ecu"ed 4B. s"a"emen"s. Th!s can
be use'ul 'or debugg!ng "he &alues re"urned b "he pol!c 'unc"!on.
% 'un "h!ng "o do +!"h ,PD !s "o log!n "o 4B.SPlus as "he o+ner o' "he P%RT4 "able and
chec( !"s con"en"s)
7SK connect phpuser/welcome
7SK select J 'rom parts!
7o ro+s +!ll be re"urned because "he pol!c 'unc"!on 2NPO.:CMNP%RT4 !s appl!ed e&en 'or "he
"able o+ner. 0!"hou" ha&!ng an !den"!'!er &al!dl se", "he cond!"!on can ne&er be sa"!s'!ed. To
remo&e "h!s res"r!c"!on and ma(e adm!n!s"ra"!on o' ob8ec"s eas!er, Oracle has an ;=;MPT
%CC;44 PO.:CM pr!&!lege 'or e/emp"!ng users 'rom ,PD pol!c!es.
,PD !s use'ul 'or more "han personnel access con"rol. The model can be e/"ended "o allo+
@shared hos"!ng@. The !n'ras"ruc"ure 'or one appl!ca"!on can be shared be"+een mul"!ple
d!''eren" groups o' people +ho are ne&er au"hor!1ed "o see da"a 'rom an o"her group.
0hen ou are '!n!shed +!"h "he ,PD e/ample, ou can remo&e "he pol!c b dropp!ng !")
Script 25' vpdo**"sDl
set echo on
connect php$sec$admin/welcome
/egin
d/ms$rls.drop$polic# %
o/Wect$schema * 0E>ER7-B0+
o/Wect$name * 0E6B:70+
polic#$name * 0644-77$43M:B3K$E6B:70&!
end!
/
More !n'orma"!on on ,PD can be 'ound !n "he #sing Oracle 7irtual Private Database to -ontrol
Data Access chap"er o' "he Oracle Database Security Guide &&g :elease 2 N&&"2O manual.
0!ing a Client Identi*ier in PHP *or 5onitoring and Tracing
0h!le man "un!ng pro8ec"s s"ar" +!"h "he au"oma"!c per'ormance d!agnos"!cs run b Oracle
Da"abase, or anal1e o&erall ss"em per'ormance manuall us!ng %0R snapsho"s, "h!s ma
no" be poss!ble !n all en&!ronmen"s. 4ome"!mes on a shared ss"em, mon!"or!ng and anal1!ng
"he beha&!or o' one +eb user !s more prac"!cal and s!mpl!'!es "he process o' d!agnos!ng
per'ormance problems !n PHP. Dur!ng de&elopmen", "he beha&!or o' a proposed appl!ca"!on
pa"ch can be !sola"ed 'rom +ha" else !s happen!ng on "he ss"em. The cl!en" !den"!'!er allo+s
'ocused mon!"or!ng &!a OracleAs ;nd "o ;nd %ppl!ca"!on Trac!ng, a 'ea"ure !n"roduced 'or mul"!?
"!er appl!ca"!ons.
To collec" da"abase s"a"!s"!cs abou" a userAs da"abase resource usage, "he da"abase
adm!n!s"ra"or can e/ecu"e d/ms$monitor.client$id$stat$ena/le%& !n 4B.SPlus)
7SK connect s#stem/s#stempwd
7SK e.ecute d/ms$monitor.client$id$stat$ena/le%client$id * 0chris0&!
&)1
Authorization and Authentication With Client 'dentiAiers
The PHP appl!ca"!on can "hen be run normall 'or an chosen ac"!ons and dura"!on. 4"a"!s"!cs
!" produces can be accessed !n &ar!ous +a, !nclud!ng 'rom "he ,WC.:;7TN4T%T4 &!e+. %'"er
Chr!s loo(s a" "he Par"s appl!ca"!on !n&en"or once, "h!s &!e+ m!gh" con"a!n)
7:6:$M6N- Z6KR-
----------------------------------- ----------
user calls 1
LI time 9D@
LI 4ER 2000
parse count %total& 1
parse time elapsed 91
e.ecute count 1
s"l e.ecute elapsed time D9D
opened cursors cumulatiCe 1
session logical reads U
ph#sical reads 0
ph#sical writes 0
. . .
Th!s par"!cular e/ample sho+s a s!ngle 4B. s"a"emen" +as parsed and e/ecu"ed. 4"andard
Oracle manuals and l!"era"ure descr!bes !n"erpre"!ng all "he &alues, and descr!be "he o"her
s"a"!s"!cs &!e+s.
4"a"!s"!cs can be "urned o'' and rese" "o 1ero +!"h)
e.ecute d/ms$monitor.client$id$stat$disa/le%client$id * 0chris0&!
% da"abase "race "o sho+ "he 4B. @;/pla!n Plan@ ou"pu" 'or anal1!ng e/ecu"ed s"a"emen"s
can also be "urned on 'or each +eb user. :" +!ll sho+ ho+ s"a"emen"s ac"uall go" op"!m!1ed ?
no" 8us" ho+ ou "hough" "he +ould be run. The da"abase adm!n!s"ra"or can enable "rac!ng
+!"h "he D-M4NMO7:TOR.C.:;7TN:DNTR%C;N;7%-.; procedure !n 4B.SPlus)
7SK connect s#stem/s#stempwd
7SK e.ecute d/ms$monitor.client$id$trace$ena/le%client$id * 0chris0+
waits * true+ /inds * true&!
The appl!ca"!on can "hen be run normall. %'"er comple"!on o' "he anals!s per!od, "rac!ng can
be "urned o'' +!"h)
7SK e.ecute d/ms$monitor.client$id$trace$disa/le%client$id * 0chris0&!
To e/am!ne "he crea"ed "race '!les, '!nd "he "race d!rec"or us!ng 4HO0 P%R%M;T;R !n
4B.SPlus)
7SK show parameter user$dump$dest
Th!s g!&es ou"pu" l!(e)
M6N- :;E- Z6KR-
------------------------------------ ----------- ------------------------------
user$dump$dest string /home/oracle/app/diag/rd/ms/or
cl/orcl/trace
The "race d!rec"or "p!call con"a!ns man "race '!les 'rom normal opera"!on. The trcsess
u"!l!" can consol!da"e an o' "hose crea"ed b Chr!sAs use o' "he appl!ca"!on. The
consol!da"!on Cor an !nd!&!dual '!leF can "hen be 'orma""ed +!"h t1pro*. 2or e/ample, s"ar" a
"erm!nal +!ndo+ as "he Oracle so'"+are o+ner and run)
&)2
Connecting to .racle Bsing .C'1
) cd /home/oracle/app/diag/rd/ms/orcl/orcl/trace
) trcsess output*/tmp/all.trc clientid*chris J.trc
) tkpro' /tmp/all.trc /tmp/tkpro'.out e.plain*phpuser/welcome
Th!s loo(s "hrough all "he "race '!les !n "he d!rec"or and aggrega"es "hose crea"ed b Chr!s. :'
ou need "o run trcsess on a subse" o' '!les, such as "he '!les 'or a par"!cular da, search 'or
"he cl!en" !den"!'!er near "he "op o' "he '!les and pass "he rele&an" '!le names "o trcsess.
:nd!&!dual "race '!les con"a!n a sec"!on l!(e)
JJJ 2010-08-1P 15:29:12.D81
JJJ 7-7753M 5L:%1D@.9D@& 2010-08-1P 15:29:12.D81
JJJ 4K5-M: 5L:%chris& 2010-08-1P 15:29:12.D81
JJJ 7-BZ54- M6N-:%orcl& 2010-08-1P 15:29:12.D81
JJJ N3LRK- M6N-:%httpdOlocalhost %:M7 Z1-Z@&& 2010-08-1P 15:29:12.D81
JJJ 64:53M M6N-:%& 2010-08-1P 15:29:12.D81
Oracle Da"abase can also name '!les +!"h a g!&en su''!/, 'or e/ample +yphp, "o ma(e "hem
eas!er "o !den"!'. Do "h!s b e/ecu"!ng "he 4B. command alter session set
trace'ile$identi'ier * 0m#php0 !n PHP a'"er connec"!ng. Da"abase ser&er "race '!le names
+ould "hen loo( l!(e orcl=ora=85&5=+yphp"trc. .og!c +ould need "o be added "o each PHP '!le
"o dec!de "he "race '!le su''!/ "o use, and +ha" cond!"!ons "o se" !".
The ou"pu" 'rom t1pro* !n t1pro*"out con"a!ns anals!s o' "he e/ecu"ed s"a"emen"s. Here !s
a sec"!on o' "he '!le anal1!ng resul"s on a small ss"em)
7SK 5L: a'P9s0'a@cWnp
Elan >ash: @UP9DPU@@0
select J
'rom
parts order /# id
call count cpu elapsed disk "uer# current rows
------- ------ -------- ---------- ---------- ---------- ---------- ----------
Earse 5 0.00 0.1P 0 8 0 0
-.ecute @@ 0.00 0.00 0 0 0 0
Aetch @@ 0.00 0.00 0 2@1 0 198
------- ------ -------- ---------- ---------- ---------- ---------- ----------
total U1 0.01 0.1U 0 2@9 0 198
Nisses in li/rar# cache during parse: 1
3ptimiXer mode: 6KK$B3?7
Earsing user id: 1P02 %E>ER7-B&
Bows Bow 7ource 3peration
------- ---------------------------------------------------
P 73B: 3BL-B I; %cr*U pr*0 pw*0 time*5 us cost*D siXe*222 card*P&
P :6IK- 644-77 ARKK E6B:7 %cr*U pr*0 pw*0 time*5 us cost*@ siXe*222
card*P&
Bows -.ecution Elan
------- ---------------------------------------------------
0 7-K-4: 7:6:-N-M: N3L-: 6KK$B3?7
P 73B: %3BL-B I;&
&*3
Authorization and Authentication With Client 'dentiAiers
P :6IK- 644-77 %ARKK& 3A 0E6B:70 %:6IK-&
-lapsed times include waiting on 'ollowing eCents:
-Cent waited on :imes Na.. ?ait :otal ?aited
---------------------------------------- ?aited ---------- ------------
7SKJMet message to client @@ 0.00 0.00
7SKJMet message 'rom client @2 2219.U8 5U20.55
cursor: mute. 7 1 0.02 0.02
li/rar# cache lock 1 0.01 0.01
cursor: pin 7 wait on , 1 0.01 0.01
Lisk 'ile operations 5/3 D 0.00 0.00
The sec"!on #nderstanding SEF )race and )@P:O( !n "he Oracle Database Per*or+ance
)uning Guide &&g :elease 2 N&&"2O manual descr!bes ho+ "o !n"erpre" "he "race ou"pu".
2or lo&ers o' 3U:s, ;n"erpr!se Manager 11g CDa"abase Con"rolF has a number o' +as "o
chec( "he !mpac" o' "he appl!ca"!on on "he da"abase. 2or e/ample, "o see s"a"!s"!cs 'or a
par"!cular cl!en" !den"!'!er, s"ar" "he ;n"erpr!se Manager console h""p)<<localhos")HH00<em< !n a
bro+ser and na&!ga"e "o Per*or+ance M )op -onsu+ers M )op -lients. 4e" "he 7ie, drop?
do+n "o @Cl!en"s +!"h %ggrega"!on ;nabled@. Cl!c( Add -lient and spec!' "he cl!en" !den"!'!er
Achr!sA. Mou can "hen selec" "he ro+ Achr!sA and cl!c( "he Enable SEF )race bu""on C"h!s !s same
as D-M4NMO7:TOR.C.:;7TN:DNTR%C;N;7%-.;F. %ggrega"!on allo+s each run "o be "o"aled
"oge"her)
O"her areas o' ;n"erpr!se Manager can also '!l"er b cl!en" !den"!'!er, !nclud!ng "he )op Activity
repor".
% s!ngle run o' "he small Par"s appl!ca"!on ma no" ma(e ;n"erpr!se ManagerAs mon!"or!ng
"hresholds or be &!s!ble !n "he aggrega"!on per!ods.
Mou m!gh" ha&e no"!ced "ha" trcsess and ;n"erpr!se Manager also le" da"a be aggrega"ed
b Action and b !odule. These &alues can be se" !n PHP OC:$ +!"h "he 'unc"!ons
oci$set$action%& and oci$set$module$name%& respec"!&el "o !den"!' +h!ch par"s o' a PHP
&*&
(igure 96' Enterprise !anager )op -lients
Connecting to .racle Bsing .C'1
appl!ca"!on are be!ng e/ecu"ed. The sec"!on !onitoring O-./ SEF State+ents !n "he chap"er
Executing SEF State+ents ,ith O-./ co&ers "hem. Mon!"or!ng and "rac!ng can sho+ up "he
appl!ca"!on?+!de ho" spo"s, and "he 4B. s"a"emen"s be!ng e/ecu"ed can eas!l be !den"!'!ed.
;n"erpr!se Manager !s use'ul 'or "rac!ng per'ormance bo""lenec(s and "rac(!ng causes o'
da"abase slo+do+ns dur!ng de&elopmen". :" allo+s l!&e anals!s !n a large ss"em +!"hou"
!mpac"!ng o"her concurren" +eb users. 2or more !n'orma"!on on "rac!ng see #sing Application
)racing )ools !n "he Oracle Database Per*or+ance )uning Guide &&g :elease 2 N&&"2O"
Client Identi*ier Su11ar6
Cl!en" !den"!'!ers should be used b PHP +eb appl!ca"!ons "ha" allo+ mul"!ple appl!ca"!on users
"o connec" "o "he da"abase &!a a s!ngle da"abase user name. The !den"!'!er !s a de&eloper
chosen &alue "ha" can be der!&ed 'rom sess!on !n'orma"!on abou" "he end user "ha" !s alread
presen" !n mos" +eb appl!ca"!ons. Cl!en" !den"!'!ers are se" b s!mpl call!ng "he
oci$set$client$identi'ier%& 'unc"!on !n PHP scr!p"s connec"!ng "o "he da"abase. Oracle
Da"abase uses !den"!'!ers "o aud!", au"oma"!call res"r!c" access "o sens!"!&e da"a, and allo+
'ocused mon!"or!ng and "rac!ng o' resource usage. Oracle PHP appl!ca"!ons should use cl!en"
!den"!'!ers so "hese Oracle Da"abase 'ea"ures can be u"!l!1ed a" an po!n" !n "he l!'e"!me o' "he
appl!ca"!on.
Oracle Net;or= Ser-ice! and PHP
Oracle 7e" !s "he da"abase componen" handl!ng commun!ca"!on be"+een "he da"abase and !"s
cl!en"s. :" allo+s soph!s"!ca"ed con"rol o&er ne"+or( connec"!on managemen" 'or connec"!&!",
per'ormance and has 'ea"ures such as encrp"!on o' ne"+or( "ra''!c. Th!s sec"!on g!&es an
o&er&!e+ o' some Oracle 7e" 'ea"ures o' !n"eres" "o PHP appl!ca"!ons. Tun!ng "he O4, hard+are
and TCP<:P s"ac( +!ll also subs"an"!all help !mpro&e per'ormance and scalab!l!".
4ome o' "he Oracle 7e" se""!ngs are con'!gured !n a '!le called sDlnet"ora "ha" ou can
crea"e. 2or PHP, !" should be pu" !n "he same d!rec"or as "he tnsna+es"ora '!le !' ou use one.
O"her+!se, se" "he T74N%DM:7 en&!ronmen" &ar!able "o "he d!rec"or con"a!n!ng sDlnet"ora.
The da"abase ser&er can also ha&e a sDlnet"ora '!le, +h!ch should be !n
JO:A-FE=HO!E;net,or1;ad+in. Th!s d!rec"or on "he da"abase ser&er also con"a!ns
listener"ora, a '!le au"oma"!call crea"ed dur!ng da"abase !ns"alla"!on, +h!ch con'!gures "he
Oracle 7e"+or( l!s"ener process.
Connection :ate 'i1iting
.arge s!"es "ha" ha&e abnormal sp!(es !n "he number o' users connec"!ng can pre&en"
da"abase hos" CPU o&erload b l!m!"!ng "he ra"e "ha" connec"!ons can be es"abl!shed. The
da"abase listener"ora '!le can spec!' a R%T;N.:M:T clause "o se" "he ma/!mum number o'
re>ues"s per second "ha" +!ll be ser&!ced)
K57:-M-B*%6LLB-77$K57:*
%6LLB-77*%EB3:343K*tcp&%>37:*sales&%E3B:*1521&%B6:-$K5N5:*D&&
The &alue +!ll depend on "he hard+are !n use.
&*(
.racle Net/ork #er$ices and !H!
Setting Connection Ti1eout!
2rom Oracle 10.2.0.I on+ards, ou can spec!' a connec"!on "!meou" !n case "here !s a
ne"+or( problem dur!ng connec"!on. Th!s le"s PHP connec"!ons re"urn an Oracle error "o "he
user 'as"er, !ns"ead o' appear!ng "o DhangE. 4e" 4B.7;T.OUT-OU7DNCO77;CTNT:M;OUT !n
"he cl!en" s!de C"he PHP?s!deF sDlnet"ora '!le. Th!s se"s "he upper "!me l!m!" 'or es"abl!sh!ng a
connec"!on r!gh" "hrough "o "he da"abase, !nclud!ng "he "!me 'or a""emp"s "o connec" "o o"her
da"abase ser&!ces.
:n Oracle 11g, a sl!gh"l l!gh"er?+e!gh" solu"!on TCP.CO77;CTNT:M;OUT +as !n"roduced. :"
!s also a sDlnet"ora parame"er. :" bounds 8us" "he TCP connec"!on es"abl!shmen" "!me, +h!ch !s
mos"l +here connec"!on problems occur.
Con*iguring ,uthentication 5ethod!
There are man +as "o con'!gure connec"!on and au"hen"!ca"!on. 2or e/ample a connec"!on)
)c * oci$connect%"hr"+ "welcome"+ "a/c"&!
could be e&alua"ed b Oracle 10g as us!ng "he ;as Connec" sn"a/ "o hos" mach!ne abc
Cus!ng "he de'aul" por" and da"abase ser&!ceF or us!ng a ne" al!as abc con'!gured !n a
tnsna+es"ora '!le.
The 'le/!b!l!" can cause a dela !n ge""!ng an error bac( !' "he connec"!on de"a!ls are
!n&al!d or a da"abase !s no" opera"!onal. -o"h !n"ernal connec"!on me"hods ma be "r!ed !n
se>uence add!ng "o "he "!me dela be'ore a PHP scr!p" ge"s "he error. Th!s depends on our
Oracle 7e" and D74 se""!ngs.
Ho+ Oracle !s con'!gured "o au"hen"!ca"e "he userKs creden"!als Chere a username and
pass+ordF can also ha&e an e''ec".
The !ssue !s no" spec!'!c "o PHP. :n 4B.SPlus "he connec"!on)
) s"lplus hr/welcomeOa/c
+ould be "he same.
:n a bas!c Oracle 10g or 11g !ns"alla"!on, one +a "o re"urn an error as soon as poss!ble !s
"o se" "h!s !n our OC:$ sDlnet"ora '!le)
M6N-7.L5B-4:3B;$E6:> * %:M7M6N-7&
7SKM-:.6R:>-M:546:53M$7-BZ54-7 * %M3M-&
Th!s D:R;CTORMNP%TH &alue d!sables ;as Connec"Ks hostname:port/serCice sn"a/. :ns"ead
o' us!ng ;as Connec" sn"a/, a connec" name and tnsna+es"ora '!le +ould be needed. CTh!s
ma also add a small measure o' secur!" !' our scr!p"s acc!den"all allo+ arb!"rar
connec"!on !den"!'!ers. :" s"ops users guess!ng da"abase ser&er hos"names "he should no"
(no+ abou".F
4e""!ng %UTH;7T:C%T:O7N4;R,:C;4 "o 7O7; s"ops d!''eren" au"hen"!ca"!on me"hods be!ng
"r!ed. %l"hough "h!s ma pre&en" pr!&!leged da"abase connec"!ons, +h!ch re>u!re opera"!ng
ss"em au"hor!1a"!on, "h!s, aga!n, m!gh" be bene'!c!al. Chec( "he Oracle 7e" documen"a"!on
'or de"a!ls and 'or o"her au"hen"!ca"!on me"hods and au"hen"!ca"!on?"pe spec!'!c "!meou"
parame"ers.
&*)
Connecting to .racle Bsing .C'1
#etecting #ead PHP ,pache Se!!ion!
:' a PHP %pache process hangs, !"s da"abase ser&er process +!ll no" be closed. Th!s +!ll no"
pre&en" o"her PHP processes 'rom con"!nu!ng "o +or(, unless a re>u!red loc( +as no"
released.
The TCP (eepal!&e 'ea"ure +!ll au"oma"!call de"ec" unusable connec"!ons based on "he
opera"!ng ss"em "!meou" se""!ng, +h!ch !s "p!call some hours. Th!s de"ec"!on !s enabled on
"he da"abase ser&er b de'aul".
Oracle 7e" !"sel' can also be con'!gured "o de"ec" dead connec"!ons, +h!ch !s use'ul !' a
much smaller "!meou" compared +!"h "he de'aul" TCP (eepal!&e !s des!red. Th!s !s con'!gured
b 4B.7;T.;=P:R;NT:M; !n "he da"abase JO:A-FE=HO!E;net,or1;ad+in;sDlnet"ora. %
s"ar"!ng recommenda"!on !s "o se" !" "o 10 m!nu"es. :' a dead or "erm!na"ed connec"!on !s
!den"!'!ed, "he ser&er process e/!"s.
-o"h se""!ngs +!ll use some resources. %&o!d se""!ng "hem "oo shor", +h!ch ma !n"errup"
normal user ac"!&!".
#etecting #ead #ata$a!e Ser-er!
:' "he ne"+or( drops ou" Y or a R%C node goes do+n, "he connec"!on "o "he da"abase ser&er
'rom a PHP process !s l!(el "o be los". Mou can "ell PHP "o de"ec" and reco&er 'rom "hese
dropou"s b enabl!ng (eepal!&e !n "he PHP s!de tnsna+es"ora us!ng "he %-M6IK-*IB3G-M&
clause under "he D;4CR:PT:O7 parame"er !n a connec" s"r!ng. The opera"!ng ss"em se""!ngs
+!ll be used "o de"erm!ne "he "!meou" per!od.
Other Oracle Net Opti1i8ation!
Oracle 7e" le"s ou "une a lo" o' o"her op"!ons "oo. Chec( "he Oracle 2et Services
Ad+inistratorHs Guide and "he Oracle 2et Services :e*erence 'or de"a!ls and more 'ea"ures. %
'e+ more "!ps are men"!oned belo+.
The bes" sess!on da"a un!" C4DUF s!1e +!ll depend on "he appl!ca"!on. %n $6 s!1e C"he ne+
de'aul" !n Oracle 11gF !s su!"able 'or man appl!ca"!ons. :' .O-s are used, a b!gger &alue m!gh"
be be""er. :" should be se" "he same &alue !n bo"h "he da"abase ser&er sDlnet"ora and "he OC:$
tnsna+es"ora '!le.
2or s!"es "ha" ha&e a large number o' connec"!ons be!ng made, "une "he BU;U;4:9; op"!on
!n "he listener"ora '!le.
6eep!ng "he P%TH en&!ronmen" &ar!able shor" 'or "he oracle user on "he da"abase mach!ne
can reduce "!me 'or 'or(!ng a da"abase ser&er process. Th!s !s o' mos" bene'!" 'or s"andard
PHP connec"!ons. Reduc!ng "he number o' en&!ronmen" &ar!ables also helps.
Tracing Oracle Net
4ome"!mes our ne"+or( !s "he bo""lenec(. :' ou suspec" "h!s !s "he case, "urn on Oracle 7e"
"rac!ng !n our OC:$ sDlnet"ora '!le and see +here "!me !s be!ng spen". The e/ample
JO:A-FE=HO!E;net,or1;ad+in;sa+ple;sDlnet"ora has some no"es on "he parame"ers "ha"
help. 2or e/ample, +!"h a U4;R le&el "race !n "he PHP?s!de sDlnet"ora)
trace$leCel$client * R7-B
trace$director#$client * /tmp
%nd "he PHP code)
&**
.racle Net/ork #er$ices and !H!
)c * oci$connect%0hr0+ 0welcome0+ 0Qc0&! // inCalid d/ name
The "race '!le, 'or e/ample ;t+p;cli=6262"trc, sho+s)
...
91U-TRM-2012 09:5D:58:100< nn'tml'$make$s#stem$addr'ile: s#stem names 'ile is ...
91U-TRM-2012 09:55:00:85D< snlinYet6ddr5n'o: Mame resolution 'ailed 'or Qc
...
The le'" hand column !s "he "!mes"amp o' each lo+ le&el call. Here, !" sho+s a rela"!&el b!g
"!me dela do!ng name resolu"!on 'or "he non?e/!s"en" hos" Qc. The cause !s "he con'!gura"!on
o' "he mach!ne ne"+or( name resolu"!on.
The logg!ng !n'ras"ruc"ure o' Oracle 11g changed s!gn!'!can"l. .oo( 'or "race '!les !n a sub?
d!rec"or o' "he Oracle d!agnos"!c d!rec"or, 'or e/ample !n
JHO!E;oradiag=c0ones;diag;clients;user=c0ones 'or command l!ne PHP. 2or Oracle 7e" log '!les
crea"ed b a +eb ser&er runn!ng PHP, loo( !n ;root;oradiag=root !' no o"her pa"h +as
con'!gured. Mou can also se" "he en&!ronmen" &ar!able AD:=IASE "o !nd!ca"e +here "rac!ng
and logg!ng '!les should be s"ored.
&*+
Connecting to .racle Bsing .C'1
&*-
CH,PTE: 11
E4EC0TING S&' ST,TE5ENTS WITH
OCI.
Th!s chap"er d!scusses us!ng 4B. s"a"emen"s +!"h "he PHP OC:$ e/"ens!on. :" co&ers
s"a"emen" e/ecu"!on, "he OC:$ 'unc"!ons a&a!lable, handl!ng "ransac"!ons, "un!ng >uer!es, and
some use'ul "!ps and "r!c(s.
S&' State1ent Eecution Step!
Buer!es us!ng "he OC:$ e/"ens!on 'ollo+ a model 'am!l!ar !n "he Oracle +orld) parse, e/ecu"e
and 'e"ch. 4"a"emen"s l!(e 4B-6:- and 5M7-B: re>u!re onl pars!ng and e/ecu"!ng.
The poss!ble s"eps are)
1. !arse) Prepares a s"a"emen" 'or e/ecu"!on. Pars!ng !s reall 8us" a l!gh"?+e!gh" local
prepara"or s"ep, s!nce OracleKs ac"ual "e/" parse occurs !n "he da"abase a" "he e/ecu"!on
s"age.
2. >indE %n op"!onal s"ep "ha" le"s ou b!nd da"a &alues, 'or e/ample, !n "he ?>-B- clause,
'or be""er per'ormance and secur!". -!nd!ng local &alues !n"o a s"a"emen" !s s!m!lar "o "he
+a ou use a Fs pr!n" 'orma" spec!'!ca"!on !n a s"r!ng.
I. DeAine) %n op"!onal s"ep allo+!ng ou "o spec!' +h!ch PHP &ar!ables +!ll hold >uer
resul"s. Th!s !s no" commonl used because mos" scr!p"s use "he OC:$ *etch 'unc"!ons "o
re"urn resul"s.
J. 4%ecuteE The da"abase processes "he s"a"emen" and bu''ers an resul"s.
H. 8etch) 3e"s an >uer resul"s bac( 'rom "he da"abase.
There !s no one?s"op 'unc"!on "o do all "hese s"eps !n a s!ngle PHP call bu" !" !s "r!&!al "o crea"e
one !n our appl!ca"!on and ou can "hen add cus"om error handl!ng re>u!remen"s.
To sa'eguard 'rom run?a+a scr!p"s, b de'aul" PHP +!ll "erm!na"e !' a scr!p" "a(es longer
"han I0 seconds. Th!s !s se" +!"h "he php"ini parame"er +ax=execution=ti+e or "he
set$time$limit%& 'unc"!on. The &alue !s "he CPU "!me used b PHP, so long runn!ng 4B.
s"a"emen"s !n "he da"abase ma no" ge" !n"errup"ed. Mou +!ll need "o enable resource
managemen" !n "he da"abase "o o&ercome "h!s.
4!m!larl, !' ou are man!pula"!ng large amoun"s o' da"a, ou ma need "o !ncrease "he
php"ini parame"er +e+ory=li+it, +h!ch caps "he amoun" o' memor each PHP process can
consume.
&uer6 Ea1ple
% bas!c >uer !n OC:$ !s)
Script 24' Duery"php
<?php
&*0
4%ecuting #;L #tatements With .C'1
)c * oci$pconnect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "select cit#+ postal$code 'rom locations"&!
oci$e.ecute%)s&!
print 0<ta/le /order*"1"0!
while %)row * oci$'etch$arra#%)s+ 345$MRNH345$B-:RBM$MRKK7&& (
print "<tr"!
'oreach %)row as )item&
print "<td".htmlentities%)item&."</td"!
print "</tr"!
=
print "</ta/le"!
?
The ou"pu" 'rom "he scr!p" Duery"php !s)
The htmlentities%& 'unc"!on pre&en"s an user da"a such as AZA 'rom be!ng !n"erpre"ed as an
HTM. "ag. :n man cases ou +!ll +an" "o use "h!s 'unc"!onAs op"!onal ;7TNBUOT;4 parame"er.
Mou should also use "he op"!onal charac"er se" parame"er, spec!'!ng a &alue "ha" ma"ches "he
charac"er se" o' our documen".
&uoting S&' State1ent Tet
:n PHP, s!ngle and double >uo"es can bo"h be used 'or s"r!ngs. 4"r!ngs +!"h embedded >uo"es
can be made b escap!ng "he nes"ed >uo"es +!"h a bac(slash, or b us!ng bo"h >uo"!ng
charac"ers. The ne/" e/ample sho+s s!ngle >uo"es around "he c!" name. To ma(e "he >uer a
&al!d PHP s"r!ng !", "here'ore, mus" be enclosed !n double >uo"es)
)" * "select J 'rom locations where cit# * 07#dne#0"!
)s * oci$parse%)c+ )"&!
:' ou ha&e a >uer sn"a/ error, echo ou" "he s"r!ng and &er!' "he >uo"!ng !s &al!d 'or Oracle)
&*1
(igure 95' Output *ro+
Duery"php"
#;L #tatement 4%ecution #teps
echo )"!
PHP H.I !n"roduced a 7O0DOC sn"a/ "ha" !s use'ul 'or embedd!ng >uo"es and dollar s!gns !n
s"r!ngs, such as "h!s e/ample "ha" >uer!es one o' OracleAs adm!n!s"ra"!on &!e+s ,W4B.)
)s"l * <<<0-ML0
select parse$calls+ e.ecutions
'rom C)s"l
-ML!
)s * oci$parse%)c+ )s"l&!
. . .
7o"e "he -ML "o(en mus" appear !n "he '!rs" column o' "he scr!p", +!"hou" an !nden"a"!on.
&reeing Statements
:n long scr!p"s !" !s recommended "o close s"a"emen"s +hen "he are comple"e)
oci$'ree$statement%)s&!
Th!s allo+s resources "o be reused e''!c!en"l. 2or bre&!", and because "he e/amples e/ecu"e
>u!c(l or "he s"a"emen" resource !s closed au"oma"!call a" "he end o' 'unc"!on scope, mos"
code sn!ppe"s !n "h!s boo( do no" 'ollo+ "h!s prac"!ce.
Oracle #ata T6pe!
;ach column has a da"a "pe, +h!ch !s assoc!a"ed +!"h a spec!'!c s"orage 'orma". The common
bu!l"?!n Oracle da"a "pes are)
CH%R
,%RCH%R2
7UM-;R
D%T;
T:M;4T%MP
:7T;R,%.
-.O-
C.O-
-2:.;
=M.Tpe
The CH%R, ,%RCH%R2, 7UM-;R, D%T;, T:M;4T%MP and :7T;R,%. da"a "pes are s"ored
d!rec"l !n PHP &ar!ables. -.O-, C.O-, and -2:.; da"a "pes use PHP descr!p"ors and are
sho+n !n "he #sing Farge Ob0ects in O-./ chap"er. =M.Tpes are re"urned as s"r!ngs or .O-s,
as d!scussed !n "he #sing <!F ,ith Oracle and PHP chap"er. OracleAs 7CH%R, 7,%RCH%R2,
and 7C.O- "pes are no" suppor"ed !n "he OC:$ e/"ens!on.
&*2
4%ecuting #;L #tatements With .C'1
9etch 9unction!
There are a number o' OC:$ 'e"ch 'unc"!ons, all documen"ed !n "he PHP Oracle O-./ !anual a"
http://php.net/manual/en//ook.oci8.php. Table O l!s"s "he 'unc"!ons.
)able 9' O-./ *etch *unctions"
OCI. 9unction Purpo!e
oci$'etch$all%& 3e"s all "he resul"s a" once.
oci$'etch$arra#%& 3e"s "he ne/" ro+ as an arra !nde/ed b an !n"eger or as an
assoc!a"!&e arra, depend!ng on our cho!ce.
oci$'etch$assoc%& 3e"s "he ne/" ro+ as an assoc!a"!&e arra.
oci$'etch$o/Wect%& 3e"s "he ne/" ro+ as an ob8ec".
oci$'etch$row%& 3e"s "he ne/" ro+ as an !n"eger !nde/ed arra.
oci$'etch%& Used +!"h oci$result%&, +h!ch re"urns "he resul" o' a g!&en
'!eld. %lso used +!"h oci$de'ine$/#$name%& +h!ch prese"s +h!ch
&ar!able "he da"a +!ll be re"urned !n"o.
4ome o' "he 'unc"!ons ha&e op"!onal parame"ers. Re'er "o "he PHP manual 'or more
!n'orma"!on.
The 'unc"!on commonl used !s oci$'etch$arra#%&)
)rowarra# * oci$'etch$arra#%)statement+ )mode&!
The mode !s op"!onal. Table P l!s"s "he a&a!lable modes.
)able ?' oci=*etch=arrayNO options"
Para1eter Purpo!e
345$67734 Re"urn resul"s as an assoc!a"!&e arra.
345$MRN Re"urn resul"s as a numer!call !nde/ed arra.
345$I3:> Re"urn resul"s as bo"h assoc!a"!&e and numer!c arras. Th!s !s
"he de'aul".
345$B-:RBM$MRKK7 Re"urn PHP 7U.. &alue 'or 7U.. da"a.
345$B-:RBM$K3I7 Re"urn "he ac"ual .O- da"a !ns"ead o' an OC:?.O- resource.
Modes can be used "oge"her b add!ng or b!nar?orA!ng "hem "oge"her)
)rowarra# * oci$'etch$arra#%)s+ 345$MRN # 345$B-:RBM$MRKK7&!
The oci$'etch$assoc%& and oci$'etch$row%& 'unc"!ons are spec!al cases o'
oci$'etch$arra#%&.
9etching to a Nu1eric ,rra6
% bas!c e/ample "o 'e"ch resul"s !n"o a numer!call !nde/ed PHP arra !s)
&+3
8etch 8unctions
)s * oci$parse%)c+ "select cit#+ postal$code 'rom locations"&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$MRN&& (
echo )row9$< . " - " . )row91< . "</r2n"!
=
The "+o columns are !nde/ 0 and !nde/ 1 !n "he resul" arra. Th!s d!splas)
Boma - 00989
Zenice - 109@D
:ok#o - 1P89
>iroshima - P82@
7outhlake V 2P192
. . .
4ome o' "he 'e"ch 'unc"!ons do no" re"urn 7U.. da"a b de'aul". Th!s can be "r!c( +hen us!ng
numer!call !nde/ed arras. The resul" arra can appear "o ha&e 'e+er columns "han selec"ed,
and ou canK" al+as "ell +h!ch column +as 7U... ;!"her use assoc!a"!&e arras so "he column
names are d!rec"l assoc!a"ed +!"h "he!r &alues, or spec!' "he 345$B-:RBM$MRKK7 'lag)
)row * oci$'etch$arra#%)s+ 345$MRN H 345$B-:RBM$MRKK7&!
9etching to an ,!!ociati-e ,rra6
%ssoc!a"!&e arra (es are "he column names !n "he case sho+n +hen descr!b!ng "he "able !n
4B.SPlus)
7SK descri/e locations
Mame Mull? :#pe
----------------------------------------- -------- ----------------------------
K346:53M$5L M3: MRKK MRNI-B%D&
7:B--:$6LLB-77 Z6B4>6B2%D0&
%&S'()_C&*E Z6B4>6B2%12&
45:; M3: MRKK Z6B4>6B2%@0&
7:6:-$EB3Z5M4- Z6B4>6B2%25&
43RM:B;$5L 4>6B%2&
% scr!p" "o access "he pos" code column +ould be)
)s * oci$parse%)c+ "select postal$code 'rom locations"&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$67734&& (
echo )row9"%&S'()_C&*E"< . "</r2n"!
=
Th!s d!splas)
00989
109@D
1P89
P82@
2P192
. . .
&+&
4%ecuting #;L #tatements With .C'1
9etching Ca!e Sen!iti-e Colu1n Na1e! to an ,!!ociati-e ,rra6
:' "he "able column names +ere crea"ed case sens!"!&el b us!ng >uo"es a" "able crea"!on,
"hen "he PHP arra !nd!ces need "o ma"ch "he case)
7SK create ta/le cs$ta/ %"N#4ol" num/er&!
7SK descri/e cs$ta/
Mame Mull? :#pe
----------------------------------------- -------- ----------------------------
+,Co" MRNI-B
Th!s should be 'e"ched !n PHP as)
while %)row * oci$'etch$arra#%)s+ 345$67734&& (
echo )row90+,Co"0< . "</r2n"!
=
#uplicate Colu1n Na1e! and ,!!ociati-e ,rra6!
:n an assoc!a"!&e arra !nde/ "here !s no "able pre'!/ 'or "he column name. :' ou ha&e "o 8o!n
"ables +here "he same column name occurs +!"h d!''eren" mean!ngs !n bo"h "ables, use a
column al!as !n "he >uer. O"her+!se onl one o' "he s!m!larl named columns +!ll be re"urned
b PHP.
Th!s con"r!&ed e/ample selec"s "+o columns called CO.OR)
)s * oci$parse%)c+ "select cat$name+
cats.color as cat_co"or+
dog$name+
dogs.color
'rom cats+ dogs"&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$67734&& (
echo )row9"46:$M6N-"< . " " . )row9"46:$43K3B"< . " - " .
)row9"L3Y$M6N-"< . " " . )row9"43K3B"< . " " .
"</r2n"!
=
The assoc!a"!&e arra has CO.OR and C%TNCO.OR !nd!ces 'or "he "+o d!''eren" CO.OR
columns.
% s"ra!gh"'or+ard al"erna"!&e !s "o use 345$MRN "o re"urn numer!c arra !nde/es.
9etching to an O$3ect
2e"ch!ng as ob8ec"s allo+s proper"?s"le access "o be used.
)s * oci$parse%)c+ 0select J 'rom locations0&!
oci$e.ecute%)s&!
while %)row * oci$'etch$o/Wect%)s&& (
Car$dump%)row&!
=
Th!s sho+s each ro+ !s an ob8ec" and g!&es !"s proper"!es. The Car$dump%& 'unc"!on pr!n"s and
au"oma"!call 'orma"s "he &ar!able )row. The ou"pu" !s)
&+(
8etch 8unctions
o/Wect%std4lass&Q1 %P& (
9"K346:53M$5L"<*
string%D& "1000"
9"7:B--:$6LLB-77"<*
string%20& "129U Zia 4ola di Bie"
9"E37:6K$43L-"<*
string%5& "00989"
9"45:;"<*
string%D& "Boma"
9"7:6:-$EB3Z5M4-"<*
MRKK
9"43RM:B;$5L"<*
string%2& "5:"
=
. . .
:' "he loop !s changed "o)
while %)row * oci$'etch$o/Wect%)s&& (
echo "6ddress is " . )row-7:B--:$6LLB-77 . "</r2n"!
=
"he ou"pu" !s)
6ddress is 129U Zia 4ola di Bie
6ddress is 9@091 4alle della :esta
6ddress is 201U 7hinWuku-ku
6ddress is 9D50 Gami#a-cho
6ddress is 201D Ta//erwock# Bd
. . .
#e*ining Output <aria$le!
;/pl!c!"l se""!ng ou"pu" &ar!ables can be done +!"h oci$de'ine$/#$name%&. Th!s e/ample
'e"ches c!" names)
)s * oci$parse%)c+ 0select cit# 'rom locations0&!
oci$de'ine$/#$name%)s+ 045:;0+ )cit#&! // column name is uppercase
oci$e.ecute%)s&!
while %oci$'etch%)s&& (
echo "4it# is " . )cit# . "</r2n"!
=
The de'!ne !s done be'ore e/ecu"!on so Oracle (no+s +here "o s"ore "he ou"pu". The column
name !n "he oci$de'ine$/#$name%& call mus" be !n uppercase unless "he "able +as crea"ed
+!"h case sens!"!&e column names. The resul" !s)
4it# is Boma
4it# is Zenice
4it# is :ok#o
4it# is >iroshima
4it# is 7outhlake
. . .
&+)
4%ecuting #;L #tatements With .C'1
The oci$de'ine$/#$name%& 'unc"!on has an op"!onal "pe parame"er "ha" !s use'ul, 'or
e/ample, "o spec!' "ha" "he PHP &ar!able should be a .O-.
9etching Ne!ted Cur!or!
The ne/" e/ample sho+s a >uer "ha" 'e"ches "+o da"a &alues. The '!rs" !s "he
D;P%RTM;7TN7%M; and "he second !s a nes"ed cursor 'or "he sub?>uer o' people +!"h!n "ha"
depar"men". Th!s second &alue !s g!&en "he column al!as 7C)
Script 29' nestedcur&"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s"l *
0select department$name+
cursor%select 'irst$name
'rom emplo#ees
where emplo#ees.department$id * departments.department$id& as nc
'rom departments
where department$id in %10+ 20+ @0&0!
)s * oci$parse%)c+ )s"l&!
)r * oci$e.ecute%)s&!
while %%)row1 * oci$'etch$arra#%)s+ 345$67734&& 8* 'alse& (
echo "Lepartment: " . )row190L-E6B:N-M:$M6N-0< . "</r2n"!
)nc * )row190M40<! // treat as a statement resource
oci$e.ecute%)nc&!
while %%)row2 * oci$'etch$arra#%)nc+ 345$67734H345$B-:RBM$MRKK7&& 8* 'alse& (
echo )row290A5B7:$M6N-0< . "</r2n"!
=
oci$'ree$statement%)nc&!
echo "</r2n"!
=
?
The &alue !n )nc !s "rea"ed l!(e a parsed >uer. %'"er e/ecu"!ng )nc an o' "he 'e"ch 'unc"!ons
can be used. The ou"pu" !s)
Lepartment: 6dministration
Tenni'er
Lepartment: Narketing
Nichael
Eat
Lepartment: Eurchasing
Len
6le.ander
7helli
7igal
Yu#
&+*
8etch 8unctions
Garen
9etching and Wor=ing With Nu1$er!
.umber &ormatting and String Conersion
0hen 'e"ch!ng numbers, a con&ers!on "o s"r!ng represen"a"!on !s done b Oracle. Th!s means
Oracle 'orma"s "he da"a accord!ng "o !"s global!1a"!on se""!ngs. :n some reg!ons "he dec!mal
separa"or 'or numbers m!gh" be a comma, caus!ng problems !' our PHP scr!p" la"er cas"s "he
s"r!ng "o a PHP number 'or an ar!"hme"!c opera"!on. OracleKs de'aul" 'orma" can be changed
eas!l and !" !s recommended "o e/pl!c!"l se" "he number con&ers!on 'orma"
7.4N7UM;R:CNCH%R%CT;R4 "o 0.+0 !' "he de'aul" &alue !nher!"ed 'rom our "err!"or se""!ngs
!s d!''eren". 4ee Setting the Oracle 2u+ber (or+at ,ith 2FS=2#!E:.-=-HA:A-)E:S !n "he
chap"er Globaliation.
.umber )ccurac-
PHP and Oracle d!''er !n "he!r ar!"hme"!c handl!ng and prec!s!on so a cho!ce mus" be made
+here "o do calcula"!ons.
:' our appl!ca"!on depends on numer!c accurac +!"h '!nanc!al da"a, do ar!"hme"!c !n
Oracle 4B. or P.<4B., or cons!der us!ng PHPKs bc+ath e/"ens!on.
Th!s e/ample sho+s ho+ b de'aul" PHP 'e"ches numbers as s"r!ngs, and "he d!''erence
be"+een do!ng ar!"hme"!c !n PHP and "he da"abase. 4B. s"a"emen"s "o crea"e "he number
da"a are)
create ta/le dt %cn1 num/er+ cn2 num/er&!
insert into dt %cn1+ cn2& Calues %U1+ U0.P&!
commit!
PHP code "o 'e"ch "he ro+ !s)
)s * oci$parse%)c+ "select cn1+ cn2+ cn1 - cn2 as di'' 'rom dt"&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
Car$dump%)row&!
The Car$dump%& 'unc"!on sho+s "he PHP da"a "pe 'or numer!c columns !s string)
arra#%@& (
9"4M1"<*
string%2& "U1"
9"4M2"<*
string%D& "U0.P"
9"L5AA"<*
string%2& ".D"
=
%r!"hme"!c calcula"!ons are handled +!"h d!''eren" prec!s!on !n PHP. The pre&!ous e/ample
sho+ed "he resul" o' "he sub"rac"!on +as "he e/pec"ed &alue. :' "he code !s changed "o do "he
sub"rac"!on !n PHP)
)row * oci$'etch$arra#%)s+ 345$67734&!
&++
4%ecuting #;L #tatements With .C'1
)di'' * )row904M10< - )row904M20<!
echo "E>E di''erence is " . )di'' . "2n"!
The ou"pu" sho+s)
E>E di''erence is 0.D0000000000001
PHP has a php"ini parame"er precision +h!ch de"erm!nes ho+ man s!gn!'!can" d!g!"s are
d!splaed !n 'loa"!ng po!n" numbers. - de'aul" !" !s se" "o 1J.
9etching and Wor=ing With #ate!
Oracle has capable da"e handl!ng 'unc"!onal!", suppor"!ng &ar!ous needs. Da"es and "!mes
+!"h user spec!'!ed prec!s!ons can be s"ored. OracleAs da"e ar!"hme"!c ma(es calendar +or(
eas.
D%T;, D%T;T:M; and :7T;R,%. "pes are 'e"ched 'rom Oracle as s"r!ngs, s!m!lar "o "he +a
PHP re"urns OracleAs numer!c "pes.
The D%T; "pe has resolu"!on "o "he second bu" "he de'aul" 'orma" !s o'"en 8us" "he da,
mon"h and ear. Th!s e/ample >uer!es a da"e column)
)s * oci$parse%)c+ "select hire$date 'rom emplo#ees where emplo#ee$id * 200"&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo ">ire date is " . )row90>5B-$L6:-0<. "2n"!
:' "he de'aul" 'orma" !s "he Oracle %mer!can s"andard o' DD?MO7?MM "hen "he ou"pu" !s)
>ire date is 1U-7-E-8U
Da"es !nser"ed are e/pec"ed "o be !n "he de'aul" Oracle 'orma" "oo)
)s * oci$parse%)c+ "insert into m#dt/ %dcol& Calues %00D-6RY-0U0&"&!
oci$e.ecute%)s&!
The de'aul" 'orma" can be changed +!"h OracleAs global!1a"!on se""!ng 7.4ND%T;N2ORM%T
be'ore or a'"er PHP s"ar"s. 4ee "he chap"er Globaliation"
Regardless o' "he de'aul", an s"a"emen" can use !"s o+n cus"om 'orma". 0hen >uer!ng,
use "he :3$4>6B%& 'unc"!on. 0hen !nser"!ng, use :3$L6:-%&)
// insert a date
)s * oci$parse%)c+
"insert into m#dt/ %dcol&
Calues %to$date%0200P/01/01 05:@P:500+ 0;;;;/NN/LL >>:N5:770&&"&!
oci$e.ecute%)s&!
// 'etch a date
)s * oci$parse%)c+ "select to$char%dcol+ 0LL/NN/;;0& as dcol 'rom m#dt/"&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo "Late is " . )row9"L43K"< . "2n"!
The ou"pu" !s)
Late is 01/01/0P
&+-
8etch 8unctions
To '!nd "he curren" da"abase ser&er "!me, use 4M4D%T;. Here "he da"e and "!me re"urned b
4M4D%T; are d!splaed)
)s * oci$parse%)c+
"select to$char %s#sdate+ 0;;;;-NN-LL >>2D:N5:770& as now 'rom dual"&!
)r * oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo ":ime is " . )row9"M3?"< . "2n"!
The ou"pu" !s)
:ime is 200U-08-01 15:28:DD
OracleAs T:M;4T%MP "pe s"ores &alues prec!se "o 'rac"!onal seconds. Mou can op"!onall s"ore
a "!me 1one or local "!me 1one. 2or PHP, "he local "!me 1one +ould be "he "!me 1one o' "he
+eb ser&er, +h!ch ma no" be rele&an" "o users loca"ed remo"el.
2or an e/ample, 4M4T:M;4T%MP, +h!ch !s analogous "o 4M4D%T;, g!&es "he curren" ser&er
"!me s"amp and "!me 1one)
)s * oci$parse%)c+ "select s#stimestamp 'rom dual"&!
)r * oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo ":ime is " . )row9"7;7:5N-7:6NE"< . "2n"!
The ou"pu" !s)
:ime is 01-6RY-0U 0@.28.DD.2@@88U EN -0U:00
%n :7T;R,%. "pe represen"s "he d!''erence be"+een "+o da"e &alues. :n"er&als are use'ul 'or
OracleAs anal"!c 'unc"!ons. :n PHP "he are 'e"ched as s"r!ngs, l!(e D%T; and T:M;4T%MP are
'e"ched.
In!ert? 0pdate? #elete? Create and #rop in PHP OCI.
;/ecu"!ng Da"a De'!n!"!on .anguage CDD.F and Da"a Man!pula"!on .anguage CDM.F
s"a"emen"s, l!(e 4B-6:- and 5M7-B:, s!mpl re>u!res a parse and e/ecu"e)
)s * oci$parse%)c+ "create ta/le i1test %col1 num/er&"&!
oci$e.ecute%)s&!
The onl?run?once !ns"alla"!on sec"!ons o' appl!ca"!ons should con"a!n almos" all "he 4B-6:-
:6IK- s"a"emen"s used. %ppl!ca"!ons !n Oracle do no" commonl need "o crea"e "emporar
"ables a" run "!me, and !" !s e/pens!&e "o do so. Use !nl!ne &!e+s, or 8o!n "ables +hen re>u!red.
:n some cases Dglobal te+porary tablesE m!gh" be use'ul.
Tran!action! in PHP OCI.
Us!ng "ransac"!ons "o pro"ec" "he !n"egr!" o' da"a !s as !mpor"an" !n PHP as an o"her
rela"!onal da"abase appl!ca"!on. ;/cep" !n spec!al cases, ou +an" e!"her all our changes "o
be comm!""ed, or none o' "hem.
Unnecessar!l comm!""!ng or roll!ng bac( !mpac"s da"abase per'ormance as !" causes
unnecessar ne"+or( "ra''!c Cround tripsF be"+een PHP and "he da"abase.
&+0
4%ecuting #;L #tatements With .C'1
:" !s also causes e/"ra process!ng and more :O "o "he da"abase '!les. To ma/!m!1e e''!c!enc,
use "ransac"!ons +here appropr!a"e.
OC:$Ks de'aul" comm!" beha&!or !s l!(e o"her PHP e/"ens!ons bu" d!''eren" 'rom Oracle
Da"abaseKs s"andard. The de'aul" mode o' oci$e.ecute%& !s OC:NCOMM:TNO7N4UCC;44 "o
comm!" changes. Th!s can eas!l be o&err!dden !n OC:$. -u" "a(e care +!"h comm!""!ng and
roll!ng bac(. H!dden "ransac"!onal cons!s"enc problems can be crea"ed b no" unders"and!ng
+hen comm!"s or rollbac(s occur. 4uch problems ma no" be apparen" !n normal cond!"!ons,
bu" an abnormal e&en" m!gh" cause onl par" o' a "ransac"!on "o be comm!""ed. Problems can
also be caused b programmers "r!ng "o s>uee1e ou" absolu"el op"!mal per'ormance b
comm!""!ng or roll!ng bac( onl +hen absolu"el necessar.
4cr!p"s "ha" call a connec"!on 'unc"!on more "han once +!"h "he same creden"!als should
ma(e sure "ransac"!ons are comple"e be'ore re?connec"!ng. 4!m!larl, be care'ul a" "he end o'
scope !' "he "ransac"!on s"a"e !s uncomm!""ed.
:n "he 'ollo+!ng e/ample a ne+ record !s comm!""ed +hen "he oci$e.ecute%& call !s called)
)s * oci$parse%)c+ "insert into testta/le Calues %0m# data0&"&!
oci$e.ecute%)s&! // automaticall# committed /# de'ault
O"her users o' "he "able +!ll !mmed!a"el be able "o see "he ne+ record. %u"o?comm!""!ng can
be hand 'or a s!ngle 5M7-B: or REL6:-, bu" "ransac"!onal and per'ormance re>u!remen"s
should be "hough" abou" be'ore us!ng "he de'aul" mode e&er+here.
Mou spec!' "o beg!n a "ransac"!on +!"hou" au"o?comm!""!ng b)
)s * oci$parse%)c+ "insert into testtest Calues %0m# data 20&"&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&! // not committed
Pr!or "o OC:$ 1.J Cpr!or "o PHP H.IF, use OC:ND;2%U.T !ns"ead o' "he ne+ more ob&!ousl
named al!as OC:N7ON%UTONCOMM:T.
To comm!" an un?comm!""ed "ransac"!ons 'or our connec"!on, do)
oci$commit%)c&!
To rollbac(, do)
oci$roll/ack%)c&!
&+1
(igure 94' Each round trip bet,een PHP and the database reduces scalability"
Transactions in !H! .C'1
%n ou"s"and!ng "ransac"!on !s au"oma"!call rolled bac( +hen a connec"!on !s closed or a" "he
end o' "he scr!p". :' ou need a "ransac"!on "ha" spans mul"!ple HTTP re>ues"s, use D-M4N=%
+h!ch !s d!scussed !n "he chap"er #sing PF;SEF ,ith O-./"
7o"e) -e care'ul m!/!ng and ma"ch!ng oci$e.ecute%& calls +!"h bo"h comm!" modes !n one
scr!p", s!nce ou ma comm!" a" !ncorrec" "!mes. :n par"!cular, no"e e/ecu"!ng a >uer +!ll
comm!" an ou"s"and!ng "ransac"!on !' OC:N7ON%UTONCOMM:T !s not used !n "he >uerAs
oci$e.ecute%& call.
%n 4B-6:- or LB3E s"a"emen" +!ll au"oma"!call comm!" regardless o' "he oci$e.ecute%&
mode. Th!s !s a 'ea"ure o' Oracle Da"abase "ha" canno" be al"ered.
:' all our da"abase calls !n a scr!p" are >uer!es, or are calls "o P.<4B. pac(ages "ha" handle
"ransac"!ons !n"ernall, use)
oci$e.ecute%)s&!
:' ou pass OC:N7ON%UTONCOMM:T, PHP +!ll send an e/pl!c!" rollbac( "o "he da"abase a" "he
end o' e&er scr!p", e&en "hough !" !s unnecessar 'or our appl!ca"!on.
,utono1ou! Tran!action!
OracleKs P.<4B. procedural language Cco&ered !n de"a!l !n "he ne/" chap"erF allo+s ou "o do
au"onomous "ransac"!ons, +h!ch are e''ec"!&el sub?"ransac"!ons. %n au"onomous "ransac"!on
can be comm!""ed or rolled bac( +!"hou" a''ec"!ng "he ma!n "ransac"!on. Th!s m!gh" be use'ul
'or logg!ng da"a access ? an aud!" record can be !nser"ed e&en !' "he user dec!des "o rollbac(
"he!r ma!n change. %n e/ample !s)
Script 2?' logger"sDl
drop ta/le m#ta/le!
drop ta/le logta/le!
create ta/le m#ta/le %c1 Carchar2%10&&!
create ta/le logta/le %eCent Carchar2%@0&&!
create or replace procedure updatelog%p$eCent in Carchar2& as
pragma autonomous$transaction!
/egin
insert into logta/le %eCent& Calues%p$eCent&!
commit!
end!
/
Mou could call "he P.<4B. 'unc"!on 'rom PHP "o log e&en"s)
Script 2/' logger"php
<?php
&+2
4%ecuting #;L #tatements With .C'1
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "insert into m#ta/le Calues %0a/c0&"&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&! // don0t commit
)s * oci$parse%)c+ "/egin updatelog%05M7-B: attempted0&! end!"&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&! // don0t commit
oci$roll/ack%)c&!
?
;&en "hough OC:N7ON%UTONCOMM:T !s used, "he au"onomous "ransac"!on comm!"s "o "he log
"able. Th!s comm!" does no" also comm!" "he PHP scr!p" !nser" !n"o MMT%-.;. %'"er runn!ng
logger"php, "he "ables con"a!n)
7SK select J 'rom m#ta/le!
no rows selected
7SK select J 'rom logta/le!
-Z-M:
------------------------------
5M7-B: attempted
The Tran!actional )eha-ior o* 5ultiple Connection!
To see "he "ransac"!onal beha&!or o' "he "hree connec"!on 'unc"!ons, use 4B.SPlus "o crea"e a
"able +!"h a s!ngle da"e column)
7SK create ta/le m#ta/le %col date&!
Crea"e and run transactions"php a 'e+ "!mes, chang!ng oci$connect%& "o oci$new$connect%&
and oci$pconnect%&)
Script 28' transactions"php
<?php
'unction do$"uer#%)c&
(
)s * oci$parse%)c+ 0select col 'rom m#ta/le0&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
)row * oci$'etch$arra#%)s&!
echo "<pLate is: " . )row9043K0< . "</p2n"!
=
)c1 * oci$connect%"hr"+ "welcome"+ "localhost/,-"&! // 'irst E>E connection
)s * oci$parse%)c1+ "insert into m#ta/le Calues %0" . date%0W:N:#0& . "0&"&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
do$"uer#%)c1&!
)c2 * oci$connect%"hr"+ "welcome"+ "localhost/,-"&! // second E>E connection
&-3
Transactions in !H! .C'1
do$"uer#%)c2&!
?
The scr!p" !nser"s Cbu" does no" comm!"F us!ng one connec"!on and >uer!es bac( "he resul"s
+!"h bo"h "he or!g!nal and a second connec"!on.
Us!ng an oci$connect%& connec"!on le"s ou >uer "he ne+l !nser"ed Cbu" uncomm!""edF
da"a bo"h "!mes because )c1 and )c2 re'er "o "he same Oracle connec"!on. Us!ng
oci$pconnect%& !s "he same as oci$connect%&. The ou"pu" !n bo"h cases !s)
Late is: 1P-TRM-12
Late is: 1P-TRM-12
Us!ng oci$new$connect%& 'or )c2 g!&es a ne+ connec"!on +h!ch canno" see "he uncomm!""ed
da"a. The ou"pu" sho+s "he second >uer does no" 'e"ch an ro+s)
Late is: 1P-TRM-12
Late is:
PHP Error Handling
The .nstalling and -on*iguring PHP chap"er recommended se""!ng display=errors "o On !n
php"ini "o a!d debugg!ng. Mou can also se""!ng "he error=reporting parame"er "o ;N%.. "o ca"ch
all po"en"!al problems dur!ng de&elopmen". :n a produc"!on ss"em ou should ma(e sure
error ou"pu" !s logged !ns"ead o' d!splaed. Mou do no" +an" "o lea( !n"ernal !n'orma"!on "o
+eb users, and ou do no" +an" appl!ca"!on pages con"a!n!ng ugl error messages.
The ;N4TR:CT le&el +as no" par" o' "he ;N%.. le&el pr!or "o PHP H.J. Mou mus" e/pl!c!"l
DorE "he "+o &alues "oge"her.
;rror handl!ng can also be con"rolled a" run"!me. 2or e/ample, "o see all errors d!splaed,
scr!p"s can se")
error$reporting%-$6KK&! // 5n E>E 5.@ use -$6KK[-$7:B54:
ini$set%0displa#$errors0+ 03n0&!
Depend!ng on "he php"ini &alue o' display=errors, ou m!gh" cons!der us!ng PHPKs O pre'!/ "o
comple"el suppress au"oma"!c d!spla o' 'unc"!on errors, al"hough "h!s !mpac"s per'ormance)
)c * Ooci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
To "rap ou"pu" and reco&er 'rom errors, PHPKs ou"pu" bu''er!ng 'unc"!ons ma be use'ul. :' an
error occurs par" +a dur!ng crea"!on o' "he HTM. page, "he par"!all comple"e page con"en"s
can be d!scarded and a n!cel 'orma""ed error page can be crea"ed !ns"ead.
Handling PHP OCI. Error!
The error hand!ng o' an sol!d appl!ca"!on re>u!res care'ul des!gn. ;/pec" "he une/pec"ed.
Chec( all re"urn codes. Oracle ma p!gg?bac( calls "o "he da"abase "o op"!m!1e per'ormance.
Th!s means "ha" errors ma occur dur!ng la"er OC:$ calls "han ou m!gh" e/pec".
To 'e"ch OC:$ errors, use "he oci$error%& 'unc"!on. The 'unc"!on re>u!res a d!''eren"
argumen" depend!ng on "he call!ng con"e/", as sho+n la"er. :" re"urns an arra)
&-&
4%ecuting #;L #tatements With .C'1
)able /' Error array a*ter Je C oci=errorNO"
<aria$le #e!cription
)e9"code"< Oracle error number.
)e9"message"< Oracle error message.
)e9"o''set"< Column pos!"!on !n "he 4B. s"a"emen" o' "he error. 0!ll be 0 !'
no 4B. s"a"emen" +as !n&ol&ed.
)e9"s"lte.t"< The "e/" o' "he 4B. s"a"emen". 0!ll be emp" !' no 4B.
s"a"emen" +as !n&ol&ed.
2or !n'orma"!on on ge""!ng e/"ra !n'orma"!on 'or errors dur!ng crea"!on o' P.<4B. procedures,
see "he chap"er #sing PF;SEF ,ith O-./"
OCI, Connection Errors
To ge" connec"!on error messages, no argumen" "o oci$error%& !s needed)
error$reporting%-$6KK&!
ini$set%0displa#$errors0+ 03''0&! // Lon0t automaticall# show errors
)c * oci$connect%0hr0+ 0not_we"co-e0+ 0localhost/,-0&!
i' %8)c& (
)e * oci_error()! // Mo parameter passed
ini$set%0displa#$errors0+ 03n0&! // 6llow trigger$error%& to displa#
trigger$error%04ould not connect: 0. )e90message0<+ -$R7-B$-BB3B&!
=
0!"h "he !n&al!d pass+ord, "he ou"pu" !n a bro+ser !s)
Aatal error: 4ould not connect: 3B6-0101U: inCalid username/password!
logon denied
OCI, #ersistent Connection Errors
%n !n"ernal re!mplemen"a"!on o' connec"!on managemen" !n OC:$ 1.I made !" much be""er a"
au"oma"!call reco&er!ng 'rom da"abase una&a!lab!l!" errors. Ho+e&er +!"h pers!s"en"
connec"!ons, PHP can s"!ll re"urn a cached connec"!on +!"hou" (no+!ng !' "he da"abase a" "he
o"her end o' "he ne"+or( !s !n 'ac" s"!ll a&a!lable. :' "he da"abase has res"ar"ed s!nce "he "!me
o' '!rs" connec"!on, or !' "he D-% had enabled resource managemen" "ha" l!m!"ed "he
ma/!mum connec"!on "!me 'or a user, or e&en !' "he D-% !ssued an 6K:-B 7;7:-N G5KK
7-7753M command "o close "he userAs da"abase sess!on, "hen an alread cached OC:$
connec"!on re"urned b a 'u"ure oci$pconnect%& call +!ll be unusable. The oci$pconnect%&
call +!ll no" re"urn an error !n "h!s case. Tp!call "he error +!ll be re"urned b "he '!rs"
oci$e.ecute%& call "ha" "r!es "o use "he connec"!on resource. Ho+e&er OC:$ +!ll "hen mar( "he
connec"!on as !n&al!d and "he subse>uen" "!me PHP calls oci$pconnect%& a brand ne+
connec"!on "o "he da"abase +!ll be success'ull crea"ed and +!ll be usable !n "he PHP scr!p".
CThe sec"!on on oci/"ping=interval !n "he chap"er -onnecting to Oracle #sing O-./ has 'ur"her
d!scuss!on on "h!s caseF.
&-(
!H! 4rror Handling
2or e/ample, cons!der "he scr!p" oci/"php a" "he s"ar" o' "he chap"er -onnecting to Oracle
#sing O-./. %'"er "he scr!p" !s success'ull run !n a +eb bro+ser, !' "he D-% !ssues an 6K:-B
L6:6I67- G5KK 7-7753M command 'or "he da"abase connec"!on !" crea"ed, "hen "he ne/" "!me
"he scr!p" !s run !n a bro+ser !" +!ll d!spla "he error a'"er "he oci$e.ecute%& call)
4ould not e.ecute statement: 3B6-00028: #our session has /een killed
The oci$pconnect%& call doesnA" genera"e an error !"sel' Y !" 8us" re"urns a cached connec"!on.
:' "he scr!p" !s run a "h!rd "!me b "he same %pache process !" +!ll s!len"l reconnec" and run "o
comple"!on normall. Th!s assumes "here !s no p!ng due "o oci/"ping=interval"
The bo""om l!ne !s "ha" all OC:$ calls should be chec(ed 'or errors because arch!"ec"ural
and !n"ernal op"!m!1a"!ons ma de'er error no"!'!ca"!on.
OCI, #arse Errors
To ge" parse error messages, pass oci$error%& "he connec"!on resource)
error$reporting%-$6KK&!
ini$set%0displa#$errors0+ 03''0&! // Lon0t automaticall# show errors
)s * oci$parse%)c+ "select . cit# 'rom locations"&! // Mote stra# "uote
i' %8)s& (
)e * oci_error($c)! // 4onnection resource passed
ini$set%0displa#$errors0+ 03n0&! // 6llow trigger$error%& to displa#
trigger$error%04ould not parse: 0. )e90message0<+ -$R7-B$-BB3B&!
=
7o"e "he one e/"ra s!ngle?>uo"e !n "he m!ddle o' "he >uer s"r!ng. The resul" !s "he error
message)
E>E Aatal error: 4ould not parse: 3B6-01U5P: "uoted string not properl#
terminated
OCI, Execution and &etching Errors
%n e/ample o' an e/ecu"!on error !s +hen "he "able be!ng >uer!ed does no" e/!s". 2or
e/ecu"!on errors, pass "he s"a"emen" resource "o oci$error%&)
error$reporting%-$6KK&!
ini$set%0displa#$errors0+ 03''0&! // Lon0t automaticall# show errors
)s * oci$parse%)c+ "select cit# 'rom not_"ocations"&!
)r * oci$e.ecute%)s&!
i' %8)r& (
)e * oci_error($s)! // 7tatement resource passed
ini$set%0displa#$errors0+ 03n0&! // 6llow trigger$error%& to displa#
trigger$error%04ould not e.ecute: 0. )e90message0<+ -$R7-B$-BB3B&!
=
The parse comple"es success'ull bu" +hen "he s"a"emen" !s sen" "o "he da"abase 'or
e/ecu"!on, "he "able +!ll no" be 'ound. The ou"pu" !s)
Aatal error: 4ould not e.ecute: 3B6-009D2: ta/le or Ciew does not e.ist
&-)
4%ecuting #;L #tatements With .C'1
:' ou call Car$dump%)e&, ou +!ll see "he arra con"a!ns "he "e/" o' "he s"a"emen" and "he
column o''se" pos!"!on o' "he error !n "ha" s"a"emen". Column 1P o' "he >uer !s "he "able
name 7OTN.OC%T:O74)
arra#%D& (
9"code"<*
int%9D2&
9"message"<*
string%@9& "3B6-009D2: ta/le or Ciew does not e.ist"
9"o''set"<*
int%1U&
9"s"lte.t"<*
string%@0& "select cit# 'rom not$locations"
=
% 'e"ch error m!gh" occur !' "he ne"+or( "o "he da"abase d!sconnec"s une/pec"edl. 2or 'e"ch
errors, pass "he s"a"emen" resource)
)r * oci$'etch$all%)s+ )results&!
i' %8r& (
)e * oci_error($s)! // 7tatement resource passed
ini$set%0displa#$errors0+ 03n0&! // 6llow trigger$error%& to displa#
trigger$error%04ould not 'etch: 0. )e90message0<+ -$R7-B$-BB3B&!
=
0!ing )ind <aria$le! in Prepared State1ent!
-!nd &ar!ables are 8us" l!(e Fs pr!n" 'orma" spec!'!ers. The le" ou re?e/ecu"e a s"a"emen" +!"h
d!''eren" &alues 'or "he &ar!ables and ge" d!''eren" resul"s. :n "he PHP commun!" s"a"emen"s
l!(e "h!s are (no+n as prepared s"a"emen"s.
:' ou do no" b!nd, Oracle mus" reparse and cache mul"!ple s"a"emen"s. ;ach s"a"emen"
re>u!res crea"!on o' a cursor !n "he Oracle 43%, causes l!brar la"ch con"en"!on, and causes
shared pool con"en"!on. The o&erall resul" !s scalab!l!" !ssues. %n appl!ca"!on "ha" runs '!ne !n
small de&elopmen" and "es"!ng en&!ronmen"s ma no" be able "o handle "he !n"ended number
o' real users.
&-*
Bsing >ind @aria5les in !repared #tatements
-!nd!ng !s highly recommended. :" can !mpro&e o&erall da"abase "hroughpu". Oracle !s more
l!(el "o '!nd "he s"a"emen" !n !"s cache and be able "o reuse "he e/ecu"!on plan and con"e/"
'or "ha" s"a"emen", e&en !' someone else or!g!nall e/ecu"ed !".
-!nd &ar!ables are also an !mpor"an" +a "o pre&en" 4B. !n8ec"!on secur!" a""ac(s. 4B.
!n8ec"!on ma occur +hen 4B. s"a"emen"s are cons"ruc"ed 'rom hard?coded "e/" conca"ena"ed
+!"h user !npu")
)w * "userid * 1"! // emulate "user input"
)s * oci$parse%)c+ "select J 'rom m#ta/le where )w"&!
:' "he user !npu" !s no" care'ull chec(ed, "hen !" ma be poss!ble 'or a mal!c!ous user "o
e/ecu"e a 4B. s"a"emen" o' "he!r cho!ce !ns"ead o' "he one ou !n"ended.
:n Oracle, a b!nd &ar!able !s a colon?pre'!/ed name !n "he 4B. "e/". %n oci$/ind$/#$name%&
call "ells Oracle +h!ch PHP &ar!able "o ac"uall use +hen e/ecu"!ng "he s"a"emen".
&-+
(igure 9?' Iinding i+proves per*or+ance and security"
(igure 99' 2ot binding ,astes database resources"
4%ecuting #;L #tatements With .C'1
Script 6A' bindvar"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "select last$name 'rom emplo#ees where emplo#ee$id * :eid/C"&!
)m#eid * 101!
oci$/ind$/#$name%)s+ ":eid/C"+ )m#eid&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo "Kast name is: ". )row90K67:$M6N-0< ."</r2n"!
?
The ou"pu" !s "he las" name o' emploee 101)
Kast name is: Gochhar
There !s no need "o Cand 'or e''!c!enc ou should no"F re?parse "he 4B. s"a"emen" !' ou 8us"
+an" "o change "he &alue o' "he b!nd &ar!able. The 'ollo+!ng code +ould +or( +hen appended
"o "he end o' bindvar"php)
// Mo need to re-parse or re-/ind
)m#eid * 102!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo "Kast name is: ". )row90K67:$M6N-0< ."</r2n"!
Re?runn!ng bindvar"php no+ g!&es)
Kast name is: Gochhar
Kast name is: Le >aan
Mou can b!nd a s!ngle &alue +!"h each oci$/ind$/#$name%& call. Mul"!ple &alues can be bound
+!"h ano"her 'unc"!on, oci$/ind$arra#$/#$name%&, and passed "o P.<4B. bloc(s. Th!s !s
d!scussed !n "he chap"er on P.<4B..
Do no" "o change "he PHP "pe o' )m#eid a'"er b!nd!ng or be"+een e/ecu"!ons o"her+!se "he
!n"ernal represen"a"!on +onA" be recogn!1ed b OC:$.
The sn"a/ o' oci$/ind$/#$name%& !s)
)rc * oci$/ind$/#$name%)statement+ )/indCarname+ )phpCaria/le+ )length+ )t#pe&
The leng"h and "pe are no"!onall op"!onal. The de'aul" "pe !s "he s"r!ng "pe, 4B.TNCHR.
Oracle +!ll con&er" mos" bas!c "pes "o or 'rom "h!s as needed. 2or e/ample +hen b!nd!ng a
number ou can om!" "he "pe parame"er.
Mou +!ll need "o se" a leng"h +hen da"a !s be!ng re"urned 'rom Oracle as an OUT b!nd. Th!s
!s so PHP can alloca"e a bu''er o' "he correc" s!1e. :" !s also recommended "o pass "he leng"h !'
a >uer !s be!ng re?e/ecu"ed !n a scr!p" +!"h d!''eren" :7 b!nd &alues. 2or e/ample +hen
b!nd!ng, pass "he leng"h o' "he larges" po"en"!al s"r!ng. Pass!ng "he leng"h also a&o!ds
&--
Bsing >ind @aria5les in !repared #tatements
po"en"!al edge?case beha&!or d!''erences !' a scr!p" runs +!"h mul"!ple d!''eren" Oracle
charac"er se"s, or +!"h d!''eren" arch!"ec"ures.
4ome &er old PHP e/amples use an ampersand A^A +!"h oci$/ind$/#$name%& parame"ers.
Do no" do "h!s. 4!nce a general clean up o' "he o&erall call?b?re'erence !mplemen"a"!on !n
PHP, "h!s sn"a/ has been depreca"ed and ma cause problems.
% b!nd call "ells Oracle +h!ch memor address "o read da"a 'rom. Tha" address needs "o
con"a!n &al!d da"a +hen oci$e.ecute%& !s called. :' "he b!nd call !s made !n a d!''eren" scope
'rom "he e/ecu"e call "here could be a problem. 2or e/ample, !' "he b!nd !s !n a 'unc"!on and a
'unc"!on?local PHP &ar!able !s bound, "hen Oracle ma read an !n&al!d memor loca"!on !' "he
e/ecu"e occurs a'"er "he 'unc"!on has re"urned. Th!s has an unpred!c"able ou"come.
There !s one case +here ou m!gh" dec!de no" "o use b!nd &ar!ables. 0hen >uer!es con"a!n
b!nd &ar!ables, "he op"!m!1er does no" ha&e an !n'orma"!on abou" "he &alue ou ma
e&en"uall use +hen "he s"a"emen" !s e/ecu"ed. :' our da"a !s h!ghl s(e+ed, ou m!gh" +an"
"o hard code &alues. -u" !' "he da"a !s der!&ed 'rom user !npu" be sure "o san!"!1e !" "o a&o!d
4B. !n8ec"!on secur!" !ssues.
2!nall, Oracle does no" use >ues"!on mar( A?A 'or b!nd &ar!able placeholders a" all. OC:$
suppor"s onl named placeholders +!"h a colon pre'!/. 4ome PHP da"abase abs"rac"!on laers
+!ll s!mula"e suppor" 'or >ues"!on mar(s b scann!ng our s"a"emen"s and replac!ng "hem
+!"h suppor"ed sn"a/.
)inding in a D*orE 'oop
There !s a common problem +!"h b!nd!ng !n a 'oreach loop +!"h PHP OC:$)
)s * oci$parse%)c+ 0select J
'rom departments
where department$name * :dname and location$id * :loc0&!
)/a * arra#%0:dname0 * 05: 7upport0+ 0:loc0 * 1U00&!
'oreach %)/a as )ke# * )Cal& (
oci$/ind$/#$name%)s+ )ke#+ )Cal&! // pro/lem here
=
The problem here !s "ha" )Cal !s local "o "he loop Cand !s reusedF. The 4B. s"a"emen" +!ll no"
e/ecu"e as e/pec"ed. Chang!ng "he b!nd call !n "he loop "o use )/a9)ke#< sol&es "he problem)
Script 6&' bindloop"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ 0select J
'rom departments
where department$name * :dname and location$id * :loc0&!
)/a * arra#%0:dname0 * 05: 7upport0+ 0:loc0 * 1U00&!
'oreach %)/a as )ke# * )Cal& (
oci$/ind$/#$name%)s+ )ke#+ $ba/$0e,1&!
=
oci$e.ecute%)s&!
&-0
4%ecuting #;L #tatements With .C'1
while %%)row * oci$'etch$arra#%)s+ 345$67734&&& (
'oreach %)row as )item& (
echo htmlentities%)item& . " "!
=
echo "</r2n"!
=
?
)inding With 'IFE and :EGE4PA'IFE Clau!e!
Mou can b!nd "he &alue used !n a pa""ern?ma"ch!ng 4B. K5G- or B-Y-,E$K5G- clause)
Script 62' bindli1e"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+
"select cit#+ state$proCince 'rom locations where cit# like :/C"&!
)cit# * 07outhF0!
oci$/ind$/#$name%)s+ ":/C"+ )cit#&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
?
Th!s uses OracleAs "rad!"!onal .:6; sn"a/, +here AFA means ma"ch an"h!ng. %n underscore !n
"he pa""ern s"r!ng A$A +ould ma"ch e/ac"l one charac"er.
The ou"pu" 'rom bindli1e"php !s c!"!es and s"a"es +here "he c!" s"ar"s +!"h A4ou"hA)
arra#%2& (
9"45:;"<*
arra#%@& (
90<*
string%15& "7outh Irunswick"
91<*
string%19& "7outh 7an Arancisco"
92<*
string%9& "7outhlake"
=
9"7:6:-$EB3Z5M4-"<*
arra#%@& (
90<*
string%10& "Mew Terse#"
91<*
string%10& "4ali'ornia"
92<*
string%5& ":e.as"
=
&-1
Bsing >ind @aria5les in !repared #tatements
=
Oracle also suppor"s regular e/press!on ma"ch!ng +!"h 'unc"!ons l!(e B-Y-,E$K5G-,
B-Y-,E$5M7:B, B-Y-,E$7RI7:B, and B-Y-,E$B-EK64-.
:n a >uer 'rom PHP ou m!gh" b!nd "o B-Y-,E$K5G- us!ng)
Script 66' bindregexp"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "select cit# 'rom locations where rege.p$like%cit#+ :/C&"&!
)cit# * 0.Jing.J0!
oci$/ind$/#$name%)s+ ":/C"+ )cit#&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
?
Th!s d!splas all "he c!"!es "ha" con"a!n "he le""ers A!ngA)
arra#%1& (
9"45:;"<*
arra#%2& (
90<*
string%U& "IeiWing"
91<*
string%9& "7ingapore"
=
=
)inding 5ultiple <alue! in an IN Clau!e
User da"a 'or a b!nd &ar!able !s al+as "rea"ed as pure da"a and ne&er as par" o' "he 4B.
s"a"emen". -ecause o' "h!s, "r!ng "o use a comma separa"ed l!s" o' !"ems !n a s!ngle b!nd
&ar!able +!ll be recogn!1ed b Oracle onl as a s!ngle &alue, no" as mul"!ple &alues. The
common use case !s +hen allo+!ng a +eb user "o choose mul"!ple op"!ons 'rom a l!s" and
+an"!ng "o do a >uer on all &alues.
Hard cod!ng mul"!ple &alues !n an 5M clause !n "he 4B. s"a"emen" !s "he an"!?e/ample "ha"
should be a&o!ded)
)s * oci$parse%)c+
"select last$name 'rom emplo#ees where emplo#ee$id in %101+102&"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
'oreach %)res90K67:$M6N-0< as )name& (
echo "Kast name is: ". )name ."</r2n"!
=
&-2
4%ecuting #;L #tatements With .C'1
Th!s d!splas bo"h surnames bu" !" leads "o "he scal!ng and secur!" !ssues "ha" b!nd &ar!ables
o&ercome.
The ne/" code sn!ppe" sho+s "he na[&e e>u!&alen" us!ng a s!ngle b!nd &ar!able)
)s * oci$parse%)c+
"select last$name 'rom emplo#ees where emplo#ee$id in %:eid/C&"&!
)m#eids * "101+102"!
oci$/ind$/#$name%)s+ ":-5LIZ"+ )m#eids&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
The code g!&es "he error O:A3A&?22' invalid nu+ber because "he )m#eids s"r!ng !s "rea"ed as
a s!ngle &alue and !s no" recogn!1ed as a l!s" o' numbers.
The solu"!on 'or a '!/ed, small number o' &alues !n an :7 b!nd clause !s "o use !nd!&!dual
b!nd &ar!ables. % MRKK can be bound 'or an un(no+n &alues)
Script 65' bindinlist"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+
"select last$name 'rom emplo#ees where emplo#ee$id in %:e1+ :e2+ :e@&"&!
)m#e1 * 10@!
)m#e2 * 10D!
)m#e@ * MRKK! // pretend we were not giCen this Calue
oci$/ind$/#$name%)s+ ":-1"+ )m#e1&!
oci$/ind$/#$name%)s+ ":-2"+ )m#e2&!
oci$/ind$/#$name%)s+ ":-@"+ )m#e@&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
'oreach %)res90K67:$M6N-0< as )name& (
echo "Kast name is: ". )name ."</r2n"!
=
?
The ou"pu" !s)
Kast name is: -rnst
Kast name is: >unold
:' "he number o' &alues "o be compared !s b!g, ou could dnam!call bu!ld up "he 4B.
s"a"emen", al"hough "r "o a&o!d do!ng "h!s +here "oo man d!s"!nc" 4B. s"a"emen"s are
crea"ed and e/ecu"ed)
Script 64' dyna+icinlist"php
<?php
)args * arra#%100+105+111&! // simulate a Caria/le num/er o' arguments
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
&03
Bsing >ind @aria5les in !repared #tatements
// 4reate uni"uel# named /ind Caria/les in the 5M list
)s"l * 0select last$name 'rom emplo#ees where emplo#ee$id in %0!
)ac * count%)args&!
'or %)i * 0! )i < )ac! HH)i& (
)s"l .* ":".)i."+"!
=
)s"l * rtrim%)s"l+ "+"&!
)s"l .* 0&0!
// Iind each Caria/le
)s * oci$parse%)c+ )s"l&!
'or %)i * 0! )i < )ac! HH)i& (
oci$/ind$/#$name%)s+ )i+ )args9)i<&!
=
oci$e.ecute%)s&!
while %%)row * oci$'etch$arra#%)s+ 345$67734&& 8* 'alse& (
'oreach %)row as )item&
echo )item . "2n"!
=
?
2or &er large numbers o' :7 b!nd &alues, b!nd!ng ma no" be poss!ble and al"erna"!&e
solu"!ons such as !nser"!ng "he &alues !n"o a global "emporar "ables and us!ng a 8o!n m!gh" be
re>u!red. Tom 6"e d!scusses "he general problem and g!&es solu"!ons 'or o"her cases !n "he
March Y %pr!l 200P Oracle !againe.
0!ing )ind <aria$le! to 9etch #ata
%s +ell as +ha" are called :7 b!nds, +h!ch pass da"a !n"o Oracle, "here are also OUT b!nds "ha"
re"urn &alues. These are mos"l used "o re"urn &alues 'rom P.<4B. procedures and 'unc"!ons.
C4ee "he chap"er on us!ng P.<4B.F. :' "he PHP &ar!able assoc!a"ed +!"h an OUT b!nd does no"
e/!s", ou need "o spec!' "he op"!onal leng"h parame"er. %no"her case +hen "he leng"h
should be spec!'!ed !s +hen re"urn!ng numbers. - de'aul" !n OC:$, numbers are con&er"ed "o
and 'rom s"r!ngs +hen "he are bound. Th!s means "he leng"h parame"er should also be
passed "o oci$/ind$/#$name%& +hen re"urn!ng a number, o"her+!se d!g!"s ma be "runca"ed)
oci$/ind$/#$name%)s+ ":NI"+ )m/+ 10&!
There !s also an op"!onal '!'"h parame"er, +h!ch !s "he da"a "pe. Th!s mos"l used 'or b!nd!ng
.O-s and resul" se"s as sho+n !n "he chap"er on .O-s. One m!cro?op"!m!1a"!on +hen numbers
are (no+n "o be !n"egral, !s "o spec!' "he da"a "pe as 4B.TN:7T. Th!s a&o!ds "he "pe
con&ers!on cos")
oci$/ind$/#$name%)s+ ":NI"+ )m/+ -1+ 7SK:$5M:&!
:n "h!s e/ample, "he leng"h +as se" "o Y1 mean!ng use "he na"!&e da"a s!1e o' an !n"eger.
&0&
4%ecuting #;L #tatements With .C'1
)inding in an O:#E: )G Clau!e
4ome appl!ca"!ons allo+ "he user "o choose "he presen"a"!on order o' resul"s. Tp!call "he
number o' &ar!a"!ons 'or an 3BL-B I; clause are small and so ha&!ng d!''eren" s"a"emen"s
e/ecu"ed 'or each cond!"!on !s e''!c!en")
switch %)C& (
case 1:
)o/ * 0 order /# 'irst$name0!
/reak!
de'ault:
)o/ * 0 order /# last$name0!
/reak!
=
)s * oci$parse%)c+ 0select 'irst$name+ last$name 'rom emplo#ees0 . )o/&!
-u" !' our "un!ng !nd!ca"es "ha" b!nd!ng !n a 3BL-B I; clause !s necessar, and "he columns
are o' "he same "pe, ou m!gh" be able "o use a 4B. 467- s"a"emen". Ho+e&er "h!s m!gh"
nega"!&el !mpac" 4B. s"a"emen" op"!m!1a"!on)
)s * oci$parse%)c+ "select 'irst$name+ last$name
'rom emplo#ees
order /#
case :o/
when 0A5B7:$M6N-0 then 'irst$name
else last$name
end"&!
)Cs * "A5B7:$M6N-"!
oci$/ind$/#$name%)s+ ":o/"+ )Cs&!
oci$e.ecute%)s&!
0!ing :OWI# )ind <aria$le!
The pseudo?column RO0:D un!>uel !den"!'!es a ro+ +!"h!n a "able. Th!s e/ample sho+s
'e"ch!ng a record, chang!ng "he da"a, and b!nd!ng !"s RO0:D !n "he ?>-B- clause o' an REL6:-
s"a"emen".
Script 69' ro,id"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
// Aetch a record
)s * oci$parse%)c+
0select rowid+ street$address
'rom locations where location$id * :l$/C0&!
)locid * @000! // location to 'etch
oci$/ind$/#$name%)s+ 0:l$/C0+ )locid&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734H345$B-:RBM$MRKK7&!
)rid * )row90B3?5L0<!
&0(
Bsing >ind @aria5les in !repared #tatements
)addr * )row907:B--:$6LLB-770<!
// 4hange the address to upper case
)addr * strtoupper%)addr&!
// 7aCe new Calue
)s * oci$parse%)c+
0update locations set street$address * :a$/C where rowid * :r$/C0&!
oci$/ind$/#$name%)s+ 0:r$/C0+ )rid+ -1+ 345$I$B3?5L&!
oci$/ind$/#$name%)s+ 0:a$/C0+ )addr&!
oci$e.ecute%)s&!
?
%'"er runn!ng ro,id"php, "he address has been changed 'rom
Nurtenstrasse 921
"o
NRB:-M7:B677- 921
I1pro-ing Per*or1ance $6 Pre*etching and Caching
PHP OC:$ can use se&eral +ell (no+n Oracle da"a access 'ea"ures "o !mpro&e PHP appl!ca"!on
per'ormance.
Tuning the Pre*etch Si8e
Mou can "une PHPKs o&erall >uer per'ormance +!"h "he php"ini con'!gura"!on parame"er
oci/"de*ault=pre*etch. Th!s parame"er se"s "he number o' e/"ra ro+s re"urned !n a ba"ch +hen
an underl!ng 'e"ch call across "he ne"+or( "o "he da"abase occurs. :ncreas!ng "he pre'e"ch
&alue can s!gn!'!can"l !mpro&e per'ormance o' >uer!es "ha" re"urn a large number o' ro+s. :"
m!n!m!1es da"abase ser&er round3trips b re"urn!ng as much da"a as poss!ble each "!me an
underl!ng ne"+or( 'e"ch re>ues" "o "he da"abase !s made.
%ll "he pre'e"ched ro+s are cached b "he Oracle cl!en" l!brar!es and "here !s no !n"er'ace
!mpac" "o PHP appl!ca"!ons 'rom al"er!ng "he &alue. PHP 'unc"!ons l!(e oci$'etch$arra#%&
re"urn one ro+ "o "he user per call regardless o' "he pre'e"ch s!1e. 4ubse>uen" OC:$ 'e"ches
+!ll consume "he da"a 'rom "he cache un"!l e&en"uall ano"her ba"ch o' records !s needed "o
be re"r!e&ed 'rom "he da"abase.
&0)
4%ecuting #;L #tatements With .C'1
Mou can also change "he pre'e"ch &alue a" run"!me +!"h "he oci$set$pre'etch%& 'unc"!on)
)s * oci$parse%)c+ "select cit# 'rom locations"&!
oci$e.ecute%)s&!
oci_set_pre2etch($s 3$$)4
)row * oci$'etch$arra#%)s+ 345$67734&!
2or oci$'etch$all%&, +h!ch re"urns all >uer ro+s "o "he PHP scr!p" !n one call, PHP OC:$
!n"ernall 'e"ches "he records 'rom "he da"abase !n ba"ches.
Tes"!ng +!ll sho+ "he op"!mal pre'e"ch s!1e 'or our >uer!es. There !s no bene'!" us!ng "oo
large a pre'e"ch &alue. Con&ersel, because Oracle dnam!call alloca"es space, "here !s l!""le
"o be ga!ned b reduc!ng "he &alue "oo small.
The de'aul" pre'e"ch &alue !s 100. Pr!or "o OC:$ 1.I, "he de'aul" +as 10 and "he OC:$
e/"ens!on also capped "he memor used b "he pre'e"ch bu''er a" 102J S
oci/"de*ault=pre*etch b"es.
2rom OC:$ 1.J "he pre'e"ch &alue can be se" "o 0. The pre'e"ch &alue !s "he number o'
e/"ra ro+s "o be 'e"ched on each underl!ng da"abase access, so a pre'e"ch &alue o' 0 means
onl one ro+ !s re"urned each "!me across "he ne"+or(. 0hen PHP !s l!n(ed +!"h Oracle 11gR2
l!brar!es, pre'e"ch!ng +!ll also occur 'or R;2 CUR4OR 'e"ches, see "he chap"er #sing PF;SEF
,ith O-./. 4e""!ng "he pre'e"ch &alue "o 0 ma be use'ul onl !n one edge case, +h!ch
!n&ol&es R;2 CUR4OR4.
Pre'e"ch!ng +or(s 'or nes"ed cursor columns as long as bo"h "he Oracle cl!en" l!brar!es
l!n(ed +!"h PHP and "he da"abase are bo"h Oracle Da"abase 11gR2. The de'aul" pre'e"ch &alue
!s used or !" can be o&err!dden pr!or "o e/ecu"!ng "he nes"ed cursor resource. To change "he
!nner pre'e"ch &alue 'or "he pre&!ous e/ample nestedcur&"php, add an oci$set$pre'etch%&
call. The ou"er 'e"ch +!ll s"!ll use "he oci/"de*ault=pre*etch &alue)
&0*
(igure 9/' )he *irst reDuest to the database *etches +ultiple ro,s to the cache" SubseDuent
*etches read *ro+ the cache ,ithout reDuiring DI access"
'mpro$ing !erAormance 5y !reAetching and Caching
Script 6?' nestedcur2"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s"l *
0select department$name+
cursor%select 'irst$name
'rom emplo#ees
where emplo#ees.department$id * departments.department$id& as nc
'rom departments
where department$id in %10+ 20+ @0&0!
)s * oci$parse%)c+ )s"l&!
)r * oci$e.ecute%)s&!
while %%)row1 * oci$'etch$arra#%)s+ 345$67734&& 8* 'alse& (
echo "Lepartment: " . )row190L-E6B:N-M:$M6N-0< . "</r2n"!
)nc * )row190M40<! // treat as a statement resource
oci_set_pre2etch($nc 3$)4 // oCerride de'ault pre'etch i' desired
oci$e.ecute%)nc&!
while %%)row2 * oci$'etch$arra#%)nc+ 345$67734H345$B-:RBM$MRKK7&& 8* 'alse& (
echo )row290A5B7:$M6N-0< . "</r2n"!
=
oci$'ree$statement%)nc&!
echo "</r2n"!
=
?
Pre'e"ch!ng !s no" used +hen >uer!es con"a!n .O73 or .O- columns. One par"!al solu"!on !s "o
s"ruc"ure "he appl!ca"!on so "ha" >uer!es onl need "o 'e"ch and d!spla par" o' "he .O- da"a,
+h!ch can be done e''!c!en"l. 2or e/ample a >uer 'e"ch!ng a column MM.O-CO. could be
changed "o 'e"ch d/ms$lo/.su/str%m#lo/col+ 1000+ 1& !ns"ead o' re"urn!ng all o' "he da"a
up'ron". % dr!ll?do+n l!n( on "he appl!ca"!on +ould "hen 'ull >uer 8us" one selec"ed .O-.
Tuning the State1ent Cache Si8e
Per'ormance !s !mpro&ed +!"h OracleAs Dcl!en"E C"ha" !s, PHP OC:$F s"a"emen" cach!ng 'ea"ure.
:n "he PHP e/"ens!on "he de'aul" s"a"emen" cache s!1e !s 20 s"a"emen"s. Mou can change "he
s!1e +!"h "he php"ini d!rec"!&e oci/"state+ent=cache=sie. The recommenda"!on !s "o use "he
number o' s"a"emen"s !n "he appl!ca"!onKs +or(!ng se" o' 4B. as "he &alue. Cach!ng can be
d!sabled b se""!ng "he s!1e "o 0.
The cl!en"?s!de s"a"emen" cache !s !n add!"!on "o "he s"andard da"abase s"a"emen" cache.
The cl!en" s"a"emen" cache means e&en "he "e/" o' "he s"a"emen" does no" need "o be
"ransm!""ed "o "he da"abase more "han once, reduc!ng ne"+or( "ra''!c and da"abase ser&er
load. The da"abase can d!rec"l loo( up "he s"a"emen" con"e/" !n !"s cache +!"hou" e&en
ha&!ng "o hash "he s"a"emen". :n "urn, "he da"abase does no" need "o "rans'er me"a?da"a
abou" "he s"a"emen" bac( "o PHP.
&0+
4%ecuting #;L #tatements With .C'1
The cache !s per?Oracle sess!on so "h!s 'ea"ure !s more use'ul +hen pers!s"en" connec"!ons are
used. .!(e man "un!ng op"!ons, "here !s a "!me<memor "rade?o'' +hen "+ea(!ng "h!s
parame"er. The s"a"emen" cache also means sl!gh"l more load !s pu" on "he PHP hos".
To "une "he s"a"emen" cache s!1e, mon!"or general +eb ser&er load and "he da"abase
s"a"!s"!c @bytes sent via SEFG2et to client@. Th!s can be seen, 'or e/ample, !n Oracle %u"oma"!c
0or(load Repos!"or C%0RO repor"s. 0hen cach!ng !s e''ec"!&e, "he s"a"!s"!c should sho+ an
!mpro&emen". %d8us" "he &alue o' oci/"state+ent=cache=sie "o our sa"!s'ac"!on.
:' "he schema changes, such as dur!ng "he !n!"!al des!gn and pro"o"p!ng phases o' an
appl!ca"!on, ou ma e/per!ence errors such as O:A3A&AA? variable not in select list or O:A3
AA862' inconsistent datatypes because "he s"a"emen" cache can become ou" o' snc. The
+a "o pre&en" "h!s !s "o "urn o'' s"a"emen" cach!ng and res"ar" %pache.
OC:$ +!ll clear "he cache !' a s"a"emen" re"urns a da"abase error.
0!ing the Ser-er and Client &uer6 :e!ult Cache!
Oracle Da"abase 11g !n"roduces Dser&er?s!deEand Dcl!en"?s!deE resul" caches. These s"ore "he
'!nal resul" o' >uer!es, reduc!ng "he +or( needed +hen >uer!es are re?e/ecu"ed.
The da"abase cache !s enabled +!"h "he R;4U.TNC%CH;NMOD; da"abase parame"er, +h!ch
has se&eral se""!ngs. 0!"h Oracle 11gR2, "ables +h!ch are cand!da"es 'or >uer resul"s be!ng
cached can be nom!na"ed +!"h CR;%T; T%-.;, or +!"h an %.T;R T%-.; command )
7SK alter ta/le emplo#ees result$cache %mode 'orce&!
7o PHP changes are re>u!red !n Oracle 11gR2. %ppl!ca"!ons +!ll !mmed!a"el bene'!" 'rom
caches +hen "he ;MP.OM;;4 "able !s >uer!ed. 0!"h Oracle 11gR1, ou do need "o add a h!n"
"o "he >uer)
)s * oci$parse%)c+ "select /JH result$cache J/ J 'rom emplo#ees"&!
The cl!en" cache !s !deal 'or small >uer!es 'rom !n're>uen"l mod!'!ed "ables, such as loo(?up
"ables. :" can reduce PHP s"a"emen" process!ng "!me and s!gn!'!can"l reduce da"abase CPU
usage, allo+!ng "he da"abase "o handle more PHP processes and users. The cl!en"?s!de cache
!s per PHP process.
&0-
(igure 98' )he second ti+e a state+ent is issued, the state+ent text is not sent to the
database"
'mpro$ing !erAormance 5y !reAetching and Caching
% (e 'ea"ure !s "ha" Oracle au"oma"!call handles cache en"r !n&al!da"!on +hen a da"a
change !n&al!da"es "he s"ored resul"s. Oracle +!ll chec( "he cl!en" cache &al!d!" each "!me an
round trip "o "he da"abase occurs. :' no round "r!p has happened +!"h!n a con'!gurable DlagE
"!me, "he cl!en" cache !s assumed s"ale and "he ne/" >uer +!ll go "o "he da"abase 'or
process!ng. The cache +!ll be re'reshed a" "h!s "!me.
The Oracle -all .nter*ace Progra++er%s Guide, &&g :elease 2 N&&"2O con"a!ns "he bes"
descr!p"!on o' "he 'ea"ure and has more abou" +hen "o use !" and ho+ "o manage !".
Cl!en" Buer Resul" Cach!ng CCRCF !s bes" su!"ed 'or small loo(up "ables, so commonl "he
>uer s"a"emen" +!ll be s"a"!c and +onA" !n&ol&e b!nd &ar!ables. :' >uer!es ha&e s"r!ng b!nds,
such as "he de'aul" b!nd "pe, PHP >uer!es +onA" be able "o use CRC. Ho+e&er CRC !s used
+hen b!nd!ng numbers +!"h 4B.TN:7T l!(e)
oci$/ind$/#$name%)s+ ":/C"+ )/C+ -1+ 7SK:$5M:&!
To demons"ra"e cl!en" cach!ng, "he da"abase parame"er C.:;7TNR;4U.TNC%CH;N4:9; can be
se" "o a non 1ero &alue and "he Oracle da"abase res"ar"ed)
) s"lplus / as s#sd/a
7SK alter s#stem set client$result$cache$siXe*PDN scope*sp'ile!
7SK startup 'orce
-ecause "he ;MP.OM;;4 "able +as al"ered abo&e "o al+as be a cand!da"e 'or cach!ng, "he
PHP code needs no mag!c "o "a(e ad&an"age o' CRC !n Oracle 11gR2)
Script 6/' crc"php
<?php
)c * oci$pconnect%0hr0+ 0welcome0+ 0localhost/orcl0&!
'or %)i * 0! )i < 1000! HH)i& (
)s * oci$parse%)c+ "select J 'rom emplo#ees where rownum < 2"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
=
?
Ho+e&er, !' PHP !s l!n(ed +!"h Oracle 11.1 cl!en" l!brar!es, change "he >uer "o use a h!n")
select /JH result$cache J/ J 'rom emplo#ees where rownum < 2
%lso, pr!or "o Oracle 11.2.0.2 ma(e sure no" "o au"o comm!". :ns"ead do)
oci$e.ecute%)s+345$M3$6R:3$43NN5:&!
-e'ore e/ecu"!ng crc"php, run "h!s >uer !n "he 4B.SPlus sess!on)
7SK select parse$calls+ e.ecutions+ s"l$te.t
2 'rom C)s"l
@ where s"l$te.t like 0Femplo#eesF0!
E6B7-$46KK7 -,-4R:53M7 7SK$:-,:
----------- ---------- ---------------------------------------------------
1 1 select parse$calls+ e.ecutions+ s"l$te.t 'rom C)s"l
&00
4%ecuting #;L #tatements With .C'1
where s"l$te.t like 0Femplo#eesF0
Th!s sho+s "he da"abase be!ng accessed +hen "he >uer !s e/ecu"ed. :n!"!all !" sho+s 8us" "he
mon!"or!ng >uer !"sel'.
:n ano"her "erm!nal +!ndo+, run crc"php 'rom "he command l!ne or run !" !n a bro+ser Y !"
doesnA" d!spla an resul"s.
) php crc.php
Re?runn!ng "he mon!"or!ng >uer sho+s "ha" dur!ng "he 1000 loop !"era"!ons, "he da"abase
e/ecu"ed "he PHP >uer 8us" "+!ce, once 'or "he !n!"!al e/ecu"!on and "he second "!me b a
subse>uen" cache &al!da"!on chec()
E6B7-$46KK7 -,-4R:53M7 7SK$:-,:
----------- ---------- ---------------------------------------------------
2 2 select J 'rom emplo#ees where rownum < 2
2 2 select parse$calls+ e.ecutions+ s"l$te.t 'rom C)s"l
where s"l$te.t like 0Femplo#eesF0
Th!s means "ha" LL$ o' "he "!mes "he s"a"emen" +as per'ormed, "he cl!en" cache +as used 'or
"he resul"s, +!"h no da"abase access re>u!red.
7o+ ed!" crc"php and add /JH no$result$cache J/ "o "he 4B. s"a"emen")
)s * oci$parse%)c+
"select 56# no_res!"t_cache 65 J 'rom emplo#ees where rownum < 2"&!
Re?run "he scr!p")
) php crc.php
The mon!"or!ng >uer no+ sho+s "he mod!'!ed >uer +as e/ecu"ed 1000 "!mes, or once per
loop !"era"!on. Th!s means "he cl!en" >uer resul" cache +as no" used and each !"era"!on had
"o be sen" "o "he da"abase and processed)
E6B7-$46KK7 -,-4R:53M7 7SK$:-,:
----------- ---------- ----------------------------------------------------
2 2 select J 'rom emplo#ees where rownum < 2
@ @ select parse$calls+ e.ecutions+ s"l$te.t 'rom C)s"l
where s"l$te.t like 0Femplo#eesF0
2 1000 select /JH no$result$cache J/ J 'rom emplo#ees where
rownum < 2
% ded!ca"ed &!e+ C.:;7TNR;4U.TNC%CH;N4T%T4W !s per!od!call upda"ed +!"h s"a"!s"!cs on
cl!en" cach!ng. 2or shor" "es"s l!(e "h!s e/ample +here "he process >u!c(l runs and
"erm!na"es, !" ma no" g!&e mean!ng'ul resul"s and ,W4B. can be more use'ul.
5onitoring OCI. S&' State1ent!
Mon!"or!ng !s "he '!rs" s"ep "o "un!ng appl!ca"!ons. The da"abase?cen"r!c approach !s "o '!rs"
"une "he appl!ca"!on, ne/" "une "he 4B., and '!nall "une "he da"abase.
OC:$ 1.J CPHP H.IF allo+s some me"a da"a "o be passed "o Oracle +h!ch can help assess
"he !mpac" o' our appl!ca"!on on "he ss"em and !den"!' per'ormance !ssues. The chap"er
&01
:onitoring .C'1 #;L #tatements
-onnecting to Oracle using O-./ sho+ed us!ng oci$set$client$identi'ier%& 'or "rac!ng and
mon!"or!ng. -elo+ are some o"her OC:$ 'ea"ures "ha" can also be use'ul.
OCI. #ri-er Identi*ication
OC:$ 1.J au"oma"!call se"s "he DR:,;RN7%M; a""r!bu"e o' ,W4;44:O7NCO77;CTN:72O C+hen
us!ng Oracle 11gR2 cl!en" l!brar!esF. Th!s allo+s adm!n!s"ra"ors "o mon!"or +h!ch appl!ca"!ons
connec" "o "he da"abase. The a""r!bu"e &alue se" !s @PHP OC:$@ 'ollo+ed b "he OC:$ &ers!on
number. Mou can "es" b runn!ng a scr!p")
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
sleep%20&! // let the script run+ so the trace in'ormation can /e Ciewed
:n 4B.SPlus ou can >uer ,W4;44:O7NCO77;CTN:72O)
select uni"ue sid+ client$driCer+ authentication$t#pe
'rom C)session$connect$in'o
where client$driCer like 0E>E 3458F0
order /# sid!
Th!s sho+s some"h!ng l!(e)
75L 4K5-M:$LB
---------- ---------
22 E>E 3458
7o"e "he &!e+ "runca"es "he dr!&er name a""r!bu"e "o n!ne charac"ers !n curren" releases o'
Oracle. The @U7:BU;@ clause !s used because ,W4;44:O7NCO77;CTN:72O &!e+ !s no"
normal!1ed) each Oracle 7e" banner 'or "he sess!on appears !n one ro+. %no"her column !n "he
,W4;44:O7NCO77;CTN:72O &!e+ !s C.:;7TNCH%R4;T. Th!s could be used "o &er!' all PHP
appl!ca"!ons are us!ng "he correc" charac"er se". %" d!sconnec" "!me, en"r!es used 'or 8ob
cleanup ma be sho+n !n "h!s &!e+. :" can be use'ul "o 8o!n ,W4;44:O7NCO77;CTN:72O +!"h
,W4;44:O7.
Setting ,pplication In*or1ation in PHP OCI.
OC:$ 1.J !n"roduced 'unc"!ons "o se" user de'!ned a""r!bu"e &alues 'or "rac!ng)
oci$set$module$name%&, oci$set$action%& and oci$set$client$in'o%&.
The &alues are &!s!ble !n &ar!ous da"a d!c"!onar &!e+s !n "he da"abase, such as
,W4;44:O7. Tools l!(e Oracle ;n"erpr!se Manager allo+ search!ng and group!ng on "he &alues.
Mou can also arch!"ec" our code "o use "he &alues. 2or e/ample "he can be &!e+ed and
"es"ed !n 4B. >uer!es us!ng "he 4M4NCO7T;=TCF 'unc"!on.
The a""r!bu"es are sen" "o "he da"abase +!"h "he ne/" round"r!p, +h!ch occurs mos"
commonl +hen a 4B. or P.<4B. s"a"emen" !s e/ecu"ed. Th!s !s "he mos" e''!c!en" +a "o se"
"he &alues. :' Cl!en" Buer Resul" Cach!ng !s enabled, a round"r!p ma no" happen. 0hen
us!ng pers!s"en" connec"!ons, "he &alues ma no" be cleared a" "he end o' "he scr!p".
One use 'or "he MODU.; and %CT:O7 a""r!bu"es !s "o "rac( "he 4B. s"a"emen"s "ha" each
par" o' our appl!ca"!on e/ecu"es)
Script 68' appin*o"php
<?php
&02
4%ecuting #;L #tatements With .C'1
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
oci$set$client$in'o%)c+ 0N# 6pplication Zersion 20&!
oci$set$module$name%)c+ 0>ome Eage0&!
oci$set$action%)c+ 0Ariend Kookup0&!
// Lo some action which touches the data/ase
// :he three attri/ute Calues will /e "pigg# /acked"
// and sent with the 7SK to the data/ase
)s * oci$parse%)c+ 0select J 'rom dual0&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
// sleep so the trace in'ormation can /e Ciewed in 7SKJElus
sleep%20&!
?
The '!rs" "!me "he scr!p" !s run and "he 4B. s"a"emen" !s e/ecu"ed, "he MODU.; and %CT:O7
are recorded along +!"h "he 4B. s"a"emen" !n "he ,W4B.%R;% &!e+)
select s"l$te.t+ module+ action
'rom C)s"larea
where module * 0>ome Eage0!
Th!s produces)
7SK$:-,: N3LRK- 64:53M
--------------------------- --------------- ----------------
select J 'rom dual >ome Eage Ariend Kookup
Th!s can help narro+ do+n +here problema"!c s"a"emen"s are coded and le"s per'ormance
!ssues be resol&ed.
0!"h older &ers!ons o' OC:$, use P.<4B. "o se" "he a""r!bu"es. Ho+e&er "h!s me"hod !ncurs
a round"r!p +h!ch +!ll slo+ do+n "he appl!ca"!on)
)s * oci$parse%)c+
"/egin
d/ms$application$in'o.set$client$in'o%0N# 6pplication Zersion 20&!
d/ms$application$in'o.set$module%
0>ome Eage0+ // Nodule
0Ariend Kookup0&! // 6ction
end!"&!
oci$e.ecute%)s&!
'I5IT? ,uto7Incre1ent? 'a!t In!ert I# and 5ultiple In!ert!
:' ou are m!gra"!ng 'rom ano"her da"abase "o Oracle, "here are se&eral common opera"!ons
ou m!gh" ha&e used "ha" are handled d!''eren"l !n Oracle.
&13
L':'T" Auto'ncrement" Last 'nsert 'D and :ultiple 'nserts
'i1iting :o;! and Creating Paged #ata!et!
Oracle 11g 4B. does no" ha&e a K5N5: (e+ord. There are se&eral al"erna"!&e +as "o l!m!"
"he number o' ro+s re"urned !n OC:$.
The canon!cal pag!ng >uer 'or Oracle$i on+ards !s g!&en on http://asktom.oracle.com)
select J
'rom % select a.J+ rownum as rnum
'rom %;3RB$SR-B;$Y3-7$>-B- -- including the order /#& a
where rownum <* N6,$B3? &
where rnum * N5M$B3?
Here, M:7NRO0 !s "he ro+ number o' '!rs" ro+ and M%=NRO0 !s "he ro+ number o' "he las"
ro+ "o re"urn. :n PHP ou m!gh" do "h!s)
Script 5A' li+it"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!

)m#stmt * "select cit# 'rom locations order /# cit#"!
)minrow * D! // row num/er o' 'irst row to return
)ma.row * 8! // row num/er o' last row to return
)pages"l * "select J
'rom % select a.J+ rownum as rnum
'rom % )m#stmt & a
where rownum <* :ma.row&
where rnum * :minrow"!
)s * oci$parse%)c+ )pages"l&!
oci$/ind$/#$name%)s+ ":ma.row"+ )ma.row&!
oci$/ind$/#$name%)s+ ":minrow"+ )minrow&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
?
7o"e "ha" )m#stmt !"sel' !s no" bound. -!nd da"a !s no" "rea"ed as code, so ou canno" b!nd "he
"e/" o' "he s"a"emen" and e/pec" !" "o be e/ecu"ed. -e+are o' 4B. !n8ec"!on secur!" !ssues !'
4B. s"a"emen"s are cons"ruc"ed or conca"ena"ed.
The ou"pu" o' "he scr!p" !s)
arra#%2& (
9"45:;"<*
arra#%5& (
90<*
string%P& "YeneCa"
91<*
string%9& ">iroshima"
92<*
&1&
4%ecuting #;L #tatements With .C'1
string%P& "Kondon"
9@<*
string%11& "Ne.ico 4it#"
9D<*
string%P& "Nunich"
=
9"BMRN"<*
arra#%5& (
90<*
string%1& "D"
91<*
string%1& "5"
92<*
string%1& "P"
9@<*
string%1& "U"
9D<*
string%1& "8"
=
=
%n al"erna"!&e and pre'erred >uer sn"a/ uses OracleKs anal"!c B3?$MRNI-B%& 'unc"!on. The
>uer)
select last$name+ row$num/er%& oCer %order /# last$name& as m#r
'rom emplo#ees
re"urns "+o columns !den"!'!ng "he las" name +!"h !"s ro+ number)
K67:$M6N- N;B
------------------------- ----------
6/el 1
6nde 2
6tkinson @
. . .
- "urn!ng "h!s !n"o a sub>uer and us!ng a ?>-B- cond!"!on an range o' names can be
>uer!ed. 2or e/ample "o ge" "he 11"h "o 20"h names "he >uer !s)
select last$name AB3N
%select last$name+
row$num/er%& oCer %order /# last$name& as m#r
'rom emplo#ees&
where m#r /etween 11 and 20
:n 4B.SPlus "he ou"pu" !s)
K67:$M6N-
-------------------------
Iissot
Iloom
Iull
4a/rio
4am/rault
4am/rault
4hen
&1(
L':'T" Auto'ncrement" Last 'nsert 'D and :ultiple 'nserts
4hung
4olmenares
LaCies
%s an an"!?e/ample, ano"her +a "o l!m!" "he number o' ro+s re"urned !n&ol&es "he
oci$'etch$all%& 'unc"!on, +h!ch has op"!onal argumen"s "o spec!' a range o' resul"s "o
'e"ch. Th!s !s !mplemen"ed b "he e/"ens!on, no" b OracleKs na"!&e 'unc"!onal!". %ll ro+s
preced!ng "hose ou +an" s"!ll ha&e "o be 'e"ched 'rom "he da"abase. These unused ro+s are
d!scarded, +h!ch !s +as"e'ul o' ne"+or( and process!ng resources)
)'irstrow * @!
)numrows * 5!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res+ )'irstrow+ )numrows&!
Car$dump%)res&!
:" !s more e''!c!en" "o le" Oracle do "he ro+ selec"!on and onl re"urn "he e/ac" number o' ro+s
re>u!red.
,uto7Incre1ent Colu1n!
%u"o?!ncremen" columns !n Oracle can be crea"ed us!ng a se>uence genera"or and a "r!gger.
4e>uence genera"ors are de'!ned !n "he da"abase and re"urn Oracle numbers. 4e>uence
numbers are genera"ed !ndependen"l o' "ables. There'ore, "he same se>uence genera"or can
be used 'or more "han one "able or an+here "ha" ou +an" "o use a un!>ue number.
4e>uence genera"!on !s use'ul "o genera"e un!>ue pr!mar (es 'or our da"a and "o
coord!na"e (es across mul"!ple "ables. Mou can ge" a ne+ &alue 'rom a se>uence genera"or
us!ng "he M-,:Z6K opera"or !n a 4B. s"a"emen". Th!s g!&es "he ne/" a&a!lable number and
!ncremen"s "he genera"or. The s!m!lar 4RBBZ6K opera"or re"urns "he curren" &alue o' a
se>uence +!"hou" !ncremen"!ng "he genera"or.
% "r!gger !s a P.<4B. procedure "ha" !s au"oma"!call !n&o(ed a" a prede"erm!ned po!n". :n
"h!s e/ample a "r!gger !s !n&o(ed +hene&er an !nser" !s made "o a "able.
:n 4B.SPlus an au"o !ncremen" column MM:D can be crea"ed l!(e)
Script 5&' autoinc"sDl
create se"uence m#se"!
create ta/le m#ta/le %m#id num/er primar# ke#+ m#data Carchar2%20&&!
create trigger m#trigger
/e'ore insert on m#ta/le 'or each row
/egin
:new.m#id :* m#se".ne.tCal!
end!
/
Pr!or "o Oracle Da"abase 11g ou need "o 'e"ch "he &alue us!ng a 7-K-4: l!(e)
select m#se".ne.tCal into :new.m#id 'rom dual!
:n PHP !nser" "+o ro+s)
&1)
4%ecuting #;L #tatements With .C'1
Script 52' autoinc"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "insert into m#ta/le %m#data& Calues %0>ello0&"&!
oci$e.ecute%)s&!
)s * oci$parse%)c+ "insert into m#ta/le %m#data& Calues %0I#e0&"&!
oci$e.ecute%)s&!
?
Buer!ng "he "able !n 4B.SPlus sho+s "he MM:D &alues +ere au"oma"!call !nser"ed and
!ncremen"ed)
7SK select J 'rom m#ta/le!
N;5L N;L6:6
---------- --------------------
1 >ello
2 I#e
The !den"!'!er numbers +!ll be un!>ue and !ncreas!ng bu" ma no" be consecu"!&e. 2or
e/ample !' someone rolls bac( an !nser", a se>uence number can be Dlos"E.
Getting the 'a!t In!ert I#
OC:$ does no" ha&e an e/pl!c!" D!nser"N!dE 'unc"!on. :ns"ead, use a B-:RBM 5M:3 clause and a
b!nd &ar!able. Us!ng "he "able and "r!gger crea"ed abo&e !n autoinc"sDl, "he !nser" +ould be)
Script 56' insertid"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+
"insert into m#ta/le %m#data& Calues %0>ello0& ret!rn -,id into 7id"&!
oci$/ind$/#$name%)s+ ":id"+ )id+ 20+ 7SK:$5M:&!
oci$e.ecute%)s&!
echo "Lata inserted with id: )id2n"!
?
Th!s re"urns "he &alue o' "he MM:D column 'or "he ne+ ro+ !n"o "he PHP &ar!able )id. The
ou"pu", assum!ng "he "+o !nser"s o' autoinc"php +ere pre&!ousl e/ecu"ed, !s)
Lata inserted with id: @
Mou could s!m!larl re"urn "he RO0:D o' "he ne+ ro+ !n"o a descr!p"or)
)rid * oci_new_descriptor%)c+ &CI_*_8&9I*&!
)s * oci$parse%)c+
"insert into m#ta/le %m#data& Calues %0>ello0& ret!rn rowid into 7rid"&!
&1*
L':'T" Auto'ncrement" Last 'nsert 'D and :ultiple 'nserts
oci$/ind$/#$name%)s+ ":rid"+ )rid+ -1+ &CI_:_8&9I*&!
oci$e.ecute%)s&!
In!erting 5ultiple <alue!
4ome da"abases allo+ mul"!ple &alues "o be !nser"ed !n one call s!m!lar "o)
insert into m#ta/ %col$1+ col$2& Calues %1+2&+%@+D&!
:n Oracle, ou can use oci$/ind$arra#$/#$name%& Csee "he chap"er on P.<4B.F or "r "he
:74;RT %.. s"a"emen")
insert all
into m#ta/ %col$1+ col$2& Calues %1+ 2&
into m#ta/ %col$1+ col$2& Calues %@+ D&
select 1 'rom dual!
DonA" 'orge" "o b!nd da"a &alues unl!(e "h!s s!mple e/ample sho+s.
-enchmar( our !mplemen"a"!on !n an en&!ronmen" represen"a"!&e o' our produc"!on
ss"em. :' ou ha&e a large number o' &alues, or ha&e "o bu!ld up "he s"a"emen" "e/" b s"r!ng
conca"ena"!on !n a loop, or ha&e a 'as" ne"+or(, "hen mul"!ple :74;RT s"a"emen"s m!gh" be
'as"er.
:' ou are m!gra"!ng "o Oracle, +a"ch ou" 'or d!''erences !n "ransac"!onal beha&!or, s!nce
'a!lure +!ll cause "he +hole s"a"emen" "o be rolled bac( unl!(e some o"her da"abases.
One rela"ed use o' :74;RT %.. !s "o !nser" !n"o mul"!ple d!''eren" "ables !n "he one
s"a"emen".
Eploring Oracle
;/plore "he 4B. and P.<4B. languages. Ma(e ma/!mum reuse o' 'unc"!onal!" "ha" alread
e/!s"s. Tom 6"eKs popular s!"e, http://asktom.oracle.com, has a lo" o' use'ul !n'orma"!on.
OracleKs general gu!del!ne !s "o le" "he da"abase manage da"a and "o "rans'er "he
m!n!mum amoun" across "he ne"+or(. %&o!d sh!pp!ng da"a 'rom "he da"abase "o PHP 'or
unnecessar pos" process!ng. Da"a !s a core asse" o' our bus!ness. :" should be "rea"ed
cons!s"en"l across our appl!ca"!ons. 6eep!ng a "h!n !n"er'ace be"+een our appl!ca"!on laer
and "he da"abase !s also good programm!ng prac"!ce.
There are man more use'ul 4B. and Da"abase 'ea"ures "han "hose descr!bed !n "h!s boo(.
The are le'" 'or ou "o e/plore. % 'e+ are men"!oned belo+.
Ca!e In!en!iti-e #ata 5atching in &uerie!
:' ou +an" "o do >uer!es "ha" sor" and ma"ch da"a !n a case !nsens!"!&e manner, change "he
sess!on a""r!bu"es 7.4N4ORT and 7.4NCOMP '!rs", e!"her +!"h en&!ronmen" &ar!ables, or per
sess!on)
alter session set nls$sort * /inar#$ci!
alter session set nls$comp * linguistic!
&1+
4%ecuting #;L #tatements With .C'1
,nal6tic 9unction! in S&'
OracleKs %nal"!c 'unc"!ons are a use'ul "ool "o compu"e aggrega"e &alues based on a group o'
ro+s. Here !s an e/ample o' a correla"!on. 43BB%& re"urns "he coe''!c!en" o' correla"!on o' a se"
o' number pa!rs)
select ma.$e.tents+ corr%ma.$trans+ initial$e.tent&
'rom all$ta/les
group /# ma.$e.tents!
Mou mus" be connec"ed as "he 4M4T;M user !n "h!s par"!cular e/ample, s!nce !" depends on
"able da"a no" a&a!lable "o "he HR schema.
O"her anal"!c 'unc"!ons allo+ ou "o ge" bas!c !n'orma"!on l!(e s"andard de&!a"!ons or do
"as(s such as ran(!ng C'or Top?7 or -o""om?7 >uer!esF or do l!near regress!ons.
Eternal Ta$le!
Oracle ;/"ernal "ables allo+ da"a ou"s!de "he da"abase "o be accessed as !' !" +ere !n a
da"abase "able. Mou can read and +r!"e da"a. ;/"ernal "ables can be used "o load and unload
da"a. :n Oracle Da"abase 11g >uer!ng an e/"ernal "able can !n&o(e an e/"ernal program
+h!ch can genera"e "he da"a.
&1-
CH,PTE: 12
0SING P'2S&' WITH OCI.
P.<4B. !s OracleKs procedural language e/"ens!on "o 4B.. :" !s a da"abase?s!de language "ha"
!s eas?"o?use. P.<4B. enables ou "o m!/ 4B. s"a"emen"s +!"h procedural cons"ruc"s. PHP
can call P.<4B. bloc(s "o ma(e use o' ad&anced da"abase 'unc"!onal!", and can use !" "o
e''!c!en"l !nser" and 'e"ch da"a. %s +!"h 4B., "he P.<4B. language g!&es appl!ca"!ons eas
access "o OracleKs be""er da"e and number handl!ng, 'or e/ample "o ma(e sure our '!nanc!al
da"a !s no" a''ec"ed b PHPKs 'loa"!ng po!n" seman"!cs. Mou can crea"e s"ored procedures,
'unc"!ons and pac(ages so our bus!ness log!c !s reusable !n all our appl!ca"!ons. P.<4B. has
an !nbu!l" na"!&e comp!ler, op"!m!1!ng and debugg!ng 'ea"ures, and a \+rapK code ob'usca"!on
'ac!l!" "o pro"ec" "he !n"ellec"ual proper" !n appl!ca"!ons.
P'2S&' O-er-ie;
% P.<4B. bloc( has "hree bas!c par"s)
%n op"!onal declara"!&e par" L-4K6B-
%n e/ecu"able par" I-Y5M ... -ML
%n op"!onal e/cep"!on?handl!ng par" -,4-E:53M
%n e/ample P.<4B. bloc( !s)
declare
sal$l pls$integer!
/egin
select salar# into sal$l 'rom emplo#ees where emplo#ee$id * 191!
d/ms$output.put$line%07alar# is 0 [[ sal$l&!
e.ception
when no$data$'ound then
d/ms$output.put$line%0Mo results returned0&!
end!
Mou can run "h!s !n man "ools, !nclud!ng PHP. :n OracleKs 4B.SPlus !" !s run b en"er!ng "he
"e/" a" "he promp" and '!n!sh!ng +!"h a s!ngle slash C/F "o "ell 4B.SPlus "o e/ecu"e "he code. :'
ou "urn on 7-: 7-BZ-B3R:ER: be'orehand, "hen 4B.SPlus +!ll d!spla "he ou"pu" messages
a'"er e/ecu"!on)
7SK set serCeroutput on
7SK declare
2 sal$l pls$integer!
@ /egin
D select salar# into sal$l
5 'rom emplo#ees
P where emplo#ee$id * 191!
U d/ms$output.put$line%07alar# is 0 [[ sal$l&!
8 e.ception
9 when no$data$'ound then
10 d/ms$output.put$line%0Mo results returned0&!
&10
Bsing !L/#;L With .C'1
11 end!
12 /
7alar# is 2500
O"her "ools ha&e d!''eren" +as "o !nd!ca"e "he end o' "he s"a"emen"s and ho+ "o s+!"ch
ser&er ou"pu" on.
:' a PHP appl!ca"!on per'orms se&eral 4B. s"a"emen"s a" one "!me, !" can be e''!c!en" "o
bundle "he s"a"emen"s "oge"her !n a s!ngle P.<4B. procedure. :ns"ead o' e/ecu"!ng mul"!ple
4B. s"a"emen"s, PHP onl needs "o e/ecu"e one P.<4B. call. Th!s reduces "he number o'
round "r!ps be"+een PHP and "he da"abase, and can !mpro&e o&erall per'ormance.
There are a number o' pre?suppl!ed P.<4B. pac(ages "o ma(e appl!ca"!on de&elopmen"
eas!er. Pac(ages e/!s" 'or 'ull "e/" !nde/!ng, >ueu!ng, change no"!'!ca"!on, send!ng ema!ls, 8ob
schedul!ng and TCP access, 8us" "o name a 'e+. 0hen dec!d!ng +he"her "o +r!"e PHP on "he
m!d?"!er or P.<4B. !n "he ser&er, cons!der our s(!ll le&el !n "he languages, "he cos" o' da"a
"rans'er across "he ne"+or( and "he re?usab!l!" o' "he code. :' ou +r!"e !n P.<4B., all our
Oracle appl!ca"!ons !n an "ool or cl!en" language can reuse "he 'unc"!onal!".
)loc=!? Procedure!? Pac=age! and Trigger!
P.<4B. code can be ca"egor!1ed as one o' "he 'ollo+!ng)
%nonmous bloc(s
4"ored procedures or 'unc"!ons
Pac(ages
Tr!ggers
,non61ou! )loc=!
%n anonmous bloc( !s a P.<4B. bloc( !ncluded !n our appl!ca"!on "ha" !s no" named or
s"ored !n "he da"abase. The pre&!ous e/ample !s an anonmous bloc(. -ecause "hese bloc(s
are no" s"ored !n "he da"abase, "he are generall 'or one?"!me use !n a 4B. scr!p", or 'or
s!mple code dnam!call subm!""ed "o "he Oracle ser&er.
Stored Procedure! and 9unction!
% s"ored procedure !s a P.<4B. bloc( "ha" Oracle s"ores !n "he da"abase. The can be called b
name 'rom an appl!ca"!on. 2unc"!ons are s!m!lar bu" also re"urn a &alue +hen e/ecu"ed.
Procedures and 'unc"!ons can be used 'rom o"her procedures or 'unc"!ons. The can be
enabled and d!sabled "o pre&en" "hem be!ng used. The ma also ha&e an !n&al!d s"a"e, !'
an"h!ng "he re'erence !s no" a&a!lable. The can be crea"ed !nd!&!duall, or be par" o' a
pac(age.
0hen ou crea"e a s"ored procedure or 'unc"!on, Oracle s"ores !"s parsed represen"a"!on !n
"he da"abase 'or e''!c!en" reuse. Procedures can be crea"ed !n 4B.SPlus l!(e)
7SK create ta/le m#ta/ %m#data Carchar2%D0&+ m#id num/er&!
7SK create or replace procedure
2 m#proc%d$p in Carchar2+ i$p in num/er& as
@ /egin
&11
>locks" !rocedures" !ackages and Triggers
D insert into m#ta/ %m#data+ m#id& Calues %d$p+ i$p&!
5 end!
P /
The procedure !s onl crea"ed, no" run. Programs l!(e PHP can run !" la"er.
P.<4B. 'unc"!ons are crea"ed !n a s!m!lar +a us!ng "he 4B-6:- 3B B-EK64- ARM4:53M
command.
:' ou ha&e crea"!on errors, use "he 4B.SPlus 7>3? -BB3B7 command "o d!spla an
messages. 2or e/ample, crea"!ng a procedure "ha" re'erences an !n&al!d "able causes an error)
7SK create or replace procedure
2 m#proc%d$p in Carchar2+ i$p in num/er& as
@ /egin
D insert into ,o!rtab %m#data+ m#id& Calues %d$p+ i$p&!
5 end!
P /
?arning: Erocedure created with compilation errors.
7SK show errors
-rrors 'or EB34-LRB- N;EB34:
K5M-/43K -BB3B
-------- -----------------------------------------------------------------
D/@ EK/7SK: 7SK 7tatement ignored
D/15 EK/7SK: 3B6-009D2: ta/le or Ciew does not e.ist
:' ou are runn!ng 4B. scr!p" '!les !n 4B.SPlus, !" !s help'ul "o "urn 7-: -4>3 3M "o see "he l!ne
numbers.
4ee la"er belo+ 'or handl!ng P.<4B. errors !n PHP.
Pac=age!
Tp!call, s"ored procedures and 'unc"!ons are encapsula"ed !n"o pac(ages. Th!s helps
m!n!m!1es recomp!la"!on o' dependen" ob8ec"s. The pac(age spec!'!ca"!on de'!nes "he
s!gna"ures o' "he 'unc"!ons and procedures. :' "ha" de'!n!"!on !s unchanged, code "ha" !n&o(es
!" +!ll no" need "o be recomp!led e&en !' "he !mplemen"a"!on o' "he pac(age bod changes.
Script 55' toyshop"sDl
create ta/le to#s %id num/er+ name Carchar2%D0&&!
insert into to#s %id+ name& Calues %1+ 0/ic#cle0&!
commit!
create or replace package to#shop as
'unction 'ind$to#%id$p in num/er& return Carchar2!
procedure add$to#%id$p in num/er+ name$p in Carchar2&!
procedure 'ind$to#$proc%id$p in num/er+ name$p out Carchar2&!
end to#shop!
/
create or replace package /od# to#shop as
'unction 'ind$to#%id$p in num/er& return Carchar2 as
name$l Carchar2%20&!
&12
Bsing !L/#;L With .C'1
/egin
select name into name$l 'rom to#s where id * id$p!
return name$l!
end!
procedure add$to#%id$p in num/er+ name$p in Carchar2& as
/egin
insert into to#s %id+ name& Calues%id$p+ name$p&!
end!
procedure 'ind$to#$proc%id$p in num/er+ name$p out Carchar2& as
/egin
select name into name$p 'rom to#s where id * id$p!
end!
end to#shop!
/
Trigger!
% da"abase "r!gger !s a s"ored procedure assoc!a"ed +!"h a da"abase "able, &!e+, or e&en". The
"r!gger can be called a'"er "he e&en", "o record !", or "a(e some 'ollo+?up ac"!on. % "r!gger can
also be called be'ore an e&en", "o pre&en" erroneous opera"!ons or '!/ ne+ da"a so "ha" !"
con'orms "o bus!ness rules. Tr!ggers +ere sho+n earl!er as a +a "o op"!m!1e se""!ng da"e
'orma"s Csee Do 2ot Set the Date or 2u+eric (or+at #nnecessarily !n "he chap"er on
connec"!ngF and as a +a o' crea"!ng au"o?!ncremen" columns Csee Auto3.ncre+ent -olu+ns
!n "he pre&!ous chap"erO.
Creating P'2S&' Stored Procedure! in PHP
Procedures, 'unc"!ons and "r!ggers can be crea"ed us!ng PHP. 2or e/ample, "o crea"e a
procedure -:6;NCR;%T; "he code !s)
Script 54' bi1ecreate"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)pls"l * <<<0-370
create or replace procedure /ike$create%t#pe$p in Carchar2& as
/egin
insert into /ic#cles %st#le& Calues %t#pe$p&!
end!
-37! // this must /e at the start o' the line without leading whitespace
)s * oci$parse%)c+ )pls"l&!
)r * oci$e.ecute%)s&!
i' %)r& (
echo 0Erocedure created0!
=
?
&23
Creating !L/#;L #tored !rocedures in !H!
7o"e "he las" charac"er o' "he P.<4B. s"a"emen" !s a sem!?colon Ca'"er "he P.<4B. (e+ord
endF, +h!ch !s d!''eren" "o "he +a 4B. s"a"emen"s are "erm!na"ed !n Oracle.
The e/ample sho+s a PHP 7O0DOC con"a!n!ng "he s"a"emen". :' ou are on 0!ndo+s,
ma(e sure ou a&o!d "he end?o'?l!ne "erm!na"or !ssue men"!oned belo+.
4!m!lar "o "he earl!er per'ormance ad&!ce on crea"!ng "ables, a&o!d crea"!ng pac(ages and
procedures a" run"!me !n an appl!ca"!on. Pre?crea"e "hem as par" o' appl!ca"!on !ns"alla"!on.
End o* 'ine Ter1inator! in P'2S&' With Windo;! PHP
0!"h older &ers!ons o' Oracle on 0!ndo+s, mul"!?l!ne P.<4B. bloc(s +onA" run !' "he l!ne
"erm!na"ors are !ncorrec". The problem happens +hen "he end o' l!ne charac"ers !n a mul"!?l!ne
P.<4B. s"r!ng are 0!ndo+s carr!age?re"urn l!ne?'eeds)
)pls"l * "create or replace procedure
m#proc%d$p in Carchar2+ i$p in num/er& as
/egin
insert into m#ta/%m#data+ m#id& Calues %d$p+ i$p&!
end!"!
The "p!cal error !s O:A325655' success ,ith co+pilation error"
:' "he showcompilationerrors%& 'unc"!on, sho+n la"er, !s used, add!"!onal Oracle messages
+!ll sho+ "he error PFS3AA&A6' Encountered the sy+bol RR ,hen expecting one o* the
*ollo,ing. Th!s error, +h!ch ma ha&e "he smbol @G@ or a seem!ngl emp" "o(en represen"!ng
"he une/pec"ed end?o'?l!ne sn"a/, !s 'ollo+ed b a l!s" o' (e+ords or "o(ens "he P.<4B.
parser +as e/pec"!ng.
Use one o' "hese solu"!ons "o '!/ "he problem)
0r!"e "he P.<4B. code on a s!ngle l!ne)
)pls"l * "create or replace procedure m#proc . . . end!"!
Use PHP s"r!ng conca"ena"!on +!"h appropr!a"e +h!"e space padd!ng be"+een s"r!ng
"o(ens)
)pls"l * "create or replace procedure "
. "m#proc%d$p in Carchar2+ i$p in num/er& as "
. "/egin "
. "insert into m#ta/%m#data+ m#id& Calues %d$p+ i$p&! "
. "end!"!
Con&er" "he '!le "o use U7:=?s"le l!ne?'eeds +!"h a con&ers!on u"!l!" or ed!"or.
Calling P'2S&' Code
Calling P'2S&' Procedure! in PHP
To !n&o(e a P.<4B. procedure 'rom PHP, use I-Y5M and -ML "o crea"e an anonmous bloc()
Script 59' anonplsDl"php
<?php
&2&
Bsing !L/#;L With .C'1
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "begin to#shop.add$to#%2+ 0/all0&! end!"&!
oci$e.ecute%)s&!
?
The bloc( con"a!ns a s!ngle procedure call, bu" ou could !nclude an number o' o"her P.<4B.
s"a"emen"s.
Mou can also use "he 4B. 46KK s"a"emen" l!(e)
Script 5?' callplsDl"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "ca"" to#shop.add$to#%@+ 0paddling pool0&"&!
oci$e.ecute%)s&!
?
The call command !s ac"uall a 4B. command and does no" ha&e "he "ra!l!ng sem!?colon
needed 'or P.<4B. bloc(s.
"inding #arameters in #L0S1L #rocedure Calls
P.<4B. procedure and 'unc"!on argumen"s can be mar(ed :7, OUT or :7 OUT depend!ng on
+he"her da"a !s be!ng passed !n"o or ou" o' P.<4B.. 4!ngle &alue parame"ers can be bound !n
PHP +!"h oci$/ind$/#$name%&. :n "he toyshop"sDl e/ample, "he 'ind$to#$proc%& parame"ers
+ere :7 and OUT. The code could be)
)s * oci$parse%)c+ "/egin to#shop.'ind$to#$proc%:id+ :name&! end!"&!
)id * 1!
oci$/ind$/#$name%)s+ ":id"+ )id&!
oci$/ind$/#$name%)s+ ":name"+ )name+ D0&!
oci$e.ecute%)s&!
echo "Mame is: ".)name!
The b!nd call spec!'!es "ha" J0 b"es should be alloca"ed "o hold "he re"r!e&ed "o name. 2or
OUT and :7 OUT parame"ers, ma(e sure "he leng"h !s spec!'!ed !n "he b!nd call. %s men"!oned
!n "he pre&!ous chap"er, spec!'!ng "he leng"h 'or :7 b!nds !s o'"en a good !dea "oo, !' "he one
s"a"emen" !s e/ecu"ed mul"!ple "!mes !n a loop.
Calling P'2S&' 9unction! in PHP
Call!ng a P.<4B. 'unc"!on re>u!res a b!nd &ar!able 'or "he re"urn &alue. Us!ng "he 'unc"!on
'ind$to#%& crea"ed pre&!ousl !n toyshop"sDl)
Script 5/' plsDl*unc"php
<?php
&2(
Calling !L/#;L Code
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "/egin :name :* to#shop.'ind$to#%1&! end!"&!
oci$/ind$/#$name%)s+ 0:name0+ )name+ D0&!
oci$e.ecute%)s&!
echo "Mame is: " . )name!
?
The :* "o(en !s "he ass!gnmen" opera"or !n P.<4B.. Here !" ass!gns "he re"urn &alue o' "he
'unc"!on "o "he b!nd &ar!able. The b!nd call spec!'!es "ha" J0 b"es should be alloca"ed "o hold
"he resul". The scr!p" ou"pu" !s)
Mame is: /ic#cle
)inding 0n!upported P'2S&' T6pe!
4ome P.<4B. da"a "pes are !n"ernal "o P.<4B. and canno" be re"urned "hrough "he C laer
used b "he OC:$ e/"ens!on. :n "hese cases some e/"ra P.<4B. code "ha" maps "he "pe "o a
'orm usable !n PHP !s needed. 2or e/ample, "he P.<4B. user 'unc"!on is$Calid%& re"urns "he
!n"ernal Oracle "pe -OO.;%7)
Script 58' isvalid"sDl
create or replace 'unction is$Calid%p$uid in num/er& return /oolean as
/egin
i' %p$uid < 10& then
return true!
else
return 'alse!
end i'!
end!
/
The an"!?e/ample PHP code "o call "h!s !s)
Script 4A' isvalid"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s"l * "/egin :r :* is$Calid%:userid&! end!"! // will 'ail
)s * oci$parse%)c+ )s"l&!
oci$/ind$/#$name%)s+ 0:r0+ )r+ D0&!
)userid * D!
oci$/ind$/#$name%)s+ 0:userid0+ )userid&!
oci$e.ecute%)s&!
echo "Besult is " . %)r ? "true" : "'alse"& . "2n"!
?
&2)
Bsing !L/#;L With .C'1
The e/pec"a"!on !s "ha" user !d J !s less "han 10 and so "he resul" +!ll d!spla as true.
Ho+e&er, because o' "he use o' "he !n"ernal P.<4B. "pe, "h!s scr!p" ac"uall g!&es "he error
PFS3AA6/2' expression is o* ,rong type" The solu"!on !s "o change "he anonmous P.<4B.
s"a"emen" "o ma(e !" e&alua"e "he is$Calid%& re"urn &alue and propaga"e a "pe "ha" can be
bound !n OC:$)
)s"l * "/egin
i' %is$Calid%:userid& * true& then
:r :* 1!
else
:r :* 0!
end i'!
end!"!
The ou"pu" o' "he scr!p" !s no+)
Besult is true
,rra6 )inding and P'2S&' )ul= Proce!!ing
OC:$ 1.2 CPHP H.1.2F !n"roduced a 'unc"!on, oci$/ind$arra#$/#$name%&. Used +!"h a P.<4B.
procedure, "h!s can be &er e''!c!en" 'or !nser"!on or re"r!e&al, re>u!r!ng 8us" a s!ngle
oci$e.ecute%& "o "rans'er mul"!ple &alues. The 'ollo+!ng e/ample, arraybind"sDl, crea"es a
P.<4B. pac(age +!"h "+o procedures. The '!rs", m#insproc%&, +!ll be passed a PHP arra "o
!nser". :" uses OracleKs Dbul(E A3B6KK s"a"emen" 'or 'as" !nser"!on. The second procedure,
m#selproc%&, selec"s bac( 'rom "he "able us!ng "he IRKG 43KK-4: clause and re"urns "he arra
as "he OUT parame"er p$arr. The p$count parame"er !s used "o ma(e sure P.<4B. does no"
"r "o re"urn more &alues "han "he PHP arra can handle.
Script 4&' arraybind"sDl
drop ta/le m#ta/!
create ta/le m#ta/%name Carchar2%20&&!
create or replace package m#pkg as
t#pe arrt#pe is ta/le o' Carchar2%20& inde. /# pls$integer!
procedure m#insproc%p$arr in arrt#pe&!
procedure m#selproc%p$arr out arrt#pe+ p$count in num/er&!
end m#pkg!
/
show errors
create or replace package /od# m#pkg as
procedure m#insproc%p_arr in arrt,pe& is
/egin
2ora"" i in indices o' p$arr
insert into m#ta/ Calues %p$arr%i&&!
end m#insproc!
procedure m#selproc%p_arr o!t arrt,pe p_co!nt in n!-ber& is
/egin
select name b!"0 co""ect into p$arr 'rom m#ta/ where rownum <* p$count!
&2*
Array >inding and !L/#;L >ulk !rocessing
end m#selproc!
end m#pkg!
/
show errors
To !nser" a PHP arra )a !n"o MMT%-, use)
Script 42' arrayinsert"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)a * arra#%0a/c0+ 0de'0+ 0ghi0+ 0Wkl0&!
)s * oci$parse%)c+ "/egin m#pkg.m#insproc%:a&! end!"&!
oci_bind_arra,_b,_na-e%)s+ ":a"+ )a+ count%)a&+ -1+ 7SK:$4>B&!
oci$e.ecute%)s&!
?
The oci$/ind$arra#$/#$name%& 'unc"!on !s s!m!lar "o oci$/ind$/#$name%&. %s +ell as "he
upper da"a leng"h, !" has an e/"ra parame"er g!&!ng "he number o' elemen"s !n "he arra. :n
"h!s e/ample, "he number o' elemen"s !nser"ed !s count%)a&. The da"a leng"h Y1 "ells PHP "o
use "he ac"ual leng"h o' "he charac"er da"a, +h!ch !s (no+n "o PHP.
To >uer "he "able !n PHP, "he m#selproc%& procedure can be called. The number o'
elemen"s )numelems "o be 'e"ched !s passed !n"o m#selproc%& b be!ng bound "o :n. Th!s
l!m!"s "he >uer "o re"urn 'our ro+s. The &alue !s also used !n "he oci$/ind$arra#$/#$name%&
call so "he ou"pu" arra )r !s correc"l s!1ed "o hold "he 'our ro+s re"urned. The &alue 20 !s "he
+!d"h o' "he da"abase column. %n lo+er &alue could resul" !n shor"er s"r!ngs be!ng re"urned
"o PHP.
Script 46' array*etch"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)numelems * D!
)s * oci$parse%)c+ "/egin m#pkg.m#selproc%:p1+ :n&! end!"&!
oci_bind_arra,_b,_na-e%)s+ ":p1"+ )r+ )numelems+ 20+ 7SK:$4>B&!
oci$/ind$/#$name%)s+ ":n"+ )numelems&!
oci$e.ecute%)s&!
Car$dump%)r&! // print the arra#
?
The ou"pu" !s)
arra#%D& (
90<*
string%@& "a/c"
91<*
&2+
Bsing !L/#;L With .C'1
string%@& "de'"
92<*
string%@& "ghi"
9@<*
string%@& "Wkl"
=
% number o' o"her Oracle "pes can be bound +!"h oci$arra#$/ind$/#$name%&, 'or e/ample
4B.TN2.T 'or 'loa"!ng po!n" numbers.
There are more e/amples o' oci$/ind$arra#$/#$name%& !n "he au"oma"ed OC:$ "es"s
bundled +!"h "he PHP source code, see ext;oci/;tests.
P'2S&' Succe!! With In*or1ation Warning!
% common P.<4B. error +hen crea"!ng pac(ages, procedures or "r!ggers !s Warning'
oci=executeNO' O-.=S#--ESS=W.)H=.2(O' O:A325655' success ,ith co+pilation error" Th!s
message !s mos" l!(el "o be seen dur!ng de&elopmen" o' P.<4B. +h!ch !s commonl done !n
4B.SPlus or 4B. De&eloper. :" can also be seen dur!ng appl!ca"!on !ns"alla"!on !' P.<4B.
pac(ages, procedures or 'unc"!ons ha&e an unresol&ed dependenc.
PHP code "o chec( 'or !n'orma"!onal errors and +arn!ngs !s sho+n !n "he e/ample
plsDlerr"php. :" crea"es a procedure re'erenc!ng a non?e/!s"en" "able and "hen >uer!es "he
U4;RN;RROR4 "able a'"er "he OR%?2JIJJ error occurs)
Script 45' plsDlerr"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
ini$set%0displa#$errors0+ 'alse&! // do not automaticall# show E>E errors
// EK/7SK statement with deli/erate error: not$m#ta/ does not e.ist
)pls"l * "create or replace procedure
m#proc%d$p in Carchar2+ i$p in num/er& as
/egin
insert into not$m#ta/ %m#data+ m#id& Calues %d$p+ i$p&!
end!"!
)s * oci$parse%)c+ )pls"l&!
)r * Ooci$e.ecute%)s&!
i' %8)r& (
)m * oci$error%)s&!
i' %)m90code0< ** 2D@DD& ( // 6 EK/7SK "success with compilation error"
echo "?arning is " . )m90message0< . "2n"!
showcompilationerrors%)c&!
= else ( // 6 normal 7SK-st#le error
echo "-rror is " . )m90message0< . "2n"!
=
=
// Lispla# EK/7SK errors
'unction showcompilationerrors%)c&
&2-
!L/#;L #uccess With 'nAormation Warnings
(
)s * oci$parse%)c+ "7-K-4: M6N- [[ 0: 0 [[ 6::B5IR:-
[[ 0 at character 0 [[ E375:53M
[[ 0 o' line 0 [[ K5M- [[ 0 - 0 [[ :-,:
AB3N R7-B$-BB3B7
3BL-B I; M6N-+K5M-+E375:53M+6::B5IR:-+N-776Y-$MRNI-B"&!
oci$e.ecute%)s&!
print "<pre2n"!
while %)row * oci$'etch$arra#%)s+ 345$67734H345$B-:RBM$MRKK7&& (
'oreach %)row as )item& (
print %)item?htmlentities%)item&:""&!
=
print "2n"!
=
print "</pre"!
=
?
Th!s d!splas)
?arning is 3B6-2D@DD: success with compilation error
N;EB34: -BB3B at character 1@ o' line D - EK/7SK: 7SK 7tatement ignored
N;EB34: -BB3B at character 25 o' line D - EK/7SK: 3B6-009D2: ta/le or Ciew does
not e.ist
.oo(!ng a" "he P.<4B. code crea"!ng "he procedure, charac"er 1I on l!ne J o' "he P.<4B. code
!s "he 5M7-B: s"a"emen". Charac"er 2H !s "he "able name 7OTNMMT%-.
Mour ou"pu" ma also !nclude errors 'rom crea"!ng earl!er bloc(s. Mou can !nser" a ?>-B-
clause be'ore "he 3BL-B I; "o res"r!c" "he error messages)
where name * 0N;EB340
0!ing :E9 C0:SO:S *or :e!ult Set!
R;2 CUR4OR4 le" ou re"urn a se" o' >uer resul"s "o PHP ? "h!n( o' "hem l!(e a po!n"er "o
resul"s. :n PHP ou b!nd an OC:N-NCUR4OR &ar!able "o a P.<4B. R;2 CUR4OR procedure
parame"er and re"r!e&e "he ro+s o' "he resul" se" !n a normal 'e"ch loop.
%s an e/ample, +e crea"e a P.<4B. pac(age +!"h a procedure "ha" >uer!es "he ;MP.OM;;4
"able. The procedure re"urns a R;2 CUR4OR con"a!n!ng "he emploeesK las" names.
The P.<4B. procedure con"a!ns "he code)
Script 44' re*cur&"sDl
create or replace procedure m#proc%p1 out s#s$re'cursor& as
/egin
open p1 'or select last$name 'rom emplo#ees where rownum <* 5!
end!
/
show errors
:n PHP "he oci$new$cursor%& 'unc"!on re"urns a R;2 CUR4OR resource. Th!s !s bound "o :rc !n
"he call "o m#proc%&. The b!nd s!1e o' ?1 means D!gnore "he s!1e passedE. :" !s used because
&20
Bsing !L/#;L With .C'1
"he s!1e o' "he R;2 CUR4OR !s '!/ed b Oracle. Once "he P.<4B. procedure has comple"ed
"hen "he &alue !n )re'cur !s "rea"ed l!(e a prepared s"a"emen" !den"!'!er. :" !s s!mpl e/ecu"ed
and used !n a 'e"ch loop l!(e a normal >uer.
Script 49' re*cur&"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
// -.cute the call to the EK/7SK stored procedure
)s * oci$parse%)c+ "call m#proc%:rc&"&!
$re2c!r ; oci_new_c!rsor($c)4
oci$/ind$/#$name%$s 07rc0+ $re2c!r <1 &CI_:_C=8S&8&!
oci$e.ecute%)s&!
// -.ecute and 'etch 'rom the cursor
oci_exec!te($re2c!r)4 // treat the returned cursor as an 3458 statement resource
echo "<ta/le /order*0102n"!
while%)row * oci$'etch$arra#%$re2c!r+ 345$67734&& (
echo "<tr"!
'oreach %)row as )item& (
echo "<td". htmlentities%)item& . "</td"!
=
echo "</tr2n"!
=
echo "</ta/le2n"!
?
The ou"pu" !s)
6/el
6nde
6tkinson
6ustin
Iaer
Th!s ne/" e/ample uses a user?de'!ned "pe 'or "he R;2 CUR4OR, ma(!ng "he cursor Ds"rongl
"pedE. The "pe !s declared !n a pac(age spec!'!ca"!on.
Script 4?' re*cur2"sDl
create or replace package emp$pack as

t#pe contact$in'o$t#pe is record %
'name emplo#ees.'irst$nameFt#pe+
lname emplo#ees.last$nameFt#pe+
phone emplo#ees.phone$num/erFt#pe+
email emplo#ees.emailFt#pe&!

t#pe contact$in'o$cur$t#pe is re' cursor return contact$in'o$t#pe!
procedure get$contact$in'o%
&21
Bsing R48 CBR#.R# Aor Result #ets
p$emp$id in num/er+
p$contact$in'o out contact$in'o$cur$t#pe&!
end emp$pack!
/
show errors
create or replace package /od# emp$pack as
procedure get$contact$in'o%
p$emp$id in num/er+
p$contact$in'o out contact$in'o$cur$t#pe& as
/egin
open p$contact$in'o 'or
select 'irst$name+ last$name+ phone$num/er+ email
'rom emplo#ees
where emplo#ee$id * p$emp$id!
end!
end emp$pack!
/
show errors
The PHP code !s &er s!m!lar "o re*cur&"php, e/cep" !n "he call "o "he procedure. The
procedure name has changed and, 'or "h!s e/ample, an e/ample emploee !den"!'!er o' 1$$ !s
used.
. . .
)s * oci$parse%)c+ "call e-p_pac0.get_contact_in2o(1>> 7rc)"&!
. . .
The ou"pu" +ould be "he record 'or emploee 1$$. The 'our &alues ma"ch "he
CO7T%CTN:72ONTMP;)
Gell# 4hung P50.505.18UP G4>RMY
% P.<4B. 'unc"!on "ha" re"urns a R;2 CUR4OR can be called !n an anonmous bloc( l!(e used
pre&!ousl, or be used as a >uer column. 2or e/ample)
create or replace 'unction selectme%eid$p num/er& return s#s$re'cursor is
rc$l s#s$re'cursor!
/egin
open rc$l 'or
select 'irst$name+ last$name 'rom emplo#ees where emplo#ee$id * eid$p!
return rc$l!
end!
/
Th!s can be called !n PHP +!"h a >uer l!(e)
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "select selectme%:eid& as rc 'rom dual"&!
)eid * 101!
&22
Bsing !L/#;L With .C'1
oci$/ind$/#$name%)s+ ":eid"+ )eid&!
oci$e.ecute%)s&!
)r * oci$'etch$arra#%)s&!
)re'cur * )r90B40<!
oci$e.ecute%)re'cur&!
oci$'etch$all%)re'cur+ )res&!
Car$dump%)res&!
?
Clo!ing Cur!or!
To a&o!d runn!ng ou" o' Oracle cursors C+h!ch ha&e a da"abase?con'!gured, per?sess!on l!m!"
open=cursors se" b "he D-%F, ma(e sure "o e/pl!c!"l 'ree cursors. The e/ample !n
re*cur6"php !s a scr!p" "ha" !mpl!c!"l crea"es cursors.
Script 4/' re*cur6"php
<?php
// 4reate a ta/le with D00 rows
'unction initialiXe%)c&
(
)stmtarra# * arra#%"drop ta/le m#ta/"+
"create ta/le m#ta/%col1 Carchar2%1&&"&!
'oreach %)stmtarra# as )stmt& (
)s * oci$parse%)c+ )stmt&!
Ooci$e.ecute%)s&!
=
)s * oci$parse%)c+ "insert into m#ta/ Calues %060&"&!
'or %)i * 0! )i < D00! HH)i& (
oci$e.ecute%)s&!
=
=
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
initialiXe%)c&!
)s * oci$parse%)c+ 0select cursor%select J 'rom dual& 'rom m#ta/0&!
oci$e.ecute%)s&!
while %)re'cur * oci$'etch$arra#%)s+ 345$MRN&& ( // get each B-A 4RB73B
oci$e.ecute%)re'cur90<&! // e.ecute the B-A 4RB73B
while %)row * oci$'etch$arra#%)re'cur90<+ 345$MRN&& (
'oreach %)row as )item&
echo ")item "!
echo "2n"!
=
oci$'ree$statement%)re'cur90<&! // 'ree the re' cursor
=
(33
Bsing R48 CBR#.R# Aor Result #ets
?
The ou"er selec" 'rom MMT%- re"urns no" ro+s, bu" a CUR4OR per ro+ o' MMT%-. Those cursors
each represen" "he resul" 'rom "he !nner >uer. Tha" !s, "here are J00 >uer!es 'rom "he DU%.
"able. The ou"er 0H:.; loop 'e"ches each o' "he J00 R;2 CUR4ORs !n "urn. The !nner 0H:.;
loop 'e"ches *ro+ each R;2 CUR4OR. The resul" !s a s"ream o' =As C+h!ch !s "he s!ngle ro+ o'
da"a !n DU%.F be!ng d!splaed)
,
,
,
. . .
Th!s scr!p" +or(s, bu" !' "he oci$'ree$statement%& l!ne !s commen"ed ou")
// oci$'ree$statement%)re'cur90<&! // 'ree the re' cursor
"hen "he scr!p" can reach "he da"abase l!m!" on "he number o' cursors. %'"er some !"era"!ons
"hrough "he loop, an error !s d!splaed)
E>E ?arning:oci$'etch$arra#%&: 3B6-00P0D: error occurred at recursiCe 7SK leCel 1
3B6-01000: ma.imum open cursors e.ceeded
The number o' !"era"!ons be'ore ge""!ng "he messages depends on "he da"abase con'!gura"!on
parame"er open=cursors.
Pre*etching 9ro1 :E9 C0:SO:S and Ne!ted Cur!or! *or Per*or1ance
Pre'e"ch!ng o' ro+s 'rom R;2 CUR4OR4 !s suppor"ed 'rom Oracle Da"abase 11gR2 on+ards.
Pre'e"ch!ng !s also per'ormed +hen connec"ed "o pre&!ous da"abase &ers!ons as long as PHP
OC:$ !s us!ng &ers!on 11.2 Oracle cl!en" l!brar!es. Ta(!ng ad&an"age o' "he be""er per'ormance
can be as s!mple as rel!n(!ng PHP +!"h "he la"es" l!brar!es. The &alue o' oci/"de*ault=pre*etch
!s used 'or pre'e"ch!ng R;2 CUR4OR4, or "he &alue can be changed a" run"!me)
)s * oci$parse%)c+ "call m#proc%:rc&"&!
)re'cur * oci$new$cursor%)c&!
oci$/ind$/#$name%)s+ 0:rc0+ )re'cur+ -1+ 345$I$4RB73B&!
oci$e.ecute%)s&!
oci_set_pre2etch($re2c!r 3$$)4
oci$e.ecute%)re'cur&!
oci$'etch$all%)re'cur+ )res&!
4e""!ng "he pre'e"ch coun" on "he @paren"@ resource )s does no" change "he pre'e"ch s!1e 'or
)re'cur.
:' our scr!p" re"r!e&es a R;2 CUR4OR, 'e"ches a 'e+ records 'rom !", and "hen passes "he
R;2 CUR4OR bac( "o "he da"abase +here a s"ored procedure con"!nues 'e"ch!ng records 'rom
!", ou should se" "he pre'e"ch s!1e "o 0. O"her+!se "he pre'e"ch bu''er o' records sen" "o PHP
m!gh" no" be comple"el consumed b PHP oci$'etch$J calls, and "hose e/"ra ro+s +ould no"
be a&a!lable "o "he second P.<4B. s"ored procedure. Th!s +ould g!&e "he appearance o'
m!ss!ng da"a, +h!ch +asnA" processed b "he PHP appl!ca"!on or "he s"ored procedure.
(3&
Bsing !L/#;L With .C'1
Con-erting *ro1 :E9 C0:SO: to PIPE'INE# :e!ult!
:' ou are us!ng an older &ers!on o' Oracle cl!en" l!brar!es and canno" use R;2 CUR4OR
pre'e"ch!ng, e&alua"e al"erna"!&es such as do!ng d!rec" >uer!es, +r!"!ng a +rapp!ng 'unc"!on !n
P.<4B. "ha" has "pes "ha" can be bound +!"h oci$/ind$arra#$/#$name%&, or +r!"!ng a
+rapp!ng 'unc"!on "ha" p!pel!nes "he ou"pu". % p!pel!ned P.<4B. 'unc"!on g!&es "he ab!l!" "o
selec" 'rom "he 'unc"!on as !' !" +ere a "able.
To con&er" "he m#proc%& procedure 'rom re*cur&"sDl "o re"urn p!pel!ned da"a, crea"e a
pac(age)
Script 48' rc2pipeline"sDl
create or replace package m#plmap as
t#pe outt#pe is record % -- structure o' the re' cursor in m#proc
last$name Carchar2%25&
&!
t#pe outt#pe$set is ta/le o' outt#pe!
'unction maprctopl return outt#pe$set pipelined!
end!
/
show errors
create or replace package /od# m#plmap as
'unction maprctopl return outt#pe$set pipelined is
outrow outt#pe$set!
p$rc s#s$re'cursor!
/atchsiXe pls$integer :* 20! -- 'etch /atches o' 20 rows at a time
/egin
m#proc%p$rc&! -- call the original procedure
loop
'etch p$rc /ulk collect into outrow limit /atchsiXe!
'or i in 1 .. outrow.count%& loop
pipe row %outrow%i&&!
end loop!
e.it when outrow.count < /atchsiXe!
end loop!
end maprctopl!
end m#plmap!
/
show errors
Th!s calls m#proc%& and p!pes each record. :" can be called !n PHP us!ng a s!mple >uer +!"h
"he ta/le opera"or)
Script 9A' rc2pipeline"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "select J 'rom tab"e%m#plmap.maprctopl%&&"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
(3(
Bsing R48 CBR#.R# Aor Result #ets
?
:' "he R;2 CUR4OR >uer !n m#proc%& selec"ed all columns, "hen OUTTMP;N4;T could s!mpl
ha&e been declared !n "he 4B. scr!p" as)
t#pe outt#pe$set is ta/le o' emplo#eesFrowt#pe!
Oracle Collection! in PHP
Man programm!ng "echn!>ues use collec"!on "pes such as arras, bags, l!s"s, nes"ed "ables,
se"s, and "rees. To suppor" "hese "echn!>ues !n da"abase appl!ca"!ons, P.<4B. pro&!des "he
da"a "pes T%-.; and ,%RR%M, +h!ch allo+ ou "o declare !nde/?b "ables, nes"ed "ables, and
&ar!able?s!1e arras.
%n Oracle collec"!on !s an ordered group o' elemen"s, all o' "he same "pe. ;ach elemen"
has a un!>ue subscr!p" "ha" de"erm!nes !"s pos!"!on !n "he collec"!on. Collec"!ons +or( l!(e "he
arras 'ound !n mos" "h!rd?genera"!on programm!ng languages. %lso, collec"!ons can be
passed as parame"ers. 4o, ou can use "hem "o mo&e columns o' da"a !n"o and ou" o'
da"abase "ables or be"+een cl!en"?s!de appl!ca"!ons and s"ored subprograms.
Oracle collec"!ons can be man!pula"ed !n PHP b me"hods on a collec"!on resource, +h!ch
!s alloca"ed +!"h oci$new$collection%&.
:n a s!mple ema!l address boo( e/ample, "+o ,%RR%Ms are crea"ed, one 'or an arra o'
peopleKs names, and one 'or an arra o' ema!l addresses. ,%RR%Ms Cshor" 'or &ar!able?s!1e
arrasF use se>uen"!al numbers as subscr!p"s "o access a '!/ed number o' elemen"s.
Script 9&' addressboo1"sDl
drop ta/le emails!
create ta/le emails %
user$id Carchar2%10&+
'riend$name Carchar2%20&+
email$address Carchar2%20&&!
create or replace t#pe email$arra# as Carra#%100& o' Carchar2%20&!
/
show errors
create or replace t#pe 'riend$arra# as Carra#%100& o' Carchar2%20&!
/
show errors
create or replace procedure update$address$/ook%
p$user$id in Carchar2+
p$'riend$name 'riend$arra#+
p$email$addresses email$arra#&
is
/egin
delete 'rom emails where user$id * p$user$id!
'orall i in indices o' p$email$addresses
insert into emails %user$id+ 'riend$name+ email$address&
Calues %p$user$id+ p$'riend$name%i&+ p$email$addresses%i&&!
(3)
Bsing !L/#;L With .C'1
end update$address$/ook!
/
show errors
The update$address$/ook%& procedure loops o&er all elemen"s o' "he address collec"!on and
!nser"s each one and !"s ma"ch!ng name.
The updateaddresses"php code crea"es a collec"!on o' names and a collec"!on o' ema!l
addresses us!ng "he append%& me"hod "o add elemen"s "o each arra. These collec"!ons are
bound as OC:N-N7TM CDnamed "peEF "o "he argumen"s o' "he P.<4B. address$/ook%& call.
The s!1e ?1 !s used because Oracle !n"ernall (no+s "he s!1e o' "he "pe. 0hen
address$/ook%& !s e/ecu"ed, "he names and ema!l addresses are !nser"ed !n"o "he da"abase.
Script 92' updateaddresses"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)user$name * 0cWones0!
)'riends$names * arra#%0alison0+ 0aslam0&!
)'riends$emails * arra#%0alisonOe.ample.com0+ 0aslamOe.ample.com0&!
)'riend$coll * oci_new_co""ection%)c+ 0AB5-ML$6BB6;0&!
)email$coll * oci_new_co""ection%)c+ 0-N65K$6BB6;0&!
'or %)i * 0! )i < count%)'riends$names&! HH)i& (
$2riend_co""<?append%)'riends$names9)i<&!
$e-ai"_co""<?append()'riends$emails9)i<&!
=
)s * oci$parse%)c+ "/egin update$address$/ook%:un+ :'riends+ :emails&! end!"&!
oci$/ind$/#$name%)s+ 0:un0+ )user$name&!
oci$/ind$/#$name%)s+ 0:'riends0+ )'riend$coll+ -1+ 345$I$M:;&!
oci$/ind$/#$name%)s+ 0:emails0+ )email$coll+ -1+ 345$I$M:;&!
oci$e.ecute%)s&!
?
The ;M%:.4 "able no+ has "he !nser"ed da"a)
7SK select J 'rom emails!
R7-B$5L AB5-ML$M6N- -N65K$6LLB-77
---------- -------------------- --------------------
cWones alison alisonOe.ample.com
cWones aslam aslamOe.ample.com
O"her OC:$ collec"!on me"hods allo+ access!ng or cop!ng da"a !n a collec"!on. 4ee "he PHP
OC:$ manual 'or more !n'orma"!on.
(3*
Bsing !L/#;L and .racle .5=ect Types in !H!
0!ing P'2S&' and Oracle O$3ect T6pe! in PHP
4ome"!me ou ha&e "o +or( +!"h Oracle ob8ec" "pes or call P.<4B. procedures "ha" are
des!gned 'or !n"erac"!ng +!"h o"her P.<4B. code and "ha" canno" be used d!rec"l +!"h OC:$.
Pre&!ous sec"!ons ha&e !n"roduced some me"hods. Th!s sec"!on g!&es more e/amples. :" !s a
br!e' gu!de, and no" e/haus"!&e. %lso, some "echn!>ues +!ll +or( be""er !n some s!"ua"!ons
"han !n o"hers.
The '!rs" e/ample s!mula"es "he Oracle Te/" CT=NTH;4 pac(age procedures. These re"urn
Oracle ob8ec" "pes. COracle Te/" !s a da"abase componen" "ha" uses s"andard 4B. "o !nde/,
search, and anal1e "e/" and documen"s s"ored !n "he da"abase, !n '!les, and on "he +eb. :"
can per'orm l!ngu!s"!c anals!s on documen"s, as +ell as search "e/" us!ng a &ar!e" o'
s"ra"eg!es !nclud!ng (e+ord search!ng and con"e/" >uer!esF.
Th!s e/ample, ctx"sDl, se"s up an e/ample pac(age +!"h a s!m!lar !n"er'ace "o CT=NTH;4.
Here !" 8us" re"urns random da"a !n "he OUT parame"er)
Script 96' ctx"sDl
-- Eackage "7uppliedEkg" simulates 3racle :e.t0s 4:,$:>-7.
-- 5t has a procedure that returns a EK/7SK t#pe.
create or replace package 7uppliedEkg as
t#pe 7uppliedBec is record %
id num/er+
data Carchar2%100&
&!
t#pe 7upplied:a/:#pe is ta/le o' 7uppliedBec inde. /# /inar#$integer!
procedure 7uppliedEroc%p$p in out nocop# 7upplied:a/:#pe&!
end 7uppliedEkg!
/
show errors
create or replace package /od# 7uppliedEkg as
procedure 7uppliedEroc%p$p in out nocop# 7upplied:a/:#pe& is
/egin
-- 4reate some random data
p$p.delete!
'or i in 1..5 loop
p$p%i&.id :* i!
p$p%i&.data :* 0Bandom: 0 [[ i [[ %1H6I7%N3L%d/ms$random.random+100000&&&!
end loop!
end 7uppliedEroc!
end 7uppliedEkg!
/
show errors
Run "he '!le ctx"sDl !n 4B.SPlus)
) s"lplus hr/welcomeOlocalhost/,- Oct..s"l
Th!s !s "he D'!/edE par" o' "he problem, represen"!ng "he unchangeable, pre?suppl!ed
'unc"!onal!" ou need "o +or( +!"h. The ne/" 'our sec"!ons sho+ d!''eren" "echn!>ues 'or
'e"ch!ng da"a 'rom 7uppliedEroc%&.
(3+
Bsing !L/#;L With .C'1
0!ing a PIPE'INE# 9unction
% P.<4B. +rapper 'unc"!on us!ng P:P; can be used "o 'e"ch "he &alues re"urned b
7uppliedEroc%&)
Script 95' +yplp1g"sDl
create or replace package m#plpkg as
t#pe plta/ is ta/le o' 7uppliedEkg.7uppliedBec!
'unction m#wrapper1 return plta/ pipelined!
end!
/
show errors
create or replace package /od# m#plpkg as
'unction m#wrapper1 return plta/ pipelined is
origdata 7uppliedEkg.7upplied:a/:#pe!
/egin
7uppliedEkg.7uppliedEroc%origdata&!
'or i in 1..origdata.count loop
pipe row %origdata%i&&!
end loop!
end m#wrapper1!
end m#plpkg!
/
show errors
The PHP code "o call "he +rapper !s)
Script 94' +yplp1g"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "select J 'rom ta/le%m#plpkg.m#wrapper1%&&"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
?
The ou"pu" !s l!(e'
arra#%2& (
9"5L"<*
arra#%5& (
90<*
string%1& "1"
91<*
string%1& "2"
92<*
string%1& "@"
9@<*
string%1& "D"
(3-
Bsing !L/#;L and .racle .5=ect Types in !H!
9D<*
string%1& "5"
=
9"L6:6"<*
arra#%5& (
90<*
string%1D& "Bandom: 1UD852"
91<*
string%1D& "Bandom: 210905"
92<*
string%1D& "Bandom: @D10@2"
9@<*
string%1@& "Bandom: D15@0"
9D<*
string%1D& "Bandom: 5D0@88"
=
=
0!ing a :E9 C0:SO:
4!nce da"a 'rom MMP.P63.MM0R%PP;R1 !s 'e"ched +!"h a >uer, ou could also eas!l re"urn
"he &alues "o PHP us!ng a R;2 CUR4OR, !' "h!s !s our pre'erred cod!ng s"le)
Script 99' +yrcp1g"sDl
create or replace package m#rcpkg as
procedure m#wrapper2 %p$rc out s#s$re'cursor&!
end!
/
show errors
create or replace package /od# m#rcpkg as
procedure m#wrapper2 %p$rc out s#s$re'cursor& is
/egin
open p$rc 'or select J 'rom ta/le%m#plpkg.m#wrapper1%&&!
end m#wrapper2!
end m#rcpkg!
/
show errors
Th!s can be called !n PHP l!(e)
Script 9?' +yrcp1g"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "/egin m#rcpkg.m#wrapper2%:m#rc&! end!"&!
)rc * oci$new$cursor%)c&!
oci$/ind$/#$name%)s+ 0:m#rc0+ )rc+ -1+ 345$I$4RB73B&!
oci$e.ecute%)s&!
oci$e.ecute%)rc&!
oci$'etch$all%)rc+ )res&!
(30
Bsing !L/#;L With .C'1
Car$dump%)res&!
?
The ou"pu" !s "he same as 'rom +yrcp1g"php.
0!ing an ,rra6 )ind
% "h!rd solu"!on le"s ou use "he 'as" oci$/ind$arra#$/#$name%& 'unc"!on. The +rapper
procedure loo(s l!(e)
Script 9/' +ybap1g"sDl
create or replace package m#/apkg as
procedure m#wrapper@ %
p$id out d/ms$s"l.num/er$ta/le+
p$data out d/ms$s"l.Carchar2$ta/le&!
end!
/
show errors
create or replace package /od# m#/apkg as
procedure m#wrapper@%
p$id out d/ms$s"l.num/er$ta/le+
p$data out d/ms$s"l.Carchar2$ta/le& as
/egin
select id+ data
/ulk collect into p$id+ p$data
'rom h.unta/ta/le%m#plpkg.m#wrapper1%&&!
end m#wrapper@!
end m#/apkg!
/
show errors
Th!s can be called 'rom PHP +!"h)
Script 98' +ybap1g"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "/egin m#/apkg.m#wrapper@%:m#id+ :m#data&! end!"&!
oci$/ind$arra#$/#$name%)s+ ":m#id"+ )m#id+ 10+ -1+ 7SK:$5M:&!
oci$/ind$arra#$/#$name%)s+ ":m#data"+ )m#data+ 10+ 20+ 7SK:$4>B&!
oci$e.ecute%)s&!
Car$dump%)m#id&!
Car$dump%)m#data&!
?
Th!s "echn!>ue can be used +hen "he number o' !"ems "o re"urn !s (no+n. The ou"pu" !s
s!m!lar "o)
(31
Bsing !L/#;L and .racle .5=ect Types in !H!
arra#%5& (
90< *
int%1&
91< *
int%2&
92< *
int%@&
9@< *
int%D&
9D< *
int%5&
=
arra#%5& (
90< *
string%1D& "Bandom: 11@D5@"
91< *
string%1D& "Bandom: 298@8U"
92< *
string%1D& "Bandom: @U5UPU"
9@< *
string%1D& "Bandom: D50@52"
9D< *
string%1D& "Bandom: 599520"
=
0!ing OCI. Collection 9unction!
The 7uppliedEroc%& procedure can also be called us!ng OC:$ collec"!on 'unc"!ons b crea"!ng
e" ano"her a +rapper 'unc"!on !n P.<4B. "o con&er" "he P.<4B. "pe 7upplied:a/:#pe "o a
pa!r o' 4B. "pes)
Script ?A' +yclp1g"sDl
create or replace t#pe N#5dBec as ta/le o' num/er!
/
show errors
create or replace t#pe N#LataBec as ta/le o' Carchar2%100&!
/
show errors
create or replace package m#clpkg as
procedure wrapperD %p$id in out N#5dBec+ p$data in out N#LataBec&!
end!
/
show errors
create or replace package /od# m#clpkg as
procedure wrapperD %p$id in out N#5dBec+ p$data in out N#LataBec&
as
/egin
select id+ data
/ulk collect into p$id+ p$data
(32
Bsing !L/#;L With .C'1
'rom ta/le%m#plpkg.m#wrapper1%&&!
end wrapperD!
end m#clpkg!
/
show errors
7o+ ou can call wrapperD%& !n PHP)
Script ?&' +yclp1g"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ 0/egin m#clpkg.wrapperD%:res$id+ :res$data&! end!0&!
)res$id * oci$new$collection%)c+ 0N;5LB-40&!
)res$data * oci$new$collection%)c+ 0N;L6:6B-40&!
oci$/ind$/#$name%)s+ 0:res$id0+ )res$id+ -1+ 345$I$M:;&!
oci$/ind$/#$name%)s+ 0:res$data0+ )res$data+ -1+ 345$I$M:;&!
oci$e.ecute%)s&!
'or %)i * 0! )i < )res$id-siXe%&! )iHH& (
)id * )res$id-get-lem%)i&!
)data * )res$data-get-lem%)i&!
echo "5d: )id+ Lata: )data2n"!
=
?
Th!s alloca"es "+o collec"!ons and b!nds "hem as "he parame"ers "o wrapperD%&. %'"er
wrapperD%& has been called, "he PHP OC:$ collec"!on me"hod get-lem%& !s used "o access
each &alue re"urned. The ou"pu" !s s!m!lar "o)
5d: 1+ Lata: Bandom: 1559D2
5d: 2+ Lata: Bandom: 2DUU8@
5d: @+ Lata: Bandom: @P555@
5d: D+ Lata: Bandom: D8U55@
5d: 5+ Lata: Bandom: 5898U9
Th!s sec"!on has sho+n 'our me"hods o' 'e"ch!ng P.<4B. "pes. The bes" me"hod +!ll depend
on personal pre'erence, da"a s!1e and per'ormance !n our en&!ronmen".
Getting Output With #)5SAO0TP0T
The D-M4NOUTPUT pac(age !s "he s"andard +a "o Dpr!n"E ou"pu" 'rom P.<4B.. The dra+bac(
!s "ha" !" !s no" asnchronous. The P.<4B. procedure or bloc( "ha" calls D-M4NOUTPUT runs "o
comple"!on be'ore an ou"pu" !s re"urned "o "he user.
D-M4NOUTPUT !s l!(e a bu''er. Mour PHP code "urns on D-M4NOUTPUT bu''er!ng, calls some
P.<4B. code "ha" pu"s ou"pu" !n "he bu''er, and "hen la"er 'e"ches 'rom "he bu''er. O"her
da"abase connec"!ons canno" access our bu''er.
% bas!c +a "o 'e"ch D-M4NOUTPUT !n PHP !s "o b!nd an ou"pu" s"r!ng "o "he P.<4B.
d/ms$output.get$line%& procedure)
)s * oci$parse%)c+ "/egin d/ms$output.get$line%:ln+ :st&! end!"&!
(&3
,etting .utput With D>:#C.BT!BT
oci$/ind$/#$name%)s+ ":ln"+ )ln+ 255&! // output line
oci$/ind$/#$name%)s+ ":st"+ )st+ -1+ 7SK:$5M:&! // status: 1 means no more lines
while %%)succ * oci$e.ecute%)s&& ^^ 8)st& (
echo ")ln2n"!
=
The &ar!able :ln !s arb!"rar!l bound as leng"h 2HH. Th!s +as "he D-M4NOUTPUT l!ne s!1e l!m!"
pr!or "o Oracle Da"abase 10g Release 10.2, +hen !" +as "hen changed "o I26-. CThe l!m!"a"!on
on "he number o' l!nes +as also ra!sedF. %&o!d b!nd!ng I26-, espec!all !' "he da"abase !s
runn!ng !n OracleKs shared ser&er mode. :' ou b!nd "h!s s!1e, "hen !" !s eas "o slo+ do+n
per'ormance or ge" memor errors. Ho+e&er, !' ou b!nd less "han "he 'ull s!1e, ma(e sure
our appl!ca"!on does no" pr!n" +!der l!nes.
%l"erna"!&el, ou can use oci$/ind$arra#$/#$name%& and call ano"her D-M4NOUTPUT
pac(age "ha" re"urns mul"!ple l!nes, get$lines%&. The per'ormance o' "h!s !s generall be""er
bu" !" does depend on ho+ b!g "he b!nd arra !s, ho+ much da"a !s re"urned and ho+ "he code
!s s"ruc"ured. :n "he +ors" case !" m!gh" be slo+er "han "he s!mple code, so benchmar( our
appl!ca"!on care'ull.
% more cons!s"en" and 'as" D-M4NOUTPUT 'e"ch!ng !mplemen"a"!on uses a cus"om
p!pel!ned P.<4B. 'unc"!on. :n 4B.SPlus crea"e "he 'unc"!on)
Script ?2' db+soutput"sDl
create or replace t#pe dorow as ta/le o' Carchar2%D000&!
/
show errors
create or replace 'unction m#do'etch return dorow pipe"ined is
line Carchar2%D000&!
status integer!
/egin
loop
d/ms$output.get$line%line+ status&!
e.it when status * 1!
pipe row ("ine)!
end loop!
return!
end!
/
show errors
-ecause +e +!ll 'e"ch "he da"a !n a >uer as a 4B. s"r!ng, "he ma/!mum leng"h !s J000 b"es.
% 'unc"!on "o "urn on ou"pu" bu''er!ng !s sho+n !n db+soutput"inc"php along +!"h
getd/msoutput%& +h!ch re"urns an arra o' "he ou"pu" l!nes)
Script ?6' db+soutput"inc"php
<?php
// :urn LIN7$3R:ER: on
'unction ena/led/msoutput%)c&
(
)s * oci$parse%)c+ "/egin d/ms$output.ena/le%null&! end!"&!
)r * oci$e.ecute%)s&!
return )r!
(&&
Bsing !L/#;L With .C'1
=
// Beturns an arra# o' LIN7$3R:ER: lines
'unction getd/msoutput%)c&
(
)res * 'alse!
)s * oci$parse%)c+ "select J 'rom ta/le%m#do'etch%&&"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
return )res9043KRNM$Z6KR-0<!
=
?
Th!s has "he arb"r!"rar '!le e/"ens!on D"inc"phpS '!le "o !nd!ca"e !" +!ll be !ncluded !n o"her PHP
scr!p"s.
The ne/" scr!p" uses "hese 'unc"!ons "o sho+ Dpr!n"!ngE ou"pu" 'rom P.<4B. bloc(s)
Script ?5' db+soutput"php
<?php
include%"d/msoutput.inc.php"&!
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
// :urn output /u''ering on
ena/led/msoutput%)c&!
// 4reate some output
)s * oci$parse%)c+ "call d/ms$output.put$line%0>ello+ world80&"&!
oci$e.ecute%)s&!
// 4reate more output
// 6n# EK/7SK code /eing run can insert into the output /u''er
)s * oci$parse%)c+ "/egin
d/ms$output.put$line%0>ello again0&!
d/ms$output.put$line%0>ello 'inall#0&!
end!"&!
oci$e.ecute%)s&!
// Lispla# the output
)output * getd/msoutput%)c&!
i' %)output& (
'oreach %)output as )line& (
echo ")line</r2n"!
=
=
?
The ou"pu" !s all "he d/ms$output.put$line%& "e/")
>ello+ world8
>ello again
(&(
,etting .utput With D>:#C.BT!BT
>ello 'inall#
:' ou e/pec" large amoun"s o' ou"pu", ou ma +an" "o s"ream resul"s as "he are 'e"ched
'rom "he da"abase !ns"ead o' re"urn!ng "hem !n one arra 'rom getd/msoutput%&.
:' D-M4NOUTPUT does no" su!" our appl!ca"!on, ou can also ge" ou"pu" 'rom P.<4B. b
logg!ng !" "o da"abase "ables or b us!ng pac(ages l!(e UT.N2:.; and D-M4NP:P; "o
asnchronousl d!spla ou"pu" "o a separa"e "erm!nal +!ndo+.
P'2S&' )ac=trace! in a P'2S&' Eception Handler
P.<4B. has se&eral 'unc"!ons help'ul 'or problem resolu"!on +hen deal!ng +!"h e/cep"!ons.
:ns"ead o' h!d!ng errors or re"urn!ng abs"rac" messages 'rom an e/cep"!on handler ou can
re"urn "he e/ac" Oracle problem and loca"!on. :' our P.<4B. code !ncludes "hese 'unc"!ons,
our PHP appl!ca"!on can genera"e use'ul bac("races "o help debugg!ng. Remember "o log
"hese errors and no" d!spla "hem "o +eb users.
4ample 4B. code "ha" al+as genera"es and "hen ca"ches an e/cep"!on !s !n bac1trace"sDl)
Script ?4' bac1trace"sDl
create or replace procedure m#/t is
/egin
d/ms$output.put$line%05n m#/t0&!
raise no$data$'ound! // alwa#s throw an error
e.ception
when others then
d/ms$output.put$line%0Lispla#ing the error stack:0&!
d/ms$output.put%d/ms$utilit#.'ormat$error$stack&!
d/ms$output.put$line%d/ms$utilit#.'ormat$error$/acktrace&!
end!
/
PHP code "o call "h!s and 'e"ch "he ou"pu" !s !n bac1trace"php)
Script ?9' bac1trace"php
<?php
include%"d/msoutput.inc.php"&!
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
ena/led/msoutput%)c&!
)s * oci$parse%)c+ "/egin m#/t%&! end!"&!
oci$e.ecute%)s&!
// Lispla# the output
)output * getd/msoutput%)c&! // see preCious e.amples
'oreach %)output as )line&
echo ")line</r2n"!
?
Runn!ng bac1trace"php g!&es)
(&)
Bsing !L/#;L With .C'1
5n m#/t
Lispla#ing the error stack:
3B6-01D0@: no data 'ound
3B6-0P512: at ">B.N;I:"+ line D
P'2S&' 9unction :e!ult Cache
Oracle Da"abase 11g !n"roduced a cache 'or P.<4B. 'unc"!on resul"s, !deal 'or repea"ed loo(up
opera"!ons. The cache con"a!ns "he genera"ed resul"s o' pre&!ous 'unc"!on calls, 'or par"!cular
se"s o' !npu" parame"ers. :' "he 'unc"!on !s re?run +!"h "he same parame"er &alues, "he resul"
'rom "he cache !s re"urned !mmed!a"el +!"hou" need!ng "o re?e/ecu"e "he code. The cached
resul"s are a&a!lable "o an user. The cache +!ll age ou" resul"s !' more memor !s re>u!red.
There are some res"r!c"!ons !nclud!ng "ha" onl bas!c "pes can be used 'or parame"ers,
and "he mus" be :7 onl. Re"urn "pes are s!m!lar res"r!c"ed, !n par"!cular no" us!ng R;2
CUR4OR or P:P;.:7;D resul"s.
To use "he cache, a normal 'unc"!on !s crea"ed +!"h "he R;4U.TNC%CH; op"!on)
4cr!p" PP) 'rc.s>l
create or replace 'unction m#cache'unc%p$id in Carchar2& return Carchar2
res!"t_cache re"ies_on(-,tab)
as
l$data Carchar2%D0&!
/egin
select m#data into l$data 'rom m#ta/ where m#id * p$id!
return l$data!
end!
/
show errors
The relies$on%& clause !s a comma separa"ed l!s" o' "ables. :' an o' "hese "ables change,
"han "he cache !s au"oma"!call !n&al!da"ed b Oracle. The ne/" "!me "he 'unc"!on !s called, !"
+!ll e/ecu"e comple"el and upda"e "he cache appropr!a"el. 2rom Oracle Da"abase 11.2,
"ables used !n "he 'unc"!on are au"oma"!call de"ec"ed.
4ee "he Oracle Database PF;SEF Fanguage :e*erence &&g :elease 2 N&&"2O manual 'or
more de"a!ls abou" "he 'ea"ure.
0!ing Oracle 'ocator *or Spatial 5apping
Oracle .oca"or !s a subse" o' Oracle 4pa"!al, a comprehens!&e mapp!ng l!brar. Oracle .oca"or
!s po+er'ul !"sel' and !s a&a!lable !n all Oracle Da"abase ed!"!ons. % grea" !n"roduc"!on "o
Oracle .oca"or !s !n "he Oracle Database Express Edition 2 Day Plus Focator Developer Guide
&&g :elease 2.
Th!s sec"!on sho+s some "echn!>ues "o use .oca"or da"a !n PHP. Oracle .oca"or ma(es use
o' P.<4B. "pes such as collec"!ons. These can no" al+as be d!rec"l 'e"ched !n"o PHP.
The e/amples here use "he "ables sho+n !n "he abo&e men"!oned manualAs sample
scenar!o. Crea"e "he CU4TOM;R4 and 4TOR;4 "ables 'rom Exa+ple &3& SEF Script *or
-usto+ers and Stores Scenario !n 4B.SPlus be'ore con"!nu!ng. The UR. 'or "he scr!p" !s)
http://docs.oracle.com/cd/-1UU81$01/appdeC.112/e18U50/.e$locator.htmQ,-K345P
0
(&*
Bsing .racle Locator Aor #patial :apping
In!erting 'ocator #ata
:nser"!ng .oca"or da"a !n PHP !s s!mpl a ma""er o' e/ecu"!ng "he appropr!a"e 4B. 5M7-B:
s"a"emen")
)s"l * "insert into customers Calues
%100+ 060+ 0I0+
0111 Beese 6Ce0+ 04hicago0+ 05K0+ 12@D5+
7L3$Y-3N-:B;%2001+
8@0U+
7L3$E35M:$:;E-%-P9.2@1DD5+12.00125D+MRKK&+ MRKK+ MRKK&&"!
)s * oci$parse%)c+ )s"l&!
oci$e.ecute%)s&!
&uerie! :eturning Scalar <alue!
-e'ore 'e"ch!ng da"a, de"erm!ne !' "h!s !s, !n 'ac", necessar. O'"en "he da"a can be processed
!n Oracle 4B. or P.<4B. e''!c!en"l and eas!l.
Buer!es re"urn!ng scalar &alues 'rom .oca"or ob8ec"s are no d!''eren" "o o"her PHP >uer!es.
Th!s e/ample '!nds "he "hree closes" cus"omers "o "he s"ore +!"h CU4TOM;RN:D o' 101. The
>uer uses "he !n?bu!l" 4pa"!al 'unc"!on 73L$MM%& "o de"erm!ne "he nearest neighbor
rela"!onsh!p.
Script ?/' loc&"php
<?php

)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s"l * "select /JH ordered J/
c.customer$id+
c.'irst$name+
c.last$name
'rom stores s+ customers c
where s.store$id * :sid
and sdo$nn%c.cust$geo$location+ s.store$geo$location+ :nres& * 0:BR-0"!
)s * oci$parse%)c+ )s"l&!
)sid * 101!
)nres * 0sdo$num$res*@0! // return @ results
oci$/ind$/#$name%)s+ ":sid"+ )sid&!
oci$/ind$/#$name%)s+ ":nres"+ )nres&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
?
The ou"pu" !s)
arra#%@& (
9"4R7:3N-B$5L"<*
(&+
Bsing !L/#;L With .C'1
arra#%@& (
90<*
string%D& "1001"
91<*
string%D& "100@"
92<*
string%D& "100D"
=
9"A5B7:$M6N-"<*
arra#%@& (
90<*
string%9& "6le.andra"
91<*
string%P& "Narian"
92<*
string%P& ":homas"
=
9"K67:$M6N-"<*
arra#%@& (
90<*
string%U& "Michols"
91<*
string%5& "4hang"
92<*
string%8& "?illiams"
=
=
The CU4TOM;RN:D, 2:R4TN7%M; and .%4TN7%M; columns are scalar 7UM-;R and ,%RCH%R2
columns re"urned d!rec"l !n"o a PHP arra.
Selecting <ertice! 0!ing S#OA0TI'.GET<E:TICES
2or some .oca"or "pes, !n?bu!l" 'unc"!ons +!ll con&er" ob8ec"s "o scalar &alues "ha" can be
re"urned "o PHP. 2or e/ample, "o 'e"ch "he coord!na"es 'rom a geome"r 'or cus"omer 1001,
use "he !nbu!l" 7L3$R:5K.Y-:Z-B:54-7%& 'unc"!on)
Script ?8' loc2"php
<?php

)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s"l * "select t..+ t.#
'rom customers+
ta/le%sdo$util.getCertices%customers.cust$geo$location&& t
where customer$id * :cid"!
)s * oci$parse%)c+ )s"l&!
)cid * 1001!
oci$/ind$/#$name%)s+ ":cid"+ )cid&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
(&-
Bsing .racle Locator Aor #patial :apping
?
The ou"pu" !s)
arra#%2& (
9","<*
arra#%1& (
90<*
string%9& "-U1.D892@"
=
9";"<*
arra#%1& (
90<*
string%8& "D2.U2@DU"
=
=
0!ing a Cu!to1 9unction
4ome"!mes ou ma need "o crea"e a P.<4B. 'unc"!on "o decompose spa"!al da"a !n"o s!mple
"pes "o re"urn "hem "o PHP. Th!s e/ample uses "he CO.%NM%R6;T4 "able 'rom sec"!on 1.L,
#sing 2on3Point Geo+etry )ypes !n "he Focator manual'
http://docs.oracle.com/cd/E17781_01/appdev.112/e18750/xe_locator.htm#XELOC57
5
-e'ore con"!nu!ng, e/ecu"e "he "hree s"a"emen"s g!&en !n "he manual "o crea"e "he "able,
!nser" "he me"a?da"a !n"o U4;RN4DON3;OMNM;T%D%T% "able, and crea"e "he !nde/.
7e/", !nser" a sample ro+ as sho+n belo+ !n c+&"sDl. The ro+ descr!bes a polgon o' C/,F
ord!na"es +h!ch are g!&en as pa!rs !n "he 4DONORD:7%T;N%RR%M arra)
Script /A' c+&"sDl
insert into cola$markets Calues %
@01+ -- market 5L num/er
0pol#gon0+
sdo$geometr# %
200@+ -- two-dimensional pol#gon
null+
null+
sdo$elem$in'o$arra#%1+100@+1&+ -- one pol#gon %e.terior pol#gon ring&
sdo$ordinate$arra#%5+1+ 8+1+ 8+P+ 5+U+ 5+1& -- list o' ,+; coordinates
&
&!
commit!
% decompos!"!on 'unc"!on !n c+2"sDl helps >uer "he coord!na"es !n PHP. 7o"e "he al!as CM Can
al!as here !s also (no+n as a correlation na+eF 'or "he "able !n "he >uer. Th!s allo+s "he
4DONORD:7%T;4 collec"!on "o be !ncluded as a selec" column)
(&0
Bsing !L/#;L With .C'1
Script /&' c+2"sDl
create or replace procedure m#proc%p$id in num/er+ p$o out sdo$ordinate$arra#& as
/egin
select cm.shape.sdo$ordinates
into p$o
'rom cola$markets cm
where mkt$id * p$id!
end!
/
show errors
The coord!na"es can no+ be re"r!e&ed !n PHP as a collec"!on)
Script /2' c+"php
<?php

)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "/egin m#proc%:id+ :ords&! end!"&!
)id * @01!
oci$/ind$/#$name%)s+ ":id"+ )id&!
)ords * oci$new$collection%)c+ "7L3$3BL5M6:-$6BB6;"&!
oci$/ind$/#$name%)s+ ":ords"+ )ords+ -1+ 345$I$M:;&!
oci$e.ecute%)s&!
'or %)i * 0! )i < )ords-siXe%&! )iHH& (
)C * )ords-get-lem%)i&!
echo "Zalue: )C2n"!
=
?
The ou"pu" !s "he l!s" o' coord!na"es "ha" +ere !nser"ed !n "he 4DONORD:7%T;N%RR%M)
Zalue: 5
Zalue: 1
Zalue: 8
Zalue: 1
Zalue: 8
Zalue: P
Zalue: 5
Zalue: U
Zalue: 5
Zalue: 1
4!m!lar "echn!>ues "o "hese e/ample g!&en, or "hose "echn!>ues !n earl!er sec"!ons l!(e #sing
PF;SEF and Oracle Ob0ect )ypes in PHP can be used "o 'e"ch o"her .oca"or da"a, !' re>u!red.
Scheduling )ac=ground or 'ong :unning Operation!
4ome"!mes a +eb page s"ar"s a da"abase opera"!on "ha" can run !n "he bac(ground +h!le "he
user con"!nues o"her +or(.
(&1
#cheduling >ackground or Long Running .perations
2or e/ample, "here m!gh" be some da"abase cleanup "o be run per!od!call. %no"her
e/ample !s +hen a user o' a pho"o s!"e dec!des "o change "he name o' a "ag assoc!a"ed +!"h
!mages. The pho"o s!"e appl!ca"!on m!gh" !n!"!a"e "he name change, bu" re"urn "he user an
HTM. page sa!ng >our reDuest is being processed and ,ill soon co+plete. The user can
con"!nue &!e+!ng pho"os +!"hou" ha&!ng "o +a!" 'or "he renam!ng process "o comple"e. Th!s
"echn!>ue can !mpro&e user sa"!s'ac"!on. :" can also 'ree up an %pache ser&er "ha" +ould
o"her+!se be bloc(ed, allo+!ng !" "o be used b ano"her page re>ues".
The D-M4N4CH;DU.;R pac(age can be used "o s"ar" such bac(ground da"abase "as(s. :"
has a lo" o' 'unc"!onal!", !nclud!ng allo+!ng "as(s "o be repea"ed a" !n"er&als, or s"ar"ed +hen
e&en"s are rece!&ed. :" can also be used "o !n&o(e opera"!ng ss"em programs. :n Oracle Li,
"he D-M4N*O- pac(age can be used !ns"ead o' D-M4N4CH;DU.;R.
2or "he pho"o s!"e e/ample, crea"e some da"a +!"h "he "ag ,eeding)
Script /6' dschedinit"sDl
connect s#stem/s#stempwd
grant create Wo/ to hr!
connect hr/welcome
drop ta/le tag$ta/le!
create ta/le tag$ta/le %tag Carchar2%20&+ photo$id num/er&!
insert into tag$ta/le Calues %0weeding0+ 20@D&!
insert into tag$ta/le Calues %0weeding0+ 20@5&!
insert into tag$ta/le Calues %0san'rancisco0+ D5D0&!
commit!
To change "he "ag ,eeding "o ,edding, a procedure changetagname%& can be crea"ed)
Script /5' dbsched"sDl
create or replace procedure changetagname%old in Carchar2+ new in Carchar2& as
/ num/er!
/egin
'or i in 1..100000000 loop / :* 1! end loop! -- simulate slow transaction
update tag$ta/le set tag * new where tag * old!
commit!
end!
/
show errors
Th!s scr!p" crea"es a sample "able and "he procedure "o upda"e "ags. The procedure !s
ar"!'!c!all slo+ed do+n "o s!mula"e a b!g, long runn!ng da"abase opera"!on.
The 'ollo+!ng PHP scr!p" uses an anonmous bloc( "o crea"e a 8ob call!ng changetagname%&.
Script /4' dsched"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
'unction do"uer#%)c&
(&2
Bsing !L/#;L With .C'1
(
)s * oci$parse%)c+ "select tag 'rom tag$ta/le"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
=
// 7chedule a task to change a tag name 'rom 0weeding0 to 0wedding0
)stmt *
"/egin
d/ms$scheduler.create$Wo/%
Wo/$name * :Wo/name+
Wo/$t#pe * 07:3B-L$EB34-LRB-0+
Wo/$action * 0changetagna-e0+ // procedure to call
num/er$o'$arguments * 2&!
d/ms$scheduler.set$Wo/$argument$Calue %
Wo/$name * :Wo/name+
argument$position * 1+
argument$Calue * :oldCal&!
d/ms$scheduler.set$Wo/$argument$Calue %
Wo/$name * :Wo/name+
argument$position * 2+
argument$Calue * :newCal&!
d/ms$scheduler.ena/le%:Wo/name&!
end!"!
)s * oci$parse%)c+ )stmt&!
)Wo/name * uni"id%0ut0&!
)oldCal * 0weeding0!
)newCal * 0wedding0!
oci$/ind$/#$name%)s+ ":Wo/name"+ )Wo/name&!
oci$/ind$/#$name%)s+ ":oldCal"+ )oldCal&!
oci$/ind$/#$name%)s+ ":newCal"+ )newCal&!
oci$e.ecute%)s&!
echo "<pre;our re"uest is /eing processed and will soon complete2n"!
do"uer#%)c&! // giCes old results
sleep%10&!
echo ";our re"uest has pro/a/l# completed2n"!
do"uer#%)c&! // giCes new results
?
The PHP call "o "he anonmous P.<4B. bloc( re"urns >u!c(l. The bac(ground P.<4B. call "o
changetagname%& +!ll "a(e se&eral more seconds "o comple"e Cbecause o' !"s 'or loopF, so "he
'!rs" do"uer#%& ou"pu" sho+s "he or!g!nal, !ncorrec" "ag &alues. Then, a'"er PHP has g!&en "he
8ob "!me "o conclude, "he second do"uer#%& call sho+s "he upda"ed &alues)
;our re"uest is /eing processed and will soon complete
arra#%1& (
9":6Y"<*
((3
#cheduling >ackground or Long Running .perations
arra#%@& (
90<*
string%U& "weeding"
91<*
string%U& "weeding"
92<*
string%12& "san'rancisco"
=
=
;our re"uest has pro/a/l# completed
arra#%1& (
9":6Y"<*
arra#%@& (
90<*
string%U& "wedding"
91<*
string%U& "wedding"
92<*
string%12& "san'rancisco"
=
=
Oracle Strea1! ,d-anced &ueuing
%no"her +a "o !n!"!a"e bac(ground "as(s !s "o use Oracle 4"reams %d&anced Bueu!ng !n a
producer?consumer message pass!ng 'ash!on. Oracle %B !s h!ghl con'!gurable. Messages can
>ueued b mul"!ple producers. D!''eren" consumers can '!l"er messages 'or "hem. Messages
can also be propaga"ed "o >ueues !n o"her da"abases. Oracle %B has P.<4B., *a&a, C and
HTTP4 !n"er'aces. 2rom PHP, "he P.<4B. !n"er'ace !s used.
The 'ollo+!ng e/ample s!mula"es an appl!ca"!on user reg!s"ra"!on ss"em +here "he PHP
appl!ca"!on >ueues each ne+ userAs s"ree" address. %n e/"ernal ss"em can "hen 'e"ch and
process "ha" address. :n real l!'e "he e/"ernal ss"em m!gh" ma!l a +elcome le""er, or do
'ur"her, slo+er &al!da"!on on "he address.
The 4B.SPlus scr!p" Dcreate"sDl crea"es a ne+ Oracle user de+oDueue +!"h perm!ss!on "o
crea"e and use >ueues. % paload "pe 'or "he address !s crea"ed and a >ueue se" up 'or "h!s
paload.
Script /9' Dcreate"sDl
connect / as s#sd/a
drop user demo"ueue cascade!
create user demo"ueue identi'ied /# welcome!
grant connect+ resource to demo"ueue!
grant a"$administrator$role+ a"$user$role to demo"ueue!
grant e.ecute on d/ms$a" to demo"ueue!
grant create t#pe to demo"ueue!
connect demo"ueue/welcomeOlocalhost/.e
-- :he data we want to "ueue
create or replace t#pe user$address$t#pe as o/Wect %
((&
Bsing !L/#;L With .C'1
name Carchar2%10&+
address Carchar2%50&
&!
/
/egin
d/ms$a"adm.create$"ueue$ta/le%
"ueue$ta/le * 0demo"ueue.addr$"ueue$ta/0+
"ueue$pa#load$t#pe * 0demo"ueue.user$address$t#pe0&!
end!
/
/egin
d/ms$a"adm.create$"ueue%
"ueue$name * 0demo"ueue.addr$"ueue0+
"ueue$ta/le * 0demo"ueue.addr$"ueue$ta/0&!
end!
/
/egin
d/ms$a"adm.start$"ueue%
"ueue$name * 0demo"ueue.addr$"ueue0+
en"ueue * true&!
end!
/
The scr!p" Dhelper"sDl crea"es "+o helper 'unc"!ons "o en>ueue and de>ueue messages.
Script /?' Dhelper"sDl
-- 7et up en"ueue/de"ueue procedures
connect demo"ueue/welcomeOlocalhost/.e
create or replace procedure m#$en"%
user$addr$p in user$address$t#pe+
priorit#$p in num/er& as
en"ueue$options d/ms$a".en"ueue$options$t!
message$properties d/ms$a".message$properties$t!
en"$id raw%1P&!
/egin
d/ms$a".en"ueue%"ueue$name * 0demo"ueue.addr$"ueue0+
en"ueue$options * en"ueue$options+
message$properties * message$properties+
pa#load * user$addr$p+
msgid * en"$id&!
commit!
end!
/
show errors
create or replace procedure m#$de"%
user$addr$p out user$address$t#pe& as
de"ueue$options d/ms$a".de"ueue$options$t!
(((
.racle #treams Ad$anced ;ueuing
message$properties d/ms$a".message$properties$t!
en"$id raw%1P&!
/egin
d/ms$a".de"ueue%"ueue$name * 0demo"ueue.addr$"ueue0+
de"ueue$options * de"ueue$options+
message$properties * message$properties+
pa#load * user$addr$p+
msgid * en"$id&!
commit!
end!
/
show errors
The scr!p" ne,user"php handles a ne+ appl!ca"!on user and >ueues a message con"a!n!ng
"he!r address)
Script //' ne,user"php
<?php
)c * oci$connect%"demo"ueue"+ "welcome"+ "localhost/.e"&!
// :he new application user details
)username * 0Ared0!
)address * 0500 3racle Earkwa#0!
// -n"ueue the user in'ormation 'or 'urther o''line handling
)s"l * "/egin m#$en"%user$address$t#pe%0)username0+ 0)address0&+ 1&! end!"!
)s * oci$parse%)c+ )s"l&!
)r * oci$e.ecute%)s&!
// 4ontinue processing the new user in the current script
echo "?elcome )username2n"!
?
Th!s e/ecu"es an anonmous P.<4B. bloc( "o crea"e and en>ueue "he address message. The
!mmed!a"e ou"pu" "o "he caller !s s!mpl "he +elcome message)
?elcome Ared
Once "h!s PHP scr!p" !s e/ecu"ed, an appl!ca"!on can de>ueue "he ne+ message a" !"s le!sure.
2or e/ample, "he 'ollo+!ng 4B.SPlus commands call "he helper my_de!" de>ueue 'unc"!on
and d!spla "he user de"a!ls)
Script /8' sho,user"sDl
connect demo"ueue/welcomeOlocalhost/.e
set serCeroutput on
declare
user$address user$address$t#pe!
/egin
m#$de"%user$address&!
(()
Bsing !L/#;L With .C'1
d/ms$output.put$line%0Mame : 0 [[ user$address.name&!
d/ms$output.put$line%06ddress : 0 [[ user$address.address&!
end!
/
The ou"pu" !s)
Mame : Ared
6ddress : 500 3racle Earkwa#
:' "h!s de>ueue opera"!on !s called +!"hou" an"h!ng !n "he >ueue, !" +!ll bloc( +a!"!ng 'or a
message un"!l "he >ueue +a!" "!me e/p!res.
The P.<4B. %P: has much more 'unc"!onal!" "han sho+n !n "h!s o&er&!e+. 2or e/ample ou
can en>ueue an arra o' messages, or l!s"en "o more "han one >ueue.
Bueu!ng !s h!ghl con'!gurable and scalable, pro&!d!ng a grea" +a "o d!s"r!bu"e +or(load
'or a +eb appl!ca"!on. Oracle %B !s a&a!lable !n all ed!"!ons o' "he da"abase.
:eu!ing Procedure! Written *or 5O#AP'S&'
OracleAs MODNP.4B. ga"e+a allo+s a 0eb bro+ser "o !n&o(e a P.<4B. s"ored subprogram
"hrough an HTTP l!s"ener. Th!s !s "he !n"er'ace used b Oracle %ppl!ca"!on ;/press. ;/!s"!ng
user?crea"ed P.<4B. procedures +r!""en 'or "h!s ga"e+a can be called 'rom PHP us!ng a
+rapper 'unc"!on. 2or e/ample, cons!der a s"ored procedure 'or MODNP.4B. "ha" +as crea"ed
!n 4B.SPlus)
Script 8A' +yo,a"sDl
create or replace procedure m#owa as
/egin
htp.html3pen!
htp.head3pen!
htp.title%0Yreeting :itle0&!
htp.head4lose!
htp./od#3pen!
htp.header%1+ 07alutation >eading0&!
htp.p%0>ello+ world80&!
htp./od#4lose!
htp.html4lose!
end!
/
show errors
Th!s genera"es HTM. ou"pu" "o "he ga"e+a)
<>:NK
<>-6L
<:5:K-Yreeting :itle</:5:K-
</>-6L
<I3L;
<>17alutation >eading</>1
>ello+ world8
</I3L;
</>:NK
((*
Reusing !rocedures Written Aor :.DC!L#;L
To reuse "he procedure d!rec"l !n PHP, use HTP.3;TN.:7; !n a mapp!ng 'unc"!on "o p!pe "he
ou"pu" 'rom "he +yo,a"sDl HTP calls)
Script 8&' +y+odplsDl"sDl
create or replace t#pe modpsrow as ta/le o' Carchar2%512&!
/
show errors
create or replace 'unction m#modpls"l%proc Carchar2& return modpsrow pipelined is
param$Cal owa.Cc$arr!
line Carchar2%25P&!
irows integer!
/egin
owa.init$cgi$enC%param$Cal&!
htp.init!
e.ecute immediate 0/egin 0[[proc[[0! end!0!
loop
line :* htp.get$line%irows&!
e.it when line is null!
pipe row %line&!
end loop!
return!
end!
/
show errors
Th!s !s 'undamen"all s!m!lar "o "he pre&!ous p!pel!ned e/amples.
:n modpsrow%& ou can op"!onall use P%R%MN,%. "o se" C3: &alues. 4ee "he de'!n!"!on o'
init.cgi$enC%& !n JO:A-FE=HO!E;rdb+s;ad+in;privo,a"sDl 'or de"a!ls.
:n PHP, "he ne+ +rapper can be called l!(e)
Script 82' +y+odplsDl"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)stmt * oci$parse%)c+ 0select J 'rom ta/le%m#modpls"l%:proc&&0&!
)'unc * 0m#owa0!
oci$/ind$/#$name%)stmt+ 0:proc0+ )'unc&!
oci$e.ecute%)stmt&!
)content * 'alse!
while %)row * oci$'etch$arra#%)stmt+ 345$67734&& (
i' %)content& (
print )row9"43KRNM$Z6KR-"<!
= else (
i' %)row9"43KRNM$Z6KR-"< ** "2n"&
)content * true!
else
header%)row9"43KRNM$Z6KR-"<&!
=
=
((+
Bsing !L/#;L With .C'1
?
0hen called !n a bro+ser, "he ou"pu" !s "he e/pec"ed rend!"!on o' "he HTM. 'ragmen" sho+n
earl!er.
Ea!6 P'2S&' 0pgrade! With Edition )a!ed :ede*inition
The Editioning 'ea"ure o' Oracle Da"abase 11gR2 !s &er use'ul 'or +eb appl!ca"!ons "ha" a!m
'or no do+n"!me +hen releas!ng enhanced &ers!ons o' appl!ca"!ons. :" allo+s mul"!ple &ers!ons
o' P.<4B. ob8ec"s +!"h "he same names "o be used concurren"l. Th!s le"s ou upgrade s"ored
procedures and "es" ne+ &ers!ons +h!le produc"!on users are s"!ll access!ng "he or!g!nal
&ers!ons. %s +ell as allo+!ng "h!s sa'e +a "o upgrade, ou can also use !" 'or %<- "es"!ng,
+here ou e&alua"e "he user response "o a ne+ &ers!on o' our appl!ca"!on. The appl!ca"!on
&ers!ons "ha" users donA" apprec!a"e can >u!c(l be dropped.
The ob8ec"s ou can ed!"!on are)
snonms
&!e+s
P.<4B. ob8ec" "pes)
'unc"!on
l!brar
pac(age and pac(age bod
procedure
"r!gger
"pe and "pe bod
Tables "hemsel&es canA" be ed!"!oned bu" "here !s suppor" 'or mo&!ng and &!e+!ng da"a across
ed!"!ons.
The 'ollo+!ng e/ample sho+s ho+ ed!"!on!ng can be used "o upgrade a l!&e PHP
appl!ca"!on. The changes can be made and "es"ed on "he produc"!on da"abase and "hen
enabled 'or all users +!"h a one (e+ord change !n "he appl!ca"!on.
%s "he user 4M4T;M, allo+ "he appl!ca"!on user HR "o use ed!"!ons)
Script 86' ed&"sDl
connect s#stem/s#stempwdOlocalhost/,-
grant create an# edition to hr!
alter user hr ena/le editions!
%s "he user HR crea"e a "able o' emploees 'or "he appl!ca"!on and crea"e "he s"ored 'unc"!on
"ha" calcula"es "he number o' das o' &aca"!on an emploee !s el!g!ble 'or. Th!s 'unc"!on !s
s"ored !n "he da"abase so all Oracle appl!ca"!ons can reuse "he same log!c)
Script 85' ed2"sDl
connect hr/welcomeOlocalhost/,-
drop ta/le m#emp!
((-
4asy !L/#;L Bpgrades With 4dition >ased RedeAinition
create ta/le m#emp %name Carchar2%10&+ hoursworked num/er&!
insert into m#emp %name+ hoursworked& Calues %0alison0+ 200&!
insert into m#emp %name+ hoursworked& Calues %0kris0+ 200&!
insert into m#emp %name+ hoursworked& Calues %0wenWi0+ 200&!
commit!
create or replace 'unction Cacationda#sle't%p$name in Carchar2& return num/er as
Cdl num/er!
/egin
-- Aor eCer# D0 hours worked+ #ou get 1 da# o' Cacation
select 'loor%hoursworked / D0& into Cdl
'rom m#emp
where m#emp.name * p$name!
return Cdl!
end!
/
Tes" "he 'unc"!on !n 4B.SPlus b call!ng !")
7SK select name+ Cacationda#sle't%name& 'rom m#emp!
Th!s re"urns)
M6N- Z646:53ML6;7K-A:%M6N-&
------------------------------ ----------------------
alison 5
kris 5
wenWi 5
:n PHP "he 'unc"!on m!gh" be used l!(e)
Script 84' edition&"php
<?php
oci$set$edition%0ora)/ase0&!
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "/egin :Cdl :* Cacationda#sle't%:name&! end!"&!
oci$/ind$/#$name%)s+ ":Cdl"+ )Cdl+ 10&!
oci$/ind$/#$name%)s+ ":name"+ )name+ 10&!
)name * 0alison0!
oci$e.ecute%)s&!
echo ")name has ".)Cdl." da#s Cacation le't2n"!
?
Th!s ma(es a s!mple call "o "he s"ored 'unc"!on and re"urns "he number o' &aca"!on das
person )name has.
The ora)/ase "o(en !n oci$set$edition%& means "o use "he roo" or '!rs" ed!"!on o' ob8ec"s,
!.e "he P.<4B. 'unc"!on +e 8us" crea"ed. %l"hough curren"l redundan" because !" se"s "he
de'aul" ed!"!on, "he ed!"!on name +!ll be changed !n "he ne/" &ers!on o' "h!s '!le "o change "he
&ers!on o' "he Cacationda#sle't%& procedure be!ng called. :ns"ead o' call!ng
((0
Bsing !L/#;L With .C'1
oci$set$edition%& ou could al"erna"!&el ass!gn an ed!"!on "o an Oracle 7e" ser&!ce +!"h "he
D-M4N4;R,:C; P.<4B. procedure and se" "he PHP connec"!on s"r!ng "o "ha" ser&!ce..
% D-% can >uer D-%N;D:T:O74 "o see +ha" ed!"!ons are a&a!lable !n "he da"abase. %n
appl!ca"!on user can >uer select s#s$conte.t%0R7-B-MZ0+ 04RBB-M:$-L5:53M$M6N-0& 'rom
dual "o see "he ed!"!on "he are curren"l access!ng.
The scr!p" edition&"php produces ou"pu" l!(e)
alison has 5 da#s Cacation le't
Th!s !s good. 0e can pu" "he appl!ca"!on !n"o produc"!on and emploees can s"ar" us!ng !".
7o+ assume "he ra"e used "o calcula"e &aca"!on hours needs "o be changed so "ha" 'or
e&er I0 hours +or(ed, emploees ge" one da o' &aca"!on. %lso +e no+ +an" "he calcula"!on
"o !nclude ho+ man das &aca"!on "he ha&e alread "a(en.
2!rs", +e need a ne+ column "o s"ore "he &aca"!on "he ha&e pre&!ousl "a(en. %dd!ng "h!s
column +onA" a''ec" "he runn!ng PHP appl!ca"!on s!nce !" doesnA" (no+ abou" !" C"h!s !s a good
rem!nder ne&er "o do select J !n an appl!ca"!onF. The ne+ column !s crea"ed and, 'or "he
purpose o' "h!s e/ample, popula"ed +!"h some arb!"rar &alues)
Script 89' ed6"sDl
-- Bun as >B
alter ta/le m#emp add da#sCacationtaken num/er!
update m#emp set da#sCacationtaken * 2 where name * 0alison0!
update m#emp set da#sCacationtaken * @ where name * 0kris0!
update m#emp set da#sCacationtaken * 0 where name * 0wenWi0!
commit!
C2or more comple/ m!gra"!on scenar!os "he ed!"!on!ng 'ea"ure has crossedition "r!ggers and
editioning vie,s "o help ensure "he appropr!a"e da"a !s used !n "he old and ne+ ed!"!ons.F
7o+ crea"e "he ne+ &ers!on o' "he P.<4B. 'unc"!on. :n 4B.SPlus as HR crea"e a ne+
ed!"!on)
Script 8?' ed5"sDl
-- Bun as >B
create edition e2!
Crea"e "he upda"ed &ers!on o' "he P.<4B. procedure. -ecause "he 4B.SPlus sess!on !s no+
runn!ng !n ed!"!on ;2 "h!s ne+ procedure +onA" a''ec" "he PHP appl!ca"!on +h!ch !s runn!ng
us!ng ed!"!on OR%W-%4;)
Script 8/' ed4"sDl
-- Bun as >B
alter session set edition * e2!
create or replace 'unction Cacationda#sle't%p$name in Carchar2& return num/er as
Cdl num/er!
/egin
-- Aor eCer# @0 hours worked+ #ou get 1 da# o' Cacation
select 'loor%hoursworked / @0& - da#sCacationtaken into Cdl
'rom m#emp
((1
4asy !L/#;L Bpgrades With 4dition >ased RedeAinition
where m#emp.name * p$name!
return Cdl!
end!
/
Buer!ng !" sho+s "he upda"ed &alues)
7SK select name+ Cacationda#sle't%name& 'rom m#emp!
M6N- Z646:53ML6;7K-A:%M6N-&
------------------------------ ----------------------
alison D
kris @
wenWi P
Th!s !s all done +h!le o"hers users con"!nue "o use "he PHP appl!ca"!on l!&e and ge" "he or!g!nal
resul"s. The ne+ P.<4B. procedure sho+s %l!son no+ has onl J das o' &aca"!on. Mou can run
"he PHP scr!p" and chec( !" s"!ll re"urns "he @old@ &alue)
alison has 5 da#s Cacation le't
7o+ cop "he PHP '!le "o edition2"php and change "he oci$set$edition%& 'unc"!on "o se" "he
ne+ ed!"!on)
Script 88' edition2"php
<?php
oci$set$edition%0e30&!
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "/egin :Cdl :* Cacationda#sle't%:name&! end!"&!
oci$/ind$/#$name%)s+ ":Cdl"+ )Cdl+ 10&!
oci$/ind$/#$name%)s+ ":name"+ )name+ 10&!
)name * 0alison0!
oci$e.ecute%)s&!
echo ")name has ".)Cdl." da#s Cacation le't2n"!!
?
0hen edition2"php !s run, "he ou"pu" sho+s "he upda"ed calcula"!on o' &aca"!on "!me)
alison has D da#s Cacation le't
Mou can run bo"h edition&"php and edition2"php concurren"l and "he +!ll sho+ d!''eren"
resul"s e&en "hough "he PHP appl!ca"!on log!c and "he P.<4B. procedure name "he call !s
!den"!cal.
Oracle Da"abase 11gR2 ;d!"!on -ased Rede'!n!"!on helps PHP appl!ca"!ons mee" "he goals
o' m!n!mal do+n"!me +!"h "he 're>uen" upgrade ccle needed b +eb appl!ca"!ons. :" allo+s
PHP appl!ca"!ons, "he!r o'"en comple/ s"ored log!c, and large da"a se"s "o be upda"ed read 'or
roll!ng ou" !n produc"!on +!"hou" !mpac"!ng "he opera"!on o' e/!s"!ng users.
((2
Bsing !L/#;L With .C'1
#ata$a!e Tran!action! ,cro!! Statele!! We$ :eBue!t!
The D-M4N=% pac(age can be used "o s"ar", resume and comple"e da"abase "ransac"!ons.
0eb appl!ca"!ons can rel on "he da"abase "o s"ore "he "ransac"!on s"a"e. :' ou ha&e mul"!ple
m!d?"!er +eb ser&ers, "h!s remo&es "he need "o "rac( "he s"a"e o' a se" o' 4B. opera"!ons. The
onl shared !n'orma"!on needed b each +eb re>ues" !s a numer!c (e !den"!'!ng "he
"ransac"!on. Th!s (e should be secured and made a&a!lable "o "he appl!ca"!on &!a PHPAs
sess!on handl!ng.
Us!ng "he TOM4 "able 'rom toyshop"sDl Csho+n !n "he !n"roduc"!on "o pac(ages a" "he s"ar"
o' "h!s chap"erF run 4B.SPlus and chec( "he curren" records)
7SK select J 'rom to#s!
5L M6N-
---------- ----------------------------------------
2 /all
@ paddling pool
1 /ic#cle
% D-M4N=% e/ample s"ar"s +!"h xa&"php)
Script &AA' xa&"php
<?php
)id * 12@!
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
// 7tart a transaction+ insert a :edd# Iear+ and suspend the transaction
)s"l *
"declare
rc pls$integer!
/egin
rc :* d/ms$.a..a$start%d/ms$.a$.id%:id&+ d/ms$.a.tmno'lags&!
insert into to#s %id+ name& Calues %D+ 0tedd# /ear0&!
rc :* d/ms$.a..a$end%d/ms$.a$.id%:id&+ d/ms$.a.tmsuspend&!
end!"!
)s * oci$parse%)c+ )s"l&!
oci$/ind$/#$name%)s+ ":id"+ )id&!
oci$e.ecute%)s&!
?
Th!s scr!p" beg!ns a "ransac"!on arb!"rar!l !den"!'!ed as 12I, and !nser"s a ne+ "o. 2or sa(e o'
"he e/ample, "he !den"!'!er &alue !s hard coded.
;/ecu"e xa&"php)
) php .a1.php
There !s no ou"pu".
()3
Data5ase Transactions Across #tateless We5 Requests
:n 4B.SPlus chec( "he ro+s !n "he "able. The ne+ ro+ has no" e" been comm!""ed and !s
no" &!s!ble e".
The second scr!p", xa2"php, resumes "ransac"!on number 12I, !nser"s ano"her ne+ ro+
and comm!"s "he "ransac"!on)
Script &A&' xa2"php
<?php
)id * 12@!
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
// Besume the transaction+ insert a 7tethoscope+ and commit
)s"l *
"declare
rc pls$integer!
/egin
rc :* d/ms$.a..a$start%d/ms$.a$.id%:id&+ d/ms$.a.tmresume&!
insert into to#s %id+ name& Calues %5+ 0stethoscope0&!
rc :* d/ms$.a..a$commit%d/ms$.a$.id%12@&+ true&!
end!"!
)s * oci$parse%)c+ )s"l&!
oci$/ind$/#$name%)s+ ":id"+ )id&!
oci$e.ecute%)s&!
?
Run "h!s scr!p" C"here !s no ou"pu"F and "hen use 4B.SPlus "o >uer "he "able)
7SK select J 'rom to#s!
5L M6N-
---------- ----------------------------------------
2 /all
@ paddling pool
D tedd# /ear
5 stethoscope
1 /ic#cle
Th!s sho+s "ha" bo"h ne+ ro+s +ere !nser"ed, e&en "hough "he PHP scr!p"s +ere run !n
!ndependen" processes, +!"h an un(no+n "!me 'rame. :' ou donA" see "he "edd bear ro+, ou
probabl "oo( longer "han O0 seconds be"+een runn!ng xa&"php and xa2"php. Th!s !s "he
de'aul" "!meou" be'ore a "ransac"!on !s abor"ed. :" can be se" +!"h D-M4N=%.=%N4;TT:M;OUT.
The D-M4N=% pac(age !s a con&en!en" +a "o conduc" "ransac"!ons across "he +eb. :"
pro&!des 'unc"!onal!" "o s"ar", suspend, and cancel "ransac"!ons. The "ransac"!on number !s
"he onl p!ece o' me"ada"a "ha" needs "o be chosen and shared across +eb re>ues"s. Th!s !s
eas!l managed us!ng s"andard PHP "echn!>ues such as +!"h PHP sess!ons.
()&
Bsing !L/#;L With .C'1
()(
CH,PTE: 13
0SING ',:GE O)HECTS IN OCI.
Oracle Charac"er .arge Ob8ec" CC.O-F and -!nar .arge Ob8ec" C-.O-F "pes can be used 'or
&er large amoun"s o' da"a. The can be used 'or "able columns and as P.<4B. &ar!ables. %
pre?suppl!ed D-M4N.O- pac(age ma(es man!pula"!on !n P.<4B. eas. OC:$ .O- me"hods
allo+ s"or!ng and 'e"ch!ng .O- da"a !n PHP
Oracle also has a -2:.; "pe 'or large ob8ec"s s"ored ou"s!de "he da"abase.
Wor=ing With 'O)!
:n success!&e &ers!ons, "he Oracle da"abase has made !" eas!er "o +or( +!"h .O-s. %long "he
+a DTemporar .O-sE +ere added, and some s"r!ng?"o?.O- con&ers!ons are no+ "ransparen"
so da"a can be handled d!rec"l as s"r!ngs. De&elop and "es" our .O- appl!ca"!on +!"h "he
Oracle cl!en" l!brar!es and da"abase "ha" +!ll be used 'or deplomen" so ou can be sure all
"he e/pec"ed 'unc"!onal!" !s a&a!lable.
0hen +or(!ng +!"h large amoun"s o' da"a, se" +e+ory=li+it appropr!a"el !n php"ini
o"her+!se PHP ma "erm!na"e earl. 0hen read!ng or +r!"!ng '!les "o d!s(, chec( !'
open=basedir allo+s '!le access.
These e/ample sho+ -.O-s. Us!ng C.O-s !s almos" !den"!cal "o us!ng -.O-s) "he
descr!p"or "pe becomes OC:NDNC.O-, "he b!nd "pe becomes OC:N-NC.O-, and "ables mus"
ob&!ousl con"a!n a C.O- column.
The e/amples use a "able crea"ed !n 4B.SPlus con"a!n!ng a -.O- column called -.O-D%T%)
7SK create ta/le m#/ta/ %/lo/id num/er primar# ke#+ b"obdata b"ob&!
7o"e >uer!ng -.O- columns !n 4B.SPlus !s no" poss!ble unless 4B.SPlus 11g !s used, +here !"
+!ll d!spla a he/adec!mal &ers!on o' "he da"a. Tables +!"h C.O- columns can be >uer!ed !n all
&ers!ons o' 4B.SPlus. The ou"pu" o' -.O- and C.O- da"a can be con"rolled !n 4B.SPlus +!"h
"he 7-: K3MY command. The de'aul" &alue o' $0 means "ha" onl "he '!rs" $0 charac"ers o'
da"a +!ll be d!splaed b a >uer.
.O- da"abase s"orage and access op"!ons can be con'!gured a" "able crea"!on "!me, or +!"h
6K:-B :6IK-. 2re>uen"l accessed .O-s +!ll bene'!" 'rom mon!"or!ng "he!r use and ad8us"!ng
"he!r con'!gura"!on. One common "un!ng s"ep !s "o "urn on .O- cach!ng)
7SK alter ta/le m#/ta/ modi'# lo/ %/lo/data& %cache&!
:n Oracle 11g ou can op"!onall crea"e .O-s +!"h "he s"orage op"!on 4;CUR;2:.; "o "a(e
ad&an"age o' .O- 4ecure2!le 'ea"ures such as dedupl!ca"!on and compress!on.
In!erting and 0pdating 'O)!
:n PHP, .O-s are generall man!pula"ed us!ng a descr!p"or. PHP code "o !nser" !n"o MM-T%- !s)
Script &A2' blobinsert"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
())
Bsing Large .5=ects in .C'1
)m#/lo/id * 12@!
)m#C * 0a Cer# large amount o' /inar# data0!
)s * oci$parse%)c+ 0insert into m#/ta/ %/lo/id+ /lo/data&
Calues %:m#/lo/id+ -NE:;$IK3I%&&
returning /lo/data into :/lo/data0&!
)lo/ * oci$new$descriptor%)c+ 345$L$K3I&!
oci$/ind$/#$name%)s+ 0:m#/lo/id0+ )m#/lo/id&!
oci$/ind$/#$name%)s+ 0:/lo/data0+ )lo/+ -1+ 345$I$IK3I&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&! // Lon0t commit so )lo/-saCe%& works
)lo/-saCe%)m#C&!
oci$commit%)c&!
)lo/-close%&! // close K3I descriptor to 'ree resources
?
The B-:RBM5MY clause re"urns "he Oracle .O- loca"or o' "he ne+ ro+. - b!nd!ng as
OC:N-N-.O-, "he PHP descr!p"or !n )lo/ re'erences "h!s loca"or. The )lo/-saCe%& me"hod
"hen s"ores "he da"a !n )m#C !n"o "he -.O- column. The OC:N7ON%UTONCOMM:T 'lag !s used
'or oci$e.ecute%& so "he descr!p"or rema!ns &al!d 'or "he saCe%& me"hod. The comm!"
concludes "he !nser" and ma(es "he da"a &!s!ble "o o"her da"abase users.
:' "he appl!ca"!on uploads .O- da"a us!ng a +eb 'orm, !" can be !nser"ed d!rec"l 'rom "he
upload d!rec"or +!"h )lo/-import%)'ilename&. PHPKs ma/!mum allo+ed s!1e 'or uploaded
'!les !s se" !n php"ini us!ng "he upload=+ax=*ilesie parame"er.
To upda"e a .O-, use "he same code +!"h "h!s 4B. s"a"emen")
)s * oci$parse%)c+ 0update m#/ta/ set
/lo/data * empt#$/lo/%&
returning /lo/data into :/lo/data0&!
9etching 'O)!
0hen 'e"ch!ng a .O-, OC:$ re"urns a .O- descr!p"or. The da"a can be re"r!e&ed b us!ng a
load%& or read%& me"hod)
Script &A6' blob*etch"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)m#/lo/id * 12@!
)"uer# * 0select /lo/data 'rom m#/ta/ where /lo/id * :m#/lo/id0!
)s * oci$parse %)c+ )"uer#&!
oci$/ind$/#$name%)s+ 0:m#/lo/id0+ )m#/lo/id&!
oci$e.ecute%)s&!
)arr * oci$'etch$arra#%)s+ 345$67734&!
i' %is$o/Wect%)arr90IK3IL6:60<&& ( // protect against a MRKK K3I
)data * )arr90IK3IL6:60<-load%&!
)arr90IK3IL6:60<-'ree%&!
()*
Working With L.>s
echo )data!
=
?
:" !s !mpor"an" "o 'ree all re"urned .O- loca"ors "o a&o!d lea(s)
while %%)arr * oci$'etch$arra#%)s+ 345$67734&&& (
echo )arr90IK3IL6:60<-load%&! // do something with the IK3I
)arr90IK3IL6:60<-2ree%&! // cleanup /e'ore ne.t 'etch
=
:' .O-4 are no" 'reed, "he %-4TR%CTN.O-4 column !n "he ,WT;MPOR%RMN.O-4 "able +!ll sho+
!ncreas!ng &alues.
:ns"ead o' us!ng loca"ors, .O- da"a can al"erna"!&el be re"urned as a s"r!ng)
)arr * oci$'etch$arra#%)s+ 345$67734H345$B-:RBM$K3I7&!
echo )arr90IK3IL6:60<!
:' "he re"urned da"a !s larger "han e/pec"ed, PHP ma no" be able "o alloca"e enough memor.
To pro"ec" aga!ns" "h!s, use a loca"or +!"h "he read%& me"hod, +h!ch allo+s "he da"a "o be
'e"ched !n chun(s.
0hen do!ng 4;.;CT ] 2OR UPD%T;, use oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&
o"her+!se ou +!ll ge" an O:A3A&AA2' *etch out o* seDuence error +hen 'e"ch!ng "he .O-.
:n .O-?'e"ch!ng loops !" !s good prac"!ce "o 'ree local PHP &ar!ables con"a!n!ng .O- da"a
be'ore 'e"ch!ng "he ne/" record. Th!s can reduce "he o&erall memor use o' PHP, because onl
one .O- &alue needs "o be held !n memor a" a "!me, !ns"ead o' "he or!g!nal and ne+ &alues)
while %%)arr * oci$'etch$arra#%)s+ 345$67734&&& (
)arr * oci$'etch$arra#%)s+ 345$67734H345$B-:RBM$K3I7&!
echo )arr90IK3IL6:60<! // do something with the K3I
unset%)arr&! // 'ree E>E0s memor# /e'ore 'etching the ne.t K3I.
=
Te1porar6 'O)!
Temporar .O-s are crea"ed and ma!n"a!ned !n "he da"abase. PHP accesses "he .O- "here 'or
read!ng and +r!"!ng. Temporar .O-s are no" pers!s"en" and are a&a!lable onl +!"h!n "he
curren" PHP connec"!on. Temporar .O-s ma(e some opera"!ons eas!er.
:nser"!ng da"a +!"h a Temporar .O- does no" use a B-:RBM5MY 5M:3 clause, 'or e/ample)
Script &A5' te+pblobinsert"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)m#/lo/id * 12D!
)m#C * 0a Cer# large amount o' /inar# data0!
)s * oci$parse%)c+ 0insert into m#/ta/ %/lo/id+ /lo/data&
Calues %:m#/lo/id+ :/lo/data&0&!
)lo/ * oci$new$descriptor%)c+ 345$L$K3I&!
oci$/ind$/#$name%)s+ 0:m#/lo/id0+ )m#/lo/id&!
()+
Bsing Large .5=ects in .C'1
oci$/ind$/#$name%)s+ 0:/lo/data0+ )lo/+ -1+ 345$I$IK3I&!
)lo/-write:emporar#%)m#C+ 345$:-NE$IK3I&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
oci$commit%)c&!
)lo/-close%&! // close lo/ descriptor to 'ree resources
?
Temporar .O-s also s!mpl!' upda"!ng &alues)
)s * oci$parse%)c+ 0update m#/ta/ set /lo/data * :/d where /lo/id * :/id0&!
:' ou +an" "o e!"her !nser" a ne+ ro+ or upda"e e/!s"!ng da"a !' "he ro+ "urns ou" "o e/!s"
alread, "he 4B. s"a"emen" can be changed "o use an anonmous bloc( )
)s * oci$parse%)c+
0/egin0
. 0 insert into m#/ta/ %/lo/data+ /lo/id& Calues%:/lo/data+ :m#/lo/id&!0
. 0 e.ception0
. 0 when dup$Cal$on$inde. then0
. 0 update m#/ta/ set /lo/data * :/lo/data where /lo/id * :m#/lo/id!0
. 0end!0&!
0ploading and #i!pla6ing an I1age
The scr!p" i+age"php sho+s ho+ a *P;3 !mage can be uploaded and !nser"ed !n"o "he
da"abase. %'"er "he da"a !s !nser"ed, !" >uer!es "he !mage da"a bac( !mmed!a"el and d!splas
"he p!c"ure "o &er!' "he !nser" and >uer +or(. The same MM-T%- "able as crea"ed abo&e !s
used.
Script &A4' i+age"php
<?php
i' %8isset%)$A5K-790lo/$upload0<&& (
?
<h1IK3I -.ample - Rploading a TE-Y</h1
<'orm action*"<?php echo )$7-BZ-B90E>E$7-KA0<! ?" method*"E37:"
enct#pe*"multipart/'orm-data"
TE-Y image 'ilename: <input t#pe*"'ile" name*"lo/$upload"
<input t#pe*"su/mit" Calue*"Rpload"
</'orm
<?php
= else (
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/.e0&!
)m#/lo/id * 1! // should reall# /e a uni"ue id e.g. a se"uence num/er
// Lelete an# e.isting IK3I so the "uer# at the /ottom
// displa#s the new data
)s"l * 0delete 'rom m#/ta/ where /lo/id * :m#/lo/id0!
)s * oci$parse %)c+ )s"l&!
()-
Working With L.>s
oci$/ind$/#$name%)s+ 0:m#/lo/id0+ )m#/lo/id&!
)e * oci$e.ecute%)s+ 345$43NN5:$3M$7R44-77&!
// Bead and insert the IK3I 'rom E>E0s temporar# upload area
)lo/ * oci$new$descriptor%)c+ 345$L$K3I&!
)s"l * 0insert into m#/ta/ %/lo/id+ /lo/data& Calues%:m#/lo/id+ :/lo/data&0!
)s * oci$parse%)c+ )s"l&!
oci$/ind$/#$name%)s+ 0:m#/lo/id0+ )m#/lo/id&!
oci$/ind$/#$name%)s+ 0:/lo/data0+ )lo/+ -1+ 345$I$IK3I&!
)m#C * 'ile$get$contents%)$A5K-790lo/$upload0<90tmp$name0<&!
)lo/-write:emporar#%)m#C+ 345$:-NE$IK3I&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
oci$commit%)c&!
)lo/-close%&!
// Mow "uer# /ack the uploaded IK3I and displa# it
)s"l * 0select /lo/data 'rom m#/ta/ where /lo/id * :m#/lo/id0!
)s * oci$parse %)c+ )s"l&!
oci$/ind$/#$name%)s+ 0:m#/lo/id0+ )m#/lo/id&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
)arr * oci$'etch$assoc%)s&!
)result * )arr90IK3IL6:60<-load%&!
// 5' an# te.t %or whitespace8& is printed /e'ore this header is sent+
// the te.t won0t /e displa#ed and the image won0t displa# properl#.
// 4omment out this line to see the te.t and de/ug such a pro/lem.
header%"4ontent-t#pe: image/TE-Y"&!
echo )result!
=
?
0hen "he scr!p" !s !n!"!all loaded !n a bro+ser, )$A5K-790lo/$upload0< !s no" se" and so "he
HTM. upload 'orm !s d!splaed. 4ubm!""!ng "h!s 'orm calls )$7-BZ-B90E>E$7-KA0< +h!ch !s "he
same PHP scr!p". :" no+ e/ecu"es "he second par" o' "he else bloc(. Th!s dele"es an e/!s"!ng
!mage, uploads "he ne+ da"a 'rom PHPAs upload area and !nser"s !". 2!nall "he !mage !s
selec"ed and d!splaed. :' "here !s an "e/" such as +h!"espace be'ore "he <?php "ag, or an o'
"he OC:$ 'unc"!ons produce an error "hen "he !mage +!ll no" d!spla. To debug "h!s, commen"
ou" "he header%& call "o see "he "e/" be!ng d!splaed be'ore "he !mage da"a.
'O)! and P'2S&' procedure!
Temporar .O-s can also be used "o pass da"a !n"o P.<4B. :7 parame"ers, or re"urned 'rom
OUT parame"ers. 3!&en a P.<4B. procedure "ha" accep"s a -.O- and !nser"s !" !n"o MM-T%-)
Script &A9' inproc"sDl
create or replace procedure inproc%pid in num/er+ pdata in /lo/& as
/egin
insert into m#/ta/ %/lo/id+ /lo/data& Calues %pid+ pdata&!
end!
()0
Bsing Large .5=ects in .C'1
/
show errors
PHP code "o pass a -.O- "o :7PROC +ould loo( l!(e)
Script &A?' inproc"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)m#/lo/id * 125!
)m#C * 0a Cer# large amount o' /inar# data0!
)s * oci$parse%)c+ 0/egin inproc%:m#/lo/id+ :m#/lo/data&! end!0&!
)lo/ * oci$new$descriptor%)c+ 345$L$K3I&!
oci$/ind$/#$name%)s+ 0:N;IK3I5L0+ )m#/lo/id&!
oci$/ind$/#$name%)s+ 0:N;IK3IL6:60+ )lo/+ -1+ 345$I$IK3I&!
)lo/-write:emporar#%)m#C+ 345$:-NE$IK3I&!
oci$e.ecute%)s&!
)lo/-close%&!
?
:' "he P.<4B. procedure re"urns a -.O- as an OUT parame"er)
Script &A/' outproc"sDl
create or replace procedure outproc%pid in num/er+ pdata out /lo/& as
/egin
select /lo/data into pdata 'rom m#/ta/ where /lo/id * pid!
end!
/
show errors
PHP code "o 'e"ch and d!spla "he -.O- +ould loo( l!(e)
Script &A8' outproc"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)m#/lo/id * 125!
)s * oci$parse%)c+ "/egin outproc%:m#/lo/id+ :m#/lo/data&! end!"&!
)lo/ * oci$new$descriptor%)c+ 345$L$K3I&!
oci$/ind$/#$name%)s+ 0:N;IK3I5L0+ )m#/lo/id&!
oci$/ind$/#$name%)s+ 0:N;IK3IL6:60+ )lo/+ -1+ 345$I$IK3I&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
i' %is$o/Wect%)lo/&& ( // protect against a MRKK K3I
)data * )lo/-load%&!
)lo/-'ree%&!
echo )data!
=
()1
Working With L.>s
?
Other 'O) 5ethod!
% number o' o"her me"hods on "he .O- descr!p"or allo+ see(!ng "o a spec!'!ed o''se",
e/por"!ng da"a d!rec"l "o '!le, eras!ng da"a, and cop!ng or compar!ng a .O-.
Th!s code sn!ppe" sho+s see(!ng "o "he 10
"h
pos!"!on !n "he resul" descr!p"or, and "hen
s"or!ng "he ne/" H0 b"es !n )result'
)arr90IK3IL6:60<-seek%10+ 345$7--G$7-:&!
)result * )arr90IK3IL6:60<-read%50&!
The .O- bu''er!ng me"hods allo+ +r!"es "o "he da"abase "o be de'erred and "hen e/pl!c!"l
'lushed. Th!s reduces "he number o' ne"+or( round?"r!ps "o "he da"abase, and allo+s "he
da"abase "o opera"e more e''!c!en"l.
The 'ull l!s" o' .O- me"hods and 'unc"!ons !s sho+n !n Table L. Chec( "he PHP manual 'or
usage.
)able 8' FOI +ethods and *unctions"
PHP 9unction or 5ethod ,ction
345-Ko/-close Close a .O- descr!p"or
345-Ko/-eo' Tes" 'or .O- end?o'?'!le
345-Ko/-erase ;rases a spec!'!ed par" o' "he .O-
345-Ko/-e.port
345-Ko/-write:oAile
0r!"e a .O- "o a '!le
345-Ko/-'lush 2lushes bu''er o' "he .O- "o "he ser&er
345-Ko/-'ree 2rees da"abase resources assoc!a"ed +!"h "he .O-
345-Ko/-getIu''ering Re"urns curren" s"a"e o' bu''er!ng 'or "he .O-
345-Ko/-import
345-Ko/-saCeAile
.oads da"a 'rom a '!le "o a .O-. OC:$ reads "he comple"e
'!le be'ore "rans'err!ng !" "o "he da"abase.
345-Ko/-load Re"urns .O- con"en"s
345-Ko/-read Re"urns par" o' "he .O-
345-Ko/-rewind Mo&es "he .O-Ks !n"ernal po!n"er bac( "o "he beg!nn!ng
345-Ko/-saCe 4a&es da"a "o "he .O-
345-Ko/-seek 4e"s "he .O-As !n"ernal pos!"!on po!n"er
()2
Bsing Large .5=ects in .C'1
PHP 9unction or 5ethod ,ction
345-Ko/-setIu''ering Changes .O-As curren" s"a"e o' bu''er!ng
345-Ko/-siXe Re"urns s!1e o' .O-
345-Ko/-tell Re"urns curren" po!n"er pos!"!on
345-Ko/-truncate Trunca"es a .O-
345-Ko/-write 0r!"es da"a "o "he .O-
345-Ko/-write:emporar# 0r!"es a "emporar .O-
oci$lo/$cop# Cop!es a .O-
oci$lo/$is$e"ual Compare "+o .O- loca"ors 'or e>ual!"
Wor=ing With )9I'E!
% -2:.; !s an Oracle large ob8ec" C.O-F da"a "pe 'or '!les s"ored ou"s!de "he da"abase. -2:.;s
are a hand +a 'or us!ng rela"!&el s"a"!c, e/"ernall crea"ed con"en". The are also use'ul 'or
load!ng "e/" or b!nar da"a !n"o Oracle "ables.
:' ou are e&alua"!ng 'ea"ures, compare -2:.;4 +!"h OracleAs ;/"ernal Table 'ea"ure, no"
co&ered !n "h!s boo(.
:n 4B. and P.<4B., a -2:.; !s accessed &!a a loca"or, +h!ch !s s!mpl a po!n"er "o "he
e/"ernal '!le. There are numerous pre?suppl!ed 'unc"!ons "ha" opera"e on -2:.; loca"ors.
To sho+ ho+ -2:.;s +or( !n PHP "h!s sec"!on crea"es a sample appl!ca"!on "ha" accesses
and d!splas a s!ngle !mage. The !mage +!ll no" be loaded !n"o "he da"abase bu" "he p!c"ure
descr!p"!on !s loaded so !" can be >uer!ed. The -2:.; allo+s "he !mage "o be rela"ed "o "he
descr!p"!on. %lso "he appl!ca"!on could be e/"ended !n 'u"ure "o use P.<4B. pac(ages "o read
and man!pula"e "he !mage.
:n "h!s e/ample, "he !mage da"a !s no" loaded and pr!n"ed !n PHP. :ns"ead, "he bro+ser !s
red!rec"ed "o "he !mage UR. o' "he e/"ernal '!le. Th!s s!gn!'!can"l reduces "he amoun" o' da"a
"ha" needs "o be handled b "he appl!ca"!on.
To allo+ %pache "o ser&e "he !mage, ed!" httpd"con* and map a UR. "o "he d!rec"or
con"a!n!ng "he '!le. 2or e/ample !' "he '!le !s ;t+p;c0"0pg add)
6lias /tmp/ "/tmp/"
<Lirector# "/tmp/"
3ptions Mone
6llow3Cerride Mone
3rder allow+den#
6llow 'rom all
</Lirector#
Us!ng ;t+p l!(e "h!s !s no" recommended 'or an"h!ng e/cep" "es"!ngT
Res"ar" %pache and use a bro+ser "o chec( "ha" http';;localhost;t+p;c0"0pg loads "he
p!c"ure !n ;t+p;c0"0pg"
(*3
Working With >8'L4s
:n Oracle, crea"e a D:R;CTORM al!as 'or ;t+p. Th!s !s OracleKs po!n"er "o "he opera"!ng
ss"em and 'orms par" o' each -2:.;. The d!rec"or mus" be on "he same mach!ne "ha" "he
da"abase ser&er runs on. Run 4B.SPlus as)
) s"lplus s#stemOlocalhost/,- O/'ile.s"l
0here b*ile"sDl !s)
Script &&A' b*ile"sDl
create director# :estLir 67 0/tmp0!
grant read on director# :estLir to hr!
connect hr/welcomeOlocalhost/,-
create ta/le Aile:est %
AileMum num/er primar# ke#+
AileLesc Carchar2%@0&+
5mage /'ile&!
Th!s g!&es "he HR user access "o "he ;t+p d!rec"or and crea"es a "able 2:.;T;4T con"a!n!ng a
'!le number !den"!'!er, a "e/" descr!p"!on o' "he '!le, and "he -2:.; !"sel'. The !mage da"a !s no"
loaded !n"o "h!s "ableG "he -2:.; !n "he "able !s a po!n"er "o "he '!le on our '!le ss"em.
PHP code "o !nser" "he !mage name !n"o "he 2:.;T;4T "able loo(s l!(e)
Script &&&' b*ileinsert"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)'num * 1!
)'dsc * "7ome description to search"!
)name * "cW.Wpg"!
)s * oci$parse%)c+ "insert into Aile:est %AileMum+ AileLesc+ 5mage& "
. "Calues %:'num+ :'dsc+ /'ilename%0:-7:L5B0+ :name&&"&!
oci$/ind$/#$name%)s+ ":'num"+ )'num+ -1+ 7SK:$5M:&!
oci$/ind$/#$name%)s+ ":'dsc"+ )'dsc+ -1+ 7SK:$4>B&!
oci$/ind$/#$name%)s+ ":name"+ )name+ -1+ 7SK:$4>B&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
oci$commit%)c&!
?
The /'ilename%& cons"ruc"or !nser"s !n"o "he -2:.;?"pe column us!ng "he T;4TD:R d!rec"or
al!as crea"ed earl!er. -!nd &ar!ables are used 'or e''!c!enc and secur!".
Th!s ne+ -2:.; can be >uer!ed bac( !n PHP)
Script &&2' b*ileDuery&"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)'num * 1!
)s * oci$parse%)c+ "select 5mage 'rom Aile:est where AileMum * :'num"&!
(*&
Bsing Large .5=ects in .C'1
oci$/ind$/#$name%)s+ ":'num"+ )'num&!
oci$e.ecute%)s&!
)row * oci$'etch$assoc%)s&!
)/' * )row905N6Y-0<! // :his is a IA5K- descriptor
echo "<pre"! Car$dump%)/'&! echo "</pre"!
?
Th!s d!splas "he -2:.; descr!p"or)
o/Wect%345-Ko/&Q1 %1& (
9"descriptor"<*
resource%U& o' t#pe %oci8 descriptor&
=
2or s!mpl!c!", "he >uer cond!"!on !s "he '!le number o' "he ne+ record. :n real l!'e !" m!gh" use
a regular e/press!on on "he 2:.;D;4C column l!(e)
select 5mage 'rom Aile:est where rege.p$like%AileLesc+ 0somepattern0&
:n "h!s e/ample "he '!le name !s needed so "he bro+ser can red!rec" "o a page sho+!ng "he
!mage. Un'or"una"el "here !s no d!rec" me"hod !n PHP "o ge" "he '!lename 'rom "he descr!p"or.
Ho+e&er, an Oracle procedure can be crea"ed "o do "h!s.
:ns"ead o' e/ecu"!ng "he >uer !n PHP and us!ng P.<4B. "o '!nd "he '!lename, a more
e''!c!en" me"hod !s "o do bo"h !n P.<4B.. Here an anonmous bloc( !s used. %l"erna"!&el, a
procedure could be used.
The pre&!ous >uer code !n b*ileDuery&"php can be replaced +!"h)
Script &&6' sho,pic"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+
0declare 0
. 0/$l /'ile!0
. 0da$l Carchar2%255&!0
. 0/egin 0
. 0select image into /$l 'rom 'iletest where 'ilenum * :'num!0
. 0d/ms$lo/.'ilegetname%/$l+ da$l+ :name&!0
. 0end!0&!
)'num * 1!
oci$/ind$/#$name%)s+ ":'num"+ )'num&!
oci$/ind$/#$name%)s+ ":name"+ )name+ 255+ 7SK:$4>B&!
oci$e.ecute%)s&!
header%"Kocation: http://localhost/tmp/)name"&!
?
The '!lename c0"0pg !s re"urned !n )name cour"es o' "he :name b!nd &ar!able argumen" "o "he
LIN7$K3I.A5K-Y-:M6N-%& 'unc"!on. The header%& 'unc"!on red!rec"s "he user "o "he !mage. :'
an "e/" !s pr!n"ed be'ore "he header%& !s ou"pu", "he HTTP headers +!ll no" be correc" and "he
(*(
Working With >8'L4s
!mage +!ll no" d!spla. :' ou ha&e problems, commen" ou" "he header%& call and echo )name
"o chec( !" !s &al!d.
-2:.;s are eas "o use !n P.<4B. because "he pre?suppl!ed D-M4N.O- pac(age has a
number o' use'ul 'unc"!ons. 2or e/ample LIN7$K3I.K36LAB3NA5K-%& reads -2:.; da"a 'rom "he
'!le ss"em !n"o a P.<4B. -.O- or C.O-. Th!s could be loaded !n"o a -.O- "able column,
man!pula"ed !n P.<4B., or e&en re"urned "o PHP us!ng OC:$Ks .O- 'ea"ures. %no"her e/ample
!s LIN7$K3I.A5K--,57:7%&, +h!ch can be used "o chec( +he"her "he 2:.;T;4T "able con"a!ns
re'erences "o !mages "ha" do no" e/!s".
-2:.;s are &er use'ul 'or man purposes !nclud!ng load!ng !mages !n"o "he da"abase, bu"
-.O-s ma be be""er !n some c!rcums"ances. Changes "o -2:.; loca"ors can be rolled bac( or
comm!""ed bu" s!nce "he '!les "hemsel&es are ou"s!de "he da"abase, -2:.; da"a does no"
par"!c!pa"e !n "ransac"!ons. Mou can ha&e dangl!ng re'erences "o -2:.;s because Oracle does
no" chec( "he &al!d!" o' -2:.;s un"!l "he da"a !s e/pl!c!"l read C"h!s allo+s ou "o pre?crea"e
-2:.;s or "o change "he phs!cal da"a on d!s(F. -2:.; da"a '!les are read?onl and canno" be
changed +!"h!n Oracle. 2!nall, -2:.;s need "o be bac(ed up manuall. -ecause o' "hese
po!n"s, "here m!gh" be "!mes ou should use -.O-s "o s"ore !mages !ns!de "he da"abase "o
ensure da"a and appl!ca"!on cons!s"enc bu" -2:.;s are "here !' ou +an" "hem.
(*)
Bsing Large .5=ects in .C'1
(**
CH,PTE: 1"
0SING 45' WITH O:,C'E ,N# PHP
-o"h Oracle and PHP H ha&e e/cellen" =M. capab!l!"!es. %ll ed!"!ons o' Oracle con"a!n +ha" !s
(no+n as D=M. D-E, "he =M. capab!l!"!es o' "he da"abase. 0hen "ables are crea"ed, =M. can
be s"ored !n l!near .O- 'orma", or accord!ng "o "he s"ruc"ure o' our =M. schema.
Th!s chap"er co&ers "he bas!cs o' us!ng =M. da"a +!"h Oracle and PHP. :" also sho+s ho+ "o
access da"a o&er HTTP d!rec"l 'rom "he da"abase.
9etching :elational :o;! a! 45'
One use'ul 'ea"ure o' =M. D- !s "ha" e/!s"!ng rela"!onal 4B. "ables can au"oma"!call be
re"r!e&ed as =M.)
Script &&5' x+l*rag"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)"uer# *
0select .mlelement%"-mplo#ees"+
.mlelement%"Mame"+ emplo#ees.last$name&+
.mlelement%"5d"+ emplo#ees.emplo#ee$id&& as result
'rom emplo#ees
where emplo#ee$id 2000!
)s * oci$parse%)c+ )"uer#&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$MRN&& (
'oreach %)row as )item& (
echo htmlentities%)item&."</r2n"!
=
=
?
The re"urned &alues are =M. 'ragmen"s, and no" 'ull 'ormed =M. documen"s. The ou"pu" !s)
<-mplo#ees<Mame>artstein</Mame<5d201</5d</-mplo#ees
<-mplo#ees<MameAa#</Mame<5d202</5d</-mplo#ees
<-mplo#ees<MameNaCris</Mame<5d20@</5d</-mplo#ees
<-mplo#ees<MameIaer</Mame<5d20D</5d</-mplo#ees
<-mplo#ees<Mame>iggins</Mame<5d205</5d</-mplo#ees
<-mplo#ees<MameYietX</Mame<5d20P</5d</-mplo#ees
(*+
Bsing 6:L With .racle and !H!
T!p) 0a"ch ou" 'or "he >uo"!ng o' =M. >uer!es. The =M. 'unc"!ons can ha&e embedded double?
>uo"es. Th!s !s "he e/ac" oppos!"e o' s"andard 4B. >uer!es, +h!ch can ha&e embedded s!ngle
>uo"es. Use a PHP H;R;DOC or 7O0DOC "o help cons"ruc" >uer!es.
There are a number o' o"her =M. 'unc"!ons "ha" can be s!m!larl used. 4ee "he Oracle
Database SEF Fanguage :e*erence.
9etching :o;! a! 9ull6 9or1ed 45'
%no"her +a "o crea"e =M. 'rom rela"!onal da"a !s "o use "he P.<4B. pac(age D-M4N=M.3;7.
Th!s pac(age re"urns a 'ull 'ormed =M. documen", +!"h "he =M. header.
Buer!es "ha" use D-M4N=M.3;7 re"urn a C.O- column, so "he resul" !n PHP needs "o be
"rea"ed as a .O- descr!p"or. There !s e''ec"!&el no leng"h l!m!" 'or C.O-s. The 'ollo+!ng
e/ample >uer!es "he '!rs" name o' emploees !n depar"men" I0 and s"ores "he =M. mar(ed?
up ou"pu" !n )m#lo/)
Script &&4' getx+l"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)"uer# * "select d/ms$.mlgen.get.ml%0
select 'irst$name
'rom emplo#ees
where department$id * @00& .ml
'rom dual"!
)s * oci$parse%)c+ )"uer#&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$MRN&!
). * )row90<-load%&! // treat result as a K3I descriptor
)row90<-'ree%&!
echo "<pre2n"!
echo htmlentities%).&!
echo "</pre2n"!
?
The ou"pu" !n a bro+ser !s)
<?.ml Cersion*"1.0"?
<B3?7-:
<B3?
<A5B7:$M6N-Len</A5B7:$M6N-
</B3?
<B3?
<A5B7:$M6N-6le.ander</A5B7:$M6N-
</B3?
(*-
8etching Ro/s as 8ully 8ormed 6:L
<B3?
<A5B7:$M6N-7helli</A5B7:$M6N-
</B3?
<B3?
<A5B7:$M6N-7igal</A5B7:$M6N-
</B3?
<B3?
<A5B7:$M6N-Yu#</A5B7:$M6N-
</B3?
<B3?
<A5B7:$M6N-Garen</A5B7:$M6N-
</B3?
</B3?7-:
0!ing the Si1ple45' Eten!ion in PHP
Mou can use PHPKs Si+ple<!F e/"ens!on "o con&er" =M. "o a PHP ob8ec". 2ollo+!ng on 'rom "he
pre&!ous e/ample "he >uer resul"s can be con&er"ed +!"h)
).o * simple.ml$load$string%%/inar#&).&!
7o"e "he cas" "o /inar# +h!ch ensures cons!s"en" encod!ng. The &alue !n ).o !s a PHP ob8ec")
o/Wect%7imple,NK-lement&Q2 %1& (
9"B3?"<*
arra#%P& (
90<*
o/Wect%7imple,NK-lement&Q@ %1& (
9"A5B7:$M6N-"<*
string%@& "Len"
=
91<*
o/Wect%7imple,NK-lement&QD %1& (
9"A5B7:$M6N-"<*
string%9& "6le.ander"
=
92<*
o/Wect%7imple,NK-lement&Q5 %1& (
9"A5B7:$M6N-"<*
string%P& "7helli"
=
9@<*
o/Wect%7imple,NK-lement&QP %1& (
9"A5B7:$M6N-"<*
string%5& "7igal"
=
9D<*
o/Wect%7imple,NK-lement&QU %1& (
9"A5B7:$M6N-"<*
string%@& "Yu#"
=
95<*
o/Wect%7imple,NK-lement&Q8 %1& (
(*0
Bsing 6:L With .racle and !H!
9"A5B7:$M6N-"<*
string%5& "Garen"
=
=
=
Th!s ob8ec" can be accessed +!"h arra !"era"ors and proper"!es)
'oreach %).o-B3? as )r& (
echo "Mame: " . )r-A5B7:$M6N- . "</r2n"!
=
Th!s ou"pu" 'rom "he loop !s)
Mame: Len
Mame: 6le.ander
Mame: 7helli
Mame: 7igal
Mame: Yu#
Mame: Garen
There are more e/amples o' us!ng 4!mple=M. +!"h =M. da"a !n PHPAs "es" su!"e under "he
ext;si+plex+l;tests d!rec"or o' "he PHP source code bundle.
To "rap and grace'ull handle 4!mple=M. errors use li/.ml$use$internal$errors%&)
<?php
li/.ml$use$internal$errors%true&!
).o * simple.ml$load$string%"not ,NK"&!
i' %8).o& (
echo ",NK load 'ailed:2n"!
'oreach%li/.ml$get$errors%& as )error&
echo " "+ )error-message!
=
?
Th!s g!&es)
,NK load 'ailed:
7tart tag e.pected+ 0<0 not 'ound
:' ou commen" ou" li/.ml$use$internal$errors%true& ou +ould see a normal +arn!ng
ra!sed)
E>E ?arning: simple.ml$load$string%&: -ntit#: line 1: parser error :
7tart tag e.pected+ 0<0 not 'ound in .ml.php on line @
9etching 45'T6pe Colu1n!
Da"a !n =M.Tpe columns can be longer "han OracleAs J000 b"e s"r!ng leng"h l!m!". 0hen
da"a !s 'e"ched as a s"r!ng, >uer!es ma 'a!l depend!ng on "he da"a leng"h. 2or e/ample, "he
R;4 column !n R;4OURC;N,:;0 C+h!ch !s a +a "o access "he Oracle =M. D- repos!"or 'rom
4B.F !s an =M.Tpe)
7SK descri/e resource$Ciew
Mame Mull? :#pe
(*1
8etching 6:LType Columns
---------------------- -------- ----------------------------
B-7 7;7.,NK:;E-%,NK7chema "http:
//.mlns.oracle.com/.d//,LIBe
source..sd" -lement "Besourc
e"&
6M;$E6:> Z6B4>6B2%D000&
B-75L B6?%1P&
PHP code "o >uer !" !s)
)s * oci$parse%)c+ 0select res 'rom resource$Ciew0&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$67734&& (
Car$dump%)row&!
=
Th!s !s l!(el "o success'ull 'e"ch and d!spla some ro+s be'ore 'a!l!ng)
. . .
<3wner7;7</3wner
<4reator7;7</4reator
<KastNodi'ier7;7</KastNodi'ier
<7chema-lementhttp://.mlns.oracle.com/.d//,LI7chema..sdQ/inar#</7chema-lement
<4ontents
</inar#DUD9DP@8@9P11P001 . . . 00@I<//inar#
</4ontents
</Besource
E>E ?arning: oci$'etch$arra#%&: 3B6-19011: 4haracter string /u''er too small
The 'a!lure happens because "he da"abase does a con&ers!on 'rom =M.Tpe "o a s"r!ng be'ore
re"urn!ng resul"s "o PHP. 0hen "he ro+s are shor" "here !s no error. Dur!ng "es"!ng ou could
be "r!c(ed !n"o "h!n(!ng our >uer +!ll al+as re"urn a comple"e se" o' ro+s.
Use "he ,NK:;E-.Y-:4K3IZ6K%& 'unc"!on "o 'orce =M.Tpe con&ers!on "o re"urn a C.O-,
a&o!d!ng "he s"r!ng s!1e l!m!" problem. 4"andard OC:$ C.O- me"hods can be used on "he
re"urned da"a)
Script &&9' x+ltype"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ 0select x-"t,pe.getc"obva"%res& 'rom resource$Ciew0&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$MRN&& (
Car$dump%)row90<-load%&&!
)row90<-'ree%&!
=
?
(*2
Bsing 6:L With .racle and !H!
In!erting Into 45'T6pe Colu1n!
Mou can !nser" or upda"e =M.Tpe columns b b!nd!ng as a C.O-.
Th!s +arehouse e/ample upda"es a "able +!"hou" an =M.4chema, and +h!ch s"ores "he
=M.Tpe column as a C.O-.
Script &&?' x+lcreate"sDl
create ta/le .warehouses %warehouse$id num/er+ warehouse$spec .mlt#pe&
.mlt#pe warehouse$spec store as clo/!
PHP code "o !nser" a +arehouse load!ng doc( !s)
Script &&/' x+linsert"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
// ,NK data to /e inserted
).ml *<<<-3A
<?.ml Cersion*"1.0"?
<?arehouse
<?arehouse5d1</?arehouse5d
<?arehouseMame7outhlake+ :e.as</?arehouseMame
<Iuilding3wned</Iuilding
<6rea25000</6rea
<Locks2</Locks
<Lock:#peBear load</Lock:#pe
<?ater6ccesstrue</?ater6ccess
<Bail6ccessM</Bail6ccess
<Earking7treet</Earking
<Z4learance10</Z4learance
</?arehouse
-3A!
// 5nsert new ,NK data using a temporar# 4K3I
)s * oci$parse%)c+
"insert into .warehouses %warehouse$id+ warehouse$spec&
Calues %:id+ ,NK:#pe%:clo/&&"&!
)id * 1!
oci$/ind$/#$name%)s+ 0:id0+ )id&!
)lo/ * oci$new$descriptor%)c+ 345$L$K3I&!
oci$/ind$/#$name%)s+ 0:clo/0+ )lo/+ -1+ 345$I$4K3I&!
)lo/-write:emporar#%).ml&!
oci$e.ecute%)s&!
)lo/-close%&!
?
PHP code "o upda"e "he number o' a&a!lable +arehouse doc(s !s)
Script &&8' x+lupdate"php
<?php
(+3
'nserting 'nto 6:LType Columns
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ 0select .mlt#pe.getclo/Cal%warehouse$spec&
'rom .warehouses where warehouse$id * :id0&!
)id * 1!
)r * oci$/ind$/#$name%)s+ 0:id0+ )id&!
oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$MRN&!
// Nanipulate the data using 7imple,NK
)s. * simple.ml$load$string%%/inar#&)row90<-load%&&!
)row90<-'ree%&!
)s.-Locks -* 1! // change the data
// 5nsert changes using a temporar# 4K3I
)s * oci$parse%)c+ 0update .warehouses
set warehouse$spec * ,NK:#pe%:clo/&
where warehouse$id * :id0&!
oci$/ind$/#$name%)s+ 0:id0+ )id&!
)lo/ * oci$new$descriptor%)c+ 345$L$K3I&!
oci$/ind$/#$name%)s+ 0:clo/0+ )lo/+ -1+ 345$I$4K3I&!
)lo/-write:emporar#%$sx<?asX-"()&!
oci$e.ecute%)s&!
)lo/-close%&!
?
The )s.-as,ml%& me"hod con&er"s "he 4!mple=M. ob8ec" "o "he "e/" represen"a"!on used "o
upda"e "he "able. % "emporar .O- !s crea"ed "o pass "he ne+ =M. &alue "o "he da"abase.
%'"er runn!ng "he PHP scr!p", >uer!ng "he record !n 4B.SPlus sho+s "he number o' doc(s
has been decremen"ed 'rom 2 "o 1)
7SK set long 1000 pagesiXe 100
7SK select warehouse$spec 'rom .warehouses!
Th!s g!&es)
?6B->3R7-$7E-4
---------------------------------------------------
<?.ml Cersion*"1.0"?
<?arehouse
<?arehouse5d1</?arehouse5d
<?arehouseMame7outhlake+ :e.as</?arehouseMame
<Iuilding3wned</Iuilding
<6rea25000</6rea
<Locks1</Locks
<Lock:#peBear load</Lock:#pe
<?ater6ccesstrue</?ater6ccess
<Bail6ccessM</Bail6ccess
<Earking7treet</Earking
<Z4learance10</Z4learance
</?arehouse
(+&
Bsing 6:L With .racle and !H!
4ee #sing <!F in SEF State+ents !n "he Oracle Database SEF :e*erence 'or more d!scuss!on
o' =M.Tpe.
9etching an 45'T6pe *ro1 a P'2S&' 9unction
The Y-:4K3IZ6K%& 'unc"!on !s also use'ul +hen "r!ng "o ge" an =M.Tpe 'rom a s"ored P.<4B.
'unc"!on. 2!le x+l*unc"sDl crea"es a s!mple P.<4B. 'unc"!on re"urn!ng =M.Tpe >uer da"a 'or a
g!&en !den"!'!er &alue.
Script &2A' x+l*unc"sDl
drop ta/le m#ta/!
create ta/le m#ta/ %id num/er+ data .mlt#pe&!
insert into m#ta/ %id+ data& Calues %1+ 0<somethingm#data</something0&!
create or replace 'unction m#'%p$id num/er& return .mlt#pe as
loc .mlt#pe!
/egin
select data into loc 'rom m#ta/ where id * p$id!
return loc!
end!
/
To access "h!s 'unc"!on !n PHP, use Y-:4K3IZ6K%& and b!nd a .O- descr!p"or "o "he re"urn
&alue. OC:$ .O- me"hods l!(e load%& can be used on "he descr!p"or)
Script &2&' x+l*unc"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)/d * oci$new$descriptor%)c+ 345$L$K3I&!
)s * oci$parse%)c+ "/egin :/C :* m#'%1&.getc"obva"()! end!"&!
oci$/ind$/#$name%)s+ ":/C"+ )/d+ -1+ 345$I$4K3I&!
oci$e.ecute%)s&!
echo htmlentities%)/d-load%&&! // Erint output
)/d-close%&!
?
The ou"pu" !s "he e/pec"ed)
<somethingm#data</something
4&uer6 45' &uer6 'anguage
OracleKs suppor" 'or =Buer +as !n"roduced !n Oracle Da"abase 10g Release 2. % bas!c
=Buer "o re"urn "he records 'rom "he ;MP.OM;;4 "able !s)
'or )i in ora:Ciew%"emplo#ees"& return )i
(+(
6;uery 6:L ;uery Language
:n use, "h!s =Buer sn"a/ !s embedded !n a spec!al 7-K-4:)
select column$Calue 'rom .mlta/le%0'or )i in ora:Ciew%"emplo#ees"& return )i0&
The d!''eren" >uo"!ng s"les used b 4B. and =Buer need care'ul a""en"!on !n PHP. :" can be
coded)
Script &22' xDuery"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)." * 0'or )i in ora:Ciew%"emplo#ees"& return )i0!
)"uer# * 0select column$Calue 'rom .mlta/le%200.).".020&0!
)s * oci$parse%)c+ )"uer#&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$MRN&& (
'oreach %)row as )item& (
echo htmlentities%)item&." "!
=
=
?
The >uer could also be !n a s!ngle PHP 7O0DOC)
)"uer# * <<<0-ML0
select column$Calue 'rom .mlta/le%0'or )i in ora:Ciew%"emplo#ees"& return )i0&
-ML!
7o"e "here canno" be +h!"espace on "he las" l!ne be'ore or a'"er "he "o(en -ML!
Pr!or "o PHP H.I, use H;R;DOC sn"a/ and escape =Buer &ar!ables l!(e )i +!"h a
bac(slash.
0h!che&er >uer 'orma" ou choose, "able ro+s are au"oma"!call +rapped !n "ags and
re"urned)
<B3?
<-NEK3;--$5L100</-NEK3;--$5L
<A5B7:$M6N-7teCen</A5B7:$M6N-
<K67:$M6N-Ging</K67:$M6N-
<-N65K7G5MY</-N65K
<E>3M-$MRNI-B515.12@.D5PU</E>3M-$MRNI-B
<>5B-$L6:-198U-0P-1U</>5B-$L6:-
<T3I$5L6L$EB-7</T3I$5L
<76K6B;2D000</76K6B;
<L-E6B:N-M:$5L90</L-E6B:N-M:$5L
</B3?
`
<B3?
<-NEK3;--$5L20P</-NEK3;--$5L
<A5B7:$M6N-?illiam</A5B7:$M6N-
<K67:$M6N-YietX</K67:$M6N-
<-N65K?Y5-:]</-N65K
(+)
Bsing 6:L With .racle and !H!
<E>3M-$MRNI-B515.12@.8181</E>3M-$MRNI-B
<>5B-$L6:-199D-0P-0U</>5B-$L6:-
<T3I$5L64$6443RM:</T3I$5L
<76K6B;8@00</76K6B;
<N6M6Y-B$5L205</N6M6Y-B$5L
<L-E6B:N-M:$5L110</L-E6B:N-M:$5L
</B3?
Mou can also use B-:RBM5MY 43M:-M: "o re"urn a s!ngle documen" node)
)"uer# * <<<0-ML0
select .ml"uer#%0'or )i in ora:Ciew%"hr"+ "locations"&/B3?
return )i/45:;0
returning content& 'rom dual
-ML!
2or bo"h ,NK:6IK-%& and ,NKSR-B;%& PHP OC:$ +!ll genera"e an O:A3&8A&&' -haracter string
bu**er too s+all error 'or resul"s se"s b!gger "han a se&eral "housand b"es. To pre&en" "h!s,
use "he ,NK:;E-.Y-:4K3IZ6K%& 'unc"!on, 'or e/ample)
)"uer# * <<<0-ML0
select .mlt#pe.getclo/Cal%column$Calue&
'rom .mlta/le%0'or )i in ora:Ciew%"emplo#ees"& return )i0&
-ML!
and
)"uer# * <<<0-ML0
select .mlt#pe.getclo/Cal%.ml"uer#%0'or )i in ora:Ciew%"hr"+
"locations"&/B3? return )i/45:;0
returning content&& 'rom dual
-ML!
The re"urned da"a !s a .O- loca"or and so "he 'e"ch needs .O- me"hods, such as load%&)
)s * oci$parse%)c+ )"uer#&!
oci$e.ecute%)s&!
while %)row * oci$'etch$arra#%)s+ 345$MRN&& (
Car$dump%)row90<-load%&&!
)row90<-'ree%&!
=
,cce!!ing #ata O-er HTTP With 45' #)
=M. D- allo+s ou "o access da"a d!rec"l &!a HTTP, 2TP or 0ebD%,. The Oracle 7e"+or(
l!s"ener +!ll handle all "hese re>ues"s. %s an e/ample o' HTTP access, use "he P.<4B.
D-M4N=D- pac(age "o crea"e a resource, +h!ch here !s some s!mple "e/")
Script &26' xdb"sDl
declare
res /oolean!
/egin
/egin
-- delete i' it alread# e.ists
(+*
Accessing Data .$er HTT! With 6:L D>
d/ms$.d/.deleteBesource%0/pu/lic/test1.t.t0&!
e.ception when others then
null!
end!
-- create the 'ile - don_t 'orget to commit
res :* d/ms$.d/.createBesource%0/pu/lic/test1.t.t0+ 0the te.t to store0&!
commit!
end!
/
2or "es"!ng, remo&e access con"rol on "he publ!c resource)
7SK connect s#stem/s#stempwd
7SK alter user anon#mous identi'ied /# anon#mous account unlock!
The '!le can no+ be accessed 'rom a bro+ser Cor PHP appl!ca"!onF us!ng)
http://localhost:8080/pu/lic/test1.t.t
Mou ma need "o en"er da"abase creden"!als such as HR and HRAs pass+ord +hen promp"ed !n
"he bro+ser.
There !s e/"ens!&e Oracle documen"a"!on on =M. D- !n "he Oracle manuals, and on "he
Oracle Technolog ne"+or( a"
http://www.oracle.com/technetwork/data/ase/'eatures/.mld//.
(++
Bsing 6:L With .racle and !H!
(+-
PHP CONNECTION POO'ING ,N# HIGH
,<,I',)I'ITG
Th!s chap"er d!scusses "+o da"abase 'ea"ures suppor"ed b PHP OC:$ "ha" !mpro&e scalab!l!"
and h!gh a&a!lab!l!")
Da"abase Res!den" Connec"!on Pool!ng CDRCPF) a 'ea"ure !n"roduced !n Oracle Da"abase
11g "ha" addresses scalab!l!" re>u!remen"s !n en&!ronmen"s re>u!r!ng large numbers o'
connec"!ons +h!le us!ng m!n!mal da"abase resources. %n Oracle benchmar( sho+ed
20,000 connec"!ons be!ng suppor"ed on a small commod!" mach!ne +!"h 23- o' R%M.
2as" %ppl!ca"!on 7o"!'!ca"!on C2%7F) 0eb appl!ca"!ons "ha" run !n h!gh a&a!lab!l!"
con'!gura"!ons such as +!"h Oracle Real %ppl!ca"!on Clus"ers CR%CF or Da"a 3uard Phs!cal
4"and?- can "a(e ad&an"age o' 2%7 e&en"s !n PHP "o allo+ appl!ca"!ons "o respond
>u!c(l "o da"abase node 'a!lures.
The 'ea"ures are usable separa"el or "oge"her. PHP H.I on+ards COC:$ 1.I on+ardsF has
!mmed!a"e suppor" 'or "hem.
#ata$a!e :e!ident Connection Pooling
Oracle Da"abase 11g DRCP addresses scalab!l!" re>u!remen"s !n en&!ronmen"s re>u!r!ng large
numbers o' connec"!ons +h!le us!ng m!n!mal da"abase resources. DRCP allo+s pool!ng o' a se"
o' ded!ca"ed da"abase ser&er processes C(no+n as pooled serversF, +h!ch can be shared
across mul"!ple appl!ca"!ons runn!ng on "he same or se&eral hos"s. % connec"!on bro(er
process manages "he pooled ser&ers a" "he da"abase !ns"ance le&el. DRCP !s a con'!gurable
'ea"ure chosen a" program run"!me, allo+!ng "rad!"!onal and DRCP?based connec"!on
arch!"ec"ures "o be !n concurren" use
0!"hou" DRCP, each PHP process crea"es and des"ros da"abase ser&ers +hen connec"!ons
are opened and closed. Th!s can be e/pens!&e and cr!ppl!ng "o h!gh scalab!l!". Or
al"erna"!&el, PHP processes use pers!s"en" connec"!ons, (eep!ng connec"!ons open e&en
+hen "he are no" process!ng an user scr!p"s. Th!s remo&es connec"!on crea"!on and
des"ruc"!on cos"s bu" !ncurs unnecessar memor o&erhead !n "he da"abase, as sho+n !n
2!gure P0.
(+0
!H! Connection !ooling and High A$aila5ility
Ho; #:CP Wor=!
The arch!"ec"ure o' DRCP !s sho+n !n 2!gure P1. % connec"!on bro(er accep"s !ncom!ng
connec"!on re>ues"s 'rom PHP processes and ass!gns each a 'ree ser&er !n "he DRCP pool.
;ach PHP process "ha" !s e/ecu"!ng a PHP scr!p" commun!ca"es +!"h "h!s Oracle ser&er un"!l
"he connec"!on !s released. Th!s release can be e/pl!c!" +!"h oci$close%& or !" +!ll happen
au"oma"!call a" "he end o' "he scr!p". 0hen "he connec"!on !s released, "he ser&er process !s
re"urned "o "he pool and "he PHP process (eeps a l!n( onl "o "he connec"!on bro(er. %c"!&e
pooled ser&ers con"a!n "he Process 3lobal %rea CP3%F and "he user sess!on da"a. :dle ser&ers
!n "he pool can op"!onall re"a!n "he user sess!on 'or reuse b subse>uen" pers!s"en" PHP
connec"!ons.
0hen "he number o' pers!s"en" connec"!ons !s less "han "he number o' pooled ser&ers, a
Dded!ca"ed op"!m!1a"!onE a&o!ds unnecessar!l re"urn!ng ser&ers "o "he pool +hen a PHP
connec"!on !s closed. :ns"ead, "he ded!ca"ed assoc!a"!on be"+een "he PHP process and "he
ser&er !s (ep" !n an"!c!pa"!on "ha" "he PHP process +!ll >u!c(l become ac"!&e aga!n. :' PHP
scr!p"s are e/ecu"ed b numerous +eb ser&ers, "he DRCP pool can gro+ "o !"s ma/!mum s!1e
Calbe!" "p!call a rela"!&el small s!1eF, e&en !' "he ra"e o' !ncom!ng user re>ues"s !s lo+. ;ach
PHP process, e!"her bus or no+ !dle, +!ll be a""ached "o !"s o+n pooled ser&er. 0hen "he pool
reaches !"s ma/!mum s!1e, ano"her PHP process "ha" needs a pooled ser&er +!ll cause an !dle
ser&er !n "he pool "o be made a&a!lable 'or !mmed!a"e reuse.
(+1
(igure ?A' Without D:-P, idle persistent connections *ro+ PHP still
consu+e database resources"
Data5ase Resident Connection !ooling
The pool s!1e and number o' connec"!on bro(ers are con'!gurable. There !s al+as a" leas" one
connec"!on bro(er per da"abase !ns"ance +hen DRCP !s enabled. %lso, a" an "!me, around H^
o' "he curren" pooled ser&ers are reser&ed 'or au"hen"!ca"!ng ne+ PHP connec"!ons.
%u"hen"!ca"!on !s per'ormed +hen a PHP process es"abl!shes a connec"!on "o "he connec"!on
bro(er.
DRCP boos"s "he scalab!l!" o' "he da"abase and "he +eb ser&er "!er because connec"!ons
"o "he da"abase are held a" m!n!mal cos". Da"abase memor !s onl used b "he pooled
ser&ers, and scal!ng can be e/pl!c!"l con"rolled b DRCP "un!ng op"!ons.
0!"h "he !n"roduc"!on o' pooled ser&ers used b DRCP, "here are no+ "hree "pes o'
da"abase ser&er process models "ha" Oracle appl!ca"!ons can use) ded!ca"ed ser&ers, shared
ser&ers and pooled ser&ers.
)able &A' Di**erences bet,een dedicated servers, shared servers, and pooled servers"
#edicated Ser-er! Shared Ser-er! Pooled Ser-er!
0hen "he PHP connec"!on !s
crea"ed, a ne"+or(
connec"!on "o a ded!ca"ed
ser&er process and
assoc!a"ed sess!on are
crea"ed.
0hen "he PHP connec"!on !s
crea"ed, a ne"+or(
connec"!on "o "he
d!spa"cher process !s
es"abl!shed. % sess!on !s
crea"ed !n "he 43%.
0hen "he PHP connec"!on !s
crea"ed, a ne"+or( connec"!on "o
"he connec"!on bro(er !s
es"abl!shed.
(+2
(igure ?&' D:-P Architecture"
!H! Connection !ooling and High A$aila5ility
#edicated Ser-er! Shared Ser-er! Pooled Ser-er!
%c"!&!" on a connec"!on !s
handled b "he ded!ca"ed
ser&er.
;ach ac"!on on a connec"!on
goes "hrough "he
d!spa"cher, +h!ch hands "he
+or( "o a shared ser&er.
%c"!&!" on a connec"!on +a(es
"he bro(er, +h!ch hands "he
ne"+or( connec"!on "o a pooled
ser&er. The ser&er "hen handles
subse>uen" re>ues"s d!rec"l, 8us"
l!(e a ded!ca"ed ser&er.
4cr!p"s e/ecu"!ng bu" +!"h
!dle PHP connec"!ons hold a
ser&er process and sess!on
resources.
4cr!p"s e/ecu"!ng bu" +!"h
!dle PHP connec"!ons hold
sess!on resources bu" no" a
ser&er process.
4cr!p"s e/ecu"!ng bu" +!"h !dle
PHP connec"!ons hold a ser&er
process and sess!on resources.
Clos!ng a PHP connec"!on
causes "he sess!on "o be
'reed and "he ser&er process
"o be "erm!na"ed.
Clos!ng a PHP connec"!on
causes "he sess!on "o be
'reed.
Clos!ng a PHP connec"!on
op"!onall causes "he sess!on "o
be des"roed. The pooled ser&er
!s released "o "he pool. % ne"+or(
connec"!on "o "he connec"!on
bro(er !s re"a!ned.
Memor usage !s
propor"!onal "o "he number
o' ser&er processes and
sess!ons. There !s one ser&er
and one sess!on 'or each
PHP connec"!on.
Memor usage !s
propor"!onal "o "he sum o'
"he shared ser&ers and
sess!ons. There !s one
sess!on 'or each PHP
connec"!on.
Memor usage !s propor"!onal "o
"he number o' pooled ser&ers
and "he!r sess!ons. There !s one
sess!on 'or each pooled ser&er.
Pooled ser&ers used b PHP are s!m!lar !n beha&!or "o ded!ca"ed ser&ers. %'"er connec"!on, PHP
d!rec"l commun!ca"es +!"h "he pooled ser&er 'or all da"abase opera"!ons.
PHP OCI. Connection! and #:CP
The !mplemen"a"!on o' "he connec"!on 'unc"!ons, oci$connect%&, oci$new$connect%&, and
oci$pconnect%& +as re+or(ed !n OC:$ 1.I. %ll "hree bene'!" 'rom us!ng DRCP. Table 11
compares ded!ca"ed and pooled ser&ers. 4hared ser&ers are no" sho+n bu" beha&e s!m!larl
"o ded!ca"ed ser&ers +!"h "he e/cep"!on "ha" onl "he sess!on and no" "he ser&er !s des"roed
+hen a connec"!on !s closed.
(-3
Data5ase Resident Connection !ooling
)able &&' Iehavior o* O-./ connection *unctions *or Dedicated and Pooled Servers"
OCI. 9unction #edicated Ser-er! Pooled Ser-er!
oci$connect%& Crea"es a PHP connec"!on "o
"he da"abase us!ng a
ded!ca"ed ser&er. The
connec"!on !s cached !n "he
PHP process 'or reuse b
subse>uen" oci$connect%&
calls !n "he same scr!p". %" "he
end o' "he scr!p" or +!"h
oci$close%&, "he connec"!on !s
closed and "he ser&er process
and sess!on are des"roed.
3e"s a pooled ser&er 'rom "he
DRCP pool and crea"es a brand
ne+ sess!on. 4ubse>uen"
oci$connect%& calls !n "he same
scr!p" use "he same connec"!on.
0hen "he scr!p" comple"es, or
oci$close%& !s called, "he
sess!on !s des"roed and "he
pooled ser&er !s a&a!lable 'or
o"her PHP connec"!ons "o use.
oci$new$connect%& 4!m!lar "o oci$connect%&
abo&e, bu" an !ndependen"
ne+ PHP connec"!on and
ser&er process !s crea"ed e&er
"!me "h!s 'unc"!on !s called,
e&en +!"h!n "he same scr!p".
%ll PHP connec"!ons and "he
da"abase ser&ers are closed
+hen "he scr!p" ends or +!"h
oci$close%&. 4ess!ons are
des"roed a" "ha" "!me.
4!m!lar "o oci$connect%& abo&e,
bu" an !ndependen" ser&er !n "he
pool !s used and a ne+ sess!on
!s crea"ed each "!me "h!s
'unc"!on !s called !n "he same
scr!p". %ll sess!ons are des"roed
a" "he end o' "he scr!p" or +!"h
oci$close%&. The pooled ser&ers
are made a&a!lable 'or o"her
connec"!ons "o use.
oci$pconnect%& Crea"es a pers!s"en" PHP
connec"!on +h!ch !s cached !n
"he PHP process. The da"abase
connec"!on !s no" closed a" "he
end o' "he scr!p". 0hen no
scr!p" !s e/ecu"!ng, an !dle PHP
process s"!ll holds "he ser&er
process and sess!on resource.
The ser&er and sess!on are
a&a!lable 'or reuse b
subse>uen" oci$pconnect%&
calls "ha" pass "he same
creden"!als !n an scr!p"
handled b "h!s PHP process.
Crea"es a pers!s"en" PHP
connec"!on. Call!ng oci$close%&
releases "he connec"!on. Th!s
ma(es "he ser&er and !"s !n"ac"
sess!on a&a!lable !n "he pool 'or
reuse b o"her PHP processes. :'
oci$close%& !s no" called, "hen
"h!s connec"!on release happens
a" "he end o' "he scr!p". 0hen
no scr!p" !s e/ecu"!ng, an !dle
PHP process re"a!ns onl an
au"hen"!ca"ed ne"+or(
connec"!on "o "he bro(er.
4ubse>uen" oci$pconnect%&
calls pass!ng "he same
creden"!als !n scr!p"s handled b
"h!s PHP process reuse "he
e/!s"!ng ne"+or( connec"!on "o
>u!c(l ge" a ser&er and sess!on
'rom "he pool
(-&
!H! Connection !ooling and High A$aila5ility
0!"h DRCP, all "hree connec"!on 'unc"!ons sa&e on "he cos" o' au"hen"!ca"!on and bene'!" 'rom
"he ne"+or( connec"!on "o "he connec"!on bro(er be!ng ma!n"a!ned, e&en 'or connec"!ons "ha"
are DclosedE 'rom PHPKs po!n" o' &!e+. The also bene'!" 'rom ha&!ng pre?spa+ned ser&er
processes !n "he DRCP pool.
The oci$pconnect%& 'unc"!on reuses sess!ons, allo+!ng e&en grea"er scalab!l!". The non?
pers!s"en" connec"!on 'unc"!ons crea"e and des"ro ne+ sess!ons each "!me "he are used,
allo+!ng less shar!ng a" "he cos" o' reduced per'ormance.
O&erall, a'"er a br!e' +arm?up per!od 'or "he pool, DRCP allo+s reduced connec"!on "!mes
!n add!"!on "o "he reuse bene'!"s o' pool!ng.
When to u!e #:CP
DRCP !s "p!call pre'erred 'or PHP appl!ca"!ons +!"h a large number o' connec"!ons. 4hared
ser&ers can be use'ul 'or a med!um number o' connec"!ons !' DRCP !s no" a&a!lable. Ded!ca"ed
sess!ons are pre'erred 'or small numbers o' connec"!ons. The "hreshold s!1es are rela"!&e "o
"he amoun" o' memor a&a!lable on "he da"abase hos".
DRCP pro&!des "he 'ollo+!ng ad&an"ages)
:" enables resource shar!ng among mul"!ple cl!en" appl!ca"!ons and mul"!ple m!ddle?"!er
appl!ca"!on ser&ers.
:" !mpro&es scalab!l!" o' da"abases and appl!ca"!ons b reduc!ng resource usage on "he
da"abase hos".
DRCP can be used !')
PHP appl!ca"!ons mos"l use "he same da"abase creden"!als 'or all connec"!ons.
The appl!ca"!ons ac>u!re a da"abase connec"!on, +or( on !" 'or a rela"!&el shor" dura"!on,
and "hen release !".
Connec"!ons loo( !den"!cal !n "erms o' sess!on se""!ngs, 'or e/ample da"e 'orma" se""!ngs
and P.<4B. pac(age s"a"e.
These are all "p!call "rue 'or PHP appl!ca"!ons.
2or pers!s"en" PHP connec"!ons, normal ded!ca"ed ser&ers can be 'as"es". There !s no
bro(er or d!spa"cher o&erhead. The da"abase ser&er process !s al+as connec"ed and
a&a!lable +hene&er "he PHP process needs !". -u" as "he number o' connec"!ons !ncreases, "he
memor cos" o' (eep!ng connec"!ons open >u!c(l reduces e''!c!enc o' "he da"abase ss"em.
2or non?pers!s"en" PHP connec"!ons, DRCP can be 'as"es" because "he use o' pooled ser&er
processes remo&es "he need 'or PHP connec"!ons "o crea"e and des"ro processes, and
remo&es "he need "o re?au"hen"!ca"e 'or each connec" call.
Cons!der an appl!ca"!on !n +h!ch "he memor re>u!red 'or each sess!on !s J00 6-. On a I2
b!" opera"!ng ss"em "he memor re>u!red 'or each ser&er process could be, 'or e/ample, J
M-, and DRCP could use IH 6- per connec"!on Cmos"l !n "he connec"!on bro(erF. :' "he
number o' pooled ser&ers !s con'!gured a" 100, "he number o' shared ser&ers !s con'!gured a"
100, and "he deploed appl!ca"!on crea"es H000 PHP connec"!ons, "hen "he memor used b
each "pe o' ser&er !s es"!ma"ed !n Table 10.
(-(
Data5ase Resident Connection !ooling
)able &2' Exa+ple database host +e+ory use *or dedicated, shared and pooled servers"
#edicated Ser-er! Shared Ser-er! Pooled Ser-er!
Da"abase 4er&er
Memor
H000 S J M- 100 S J M- 100 S J M-
4ess!on Memor H000 S J00 6- H000 S J00 6-
7o"e) 2or 4hared
4er&ers, sess!on
memor !s alloca"ed
'rom "he 43%.
100 S J00 6-
DRCP Connec"!on
-ro(er O&erhead
H000 S IH 6-
To"al Memor (& ,> (D) ,> -&3 :>
There !s a s!gn!'!can" memor sa&!ng +hen us!ng DRCP.
;&en !' su''!c!en" memor !s a&a!lable "o run !n ded!ca"ed mode, DRCP can s"!ll be a &!able
op"!on !' "he PHP appl!ca"!on needs da"abase connec"!ons 'or onl shor" per!ods o' "!me. :n "h!s
case "he memor sa&ed b us!ng DRCP can be used "o+ards !ncreas!ng "he 43%, "hereb
!mpro&!ng o&erall per'ormance.
Pool!ng !s a&a!lable +hen connec"!ng o&er TCP<:P +!"h user!d<pass+ord based da"abase
au"hen"!ca"!on. :" !s no" a&a!lable us!ng OracleAs Dbe>uea"hE connec"!ons.
0!"h Oracle 11.2, pooled connec"!ons can "a(e ad&an"age o' OracleAs Cl!en" Resul" Cache
'ea"ure.
Sharing the Ser-er Pool
DRCP guaran"ees "ha" pooled ser&ers and sess!ons !n!"!all used b one da"abase user are
onl e&er reusable b connec"!ons +!"h "ha" same user !den"!'!er. DRCP also 'ur"her par"!"!ons
"he pool !n"o log!cal groups or Dconnec"!on classesE. % connec"!on class !s a user chosen name
se" +!"h oci/"connection=class !n "he php"ini con'!gura"!on '!le.
4ess!on?spec!'!c a""r!bu"es, l!(e "he da"e 'orma" or an e/pl!c!" role, ma be re?usable b
an connec"!on !n a par"!cular appl!ca"!on. 4ubse>uen" pers!s"en" connec"!ons +!ll reuse "he
sess!on and !nher!" "hose se""!ngs !' "he username and connec"!on class are "he same as "he
pre&!ous connec"!on.
%ppl!ca"!ons "ha" need d!''eren" s"a"e !n "he sess!on memor should use d!''eren"
usernames and<or connec"!on classes.
(-)
!H! Connection !ooling and High A$aila5ility
2or e/ample, appl!ca"!ons !n a su!"e called RPT ma be +!ll!ng "o share pooled ser&ers
be"+een "hemsel&es bu" no" +!"h appl!ca"!ons !n a su!"e called HR. %n e/ample o' d!''eren"
connec"!on classes and "he resul"!ng log!cal par"!"!on!ng o' "he DRCP ser&er pool !s sho+n !n
"he pre&!ous '!gure. Connec"!ons +!"h "he same username and connec"!on class 'rom an hos"
+!ll share "he same sub?pool o' ser&ers. :' "here are no 'ree pooled ser&ers ma"ch!ng a re>ues"
'or a user!d !n "he spec!'!ed connec"!on class, and !' "he pool !s alread a" !"s ma/!mum s!1e,
"hen an !dle ser&er !n "he pool +!ll be used and a ne+ sess!on crea"ed 'or !". :' "he ser&er
or!g!nall belonged "o a d!''eren" connec"!on class, "he curren" sess!on +!ll be des"roed, "he
ser&er +!ll m!gra"e "o "he ne+ class, and a ne+ sess!on +!ll be crea"ed. :' "here are no pooled
ser&ers a&a!lable, "he connec"!on re>ues" +a!"s 'or one "o become a&a!lable. Th!s allo+s "he
da"abase "o con"!nue +!"hou" becom!ng o&erloaded.
The connec"!on class should be se" "o "he same &alue 'or each !ns"ance o' PHP runn!ng "he
same appl!ca"!on +here shar!ng o' pooled connec"!ons !s des!red. :' no connec"!on class !s
spec!'!ed, each +eb ser&er process +!ll ha&e a un!>ue, ss"em genera"ed class name, l!m!"!ng
shar!ng o' connec"!ons "o each process, and a''ec"!ng o&erall per'ormance.
:' DRCP !s used bu" sess!on shar!ng !s no" des!rable under an cond!"!on, use
oci$connect%& or oci$new$connect%& +h!ch recrea"e "he sess!on each "!me.
%l"hough sess!on da"a ma be reused b subse>uen" pers!s"en" connec"!ons, "ransac"!ons
do no" span connec"!ons across scr!p"s. Uncomm!""ed da"a +!ll be rolled bac( a" "he end o' a
PHP scr!p".
0!ing #:CP in PHP
Us!ng DRCP +!"h PHP appl!ca"!ons !n&ol&es "he 'ollo+!ng s"eps)
(-*
(igure ?2' )he D:-P pool is logically partitioned by userna+e and connection class"
Bsing DRC! in !H!
1. Con'!gur!ng and enabl!ng "he pool.
2. Con'!gur!ng PHP.
I. Deplo!ng "he appl!ca"!on.
PHP appl!ca"!ons deploed as %pache modules, 2as"C3:, C3: and s"andalone appl!ca"!ons can
bene'!" 'rom DRCP. PHP appl!ca"!ons deploed as %pache modules or +!"h 2as"C3: ga!n mos",
s!nce "he PHP processes are long runn!ng and rema!n connec"ed "o "he connec"!on bro(er o&er
mul"!ple scr!p" e/ecu"!ons. Th!s le"s "hem "a(e ad&an"age o' o"her op"!m!1a"!ons, such as
s"a"emen" cach!ng.
Con*iguring and Ena$ling the Pool
;&er !ns"ance o' Oracle Da"abase 11g uses a s!ngle, de'aul" connec"!on pool. User de'!ned
pools are curren"l no" suppor"ed. The de'aul" pool can be con'!gured and adm!n!s"ered b a
D-% us!ng "he D-M4NCO77;CT:O7NPOO. pac(age)
7SK e.ecute d/ms$connection$pool.con'igure$pool%
pool$name * 07;7$L-A6RK:$43MM-4:53M$E33K0+
minsiXe * D+
ma.siXe * D0+
incrsiXe * 2+
session$cached$cursors * 20+
inactiCit#$timeout * @00+
ma.$think$time * P00+
ma.$use$session * 500000+
ma.$li'etime$session * 8PD00&
%l"erna"!&el "he me"hod d/ms$connection$pool.alter$param%& can be used "o se" a s!ngle
parame"er)
7SK e.ecute d/ms$connection$pool.alter$param%
pool$name * 07;7$L-A6RK:$43MM-4:53M$E33K0+
param$name * 0N6,$:>5MG$:5N-0+
param$Calue * 012000&
There !s a d/ms$connection$pool.restore$de'aults%& procedure "o rese" all &alues.
0hen DRCP !s used +!"h R%C, each da"abase !ns"ance has !"s o+n connec"!on bro(er and
pool o' ser&ers. ;ach pool has "he !den"!cal con'!gura"!on. 2or e/ample, all pools s"ar" +!"h
M:74:9; ser&er processes. % s!ngle D-M4NCO77;CT:O7NPOO. command +!ll al"er "he pool o'
each !ns"ance a" "he same "!me.
The pool needs "o be s"ar"ed be'ore connec"!on re>ues"s beg!n. The command belo+ does
"h!s b br!ng!ng up "he bro(er, +h!ch reg!s"ers !"sel' +!"h "he da"abase l!s"ener)
7SK e.ecute d/ms$connection$pool.start$pool%&
Once enabled "h!s +a, "he pool au"oma"!call res"ar"s +hen "he !ns"ance res"ar"s, unless
e/pl!c!"l s"opped +!"h "he d/ms$connection$pool.stop$pool%& command)
7SK e.ecute d/ms$connection$pool.stop$pool%&
The pool canA" be s"opped +h!le connec"!ons are open. :' "he PHP appl!ca"!on uses pers!s"en"
connec"!ons, "hen "he +eb ser&er should be s"opped be'ore shu""!ng "he pool do+n. 4!m!larl
users canno" be dropped unless "he +eb ser&er !s '!rs" s"opped.
(-+
!H! Connection !ooling and High A$aila5ility
The DRCP con'!gura"!on op"!ons are descr!bed !n "he ne/" "able)
)able &6' D:-P -on*iguration Options"
#:CP Option #e!cription
pool$name
The pool "o be con'!gured. Curren"l "he onl suppor"ed name !s
"he de'aul" &alue 4M4ND;2%U.TNCO77;CT:O7NPOO..
minsiXe
M!n!mum number o' pooled ser&ers !n "he pool. The de'aul" !s J.
ma.siXe
Ma/!mum number o' pooled ser&ers !n "he pool. :' "h!s l!m!" !s
reached and all "he pooled ser&ers are bus, "hen connec"!on
re>ues"s +a!" un"!l a ser&er becomes 'ree. The &alue should be
less "han "he da"abase init"ora &alues o' sessions and
processes. The de'aul" &alue !s J0.
incrsiXe
The number o' pooled ser&ers !s !ncreased b "h!s &alue +hen
ser&ers are una&a!lable 'or PHP connec"!ons and !' "he pool !s
no" e" a" !"s ma/!mum s!1e. The de'aul" !s 2.
session$cached$cursors
:nd!ca"es "o "urn on 4;44:O7NC%CH;DNCUR4OR4 'or all
connec"!ons !n "he pool. Th!s &alue !s "p!call se" "o "he s!1e o'
"he +or(!ng se" o' 're>uen"l used s"a"emen"s. The cache uses
cursor resources on "he ser&er. The de'aul" !s 20. 7o"e) "here !s
also an init"ora parame"er 'or se""!ng "he &alue 'or "he +hole
da"abase !ns"ance. The pool op"!on allo+s a DRCP?based
appl!ca"!on "o o&err!de "he !ns"ance se""!ng.
inactiCit#$timeout
T!me "o l!&e 'or an !dle ser&er !n "he pool. :' a ser&er rema!ns
!dle !n "he pool 'or "h!s "!me, !" !s (!lled. Th!s parame"er helps "o
shr!n( "he pool +hen !" !s no" used "o !"s ma/!mum capac!". The
de'aul" !s I00 seconds.
ma.$think$time
Ma/!mum "!me o' !nac"!&!" "he PHP scr!p" !s allo+ed a'"er
connec"!ng. :' "he scr!p" does no" !ssue a da"abase call 'or "h!s
amoun" o' "!me, "he pooled ser&er ma be re"urned "o "he pool
'or reuse. The PHP scr!p" +!ll ge" an OR% error !' !" la"er "r!es "o
use "he connec"!on. The de'aul" !s 120 seconds.
ma.$use$session
Ma/!mum number o' "!mes a ser&er can be "a(en and released
"o "he pool be'ore !" !s 'lagged 'or res"ar"!ng. The de'aul" !s
H00000.
ma.$li'etime$session
T!me "o l!&e 'or a pooled ser&er be'ore !" !s res"ar"ed. The
de'aul" !s $OJ00 seconds.
num$c/rok
The number o' connec"!on bro(ers "ha" are crea"ed "o handle
connec"!on re>ues"s. The de'aul" !s 1. 7o"e) "h!s can onl be se"
+!"h alter$param%&.
(--
Bsing DRC! in !H!
#:CP Option #e!cription
ma.conn$c/rok
The ma/!mum number o' connec"!ons "ha" each connec"!on
bro(er can handle. 4e" "he per?process '!le descr!p"or l!m!" o' "he
opera"!ng ss"em su''!c!en"l h!gh so "ha" !" suppor"s "he
number o' connec"!ons spec!'!ed. The de'aul" !s J0000. 7o"e)
"h!s can onl be se" +!"h alter$param%&.
The parame"ers ha&e been descr!bed here rela"!&e "o "he!r use !n PHP bu" !" !s +or"h
remember!ng "ha" "he DRCP pool !s usable concurren"l b o"her programs, !nclud!ng "hose
us!ng PerlAs D-D))Oracle and P"honAs c/NOracle e/"ens!ons.
:n general, !' pool parame"ers are changed, "he pool should be res"ar"ed, o"her+!se ser&er
processes +!ll con"!nue "o use old se""!ngs.
The inactivity=ti+eout se""!ng "erm!na"es !dle pooled ser&ers, help!ng op"!m!1e da"abase
resources. To a&o!d pooled ser&ers permanen"l be!ng held on"o b a dead +eb ser&er process
or a sel'!sh PHP scr!p", "he +ax=thin1=ti+e parame"er can be se". The parame"ers nu+=cbro1
and +axconn=cbro1 can be used "o d!s"r!bu"e "he pers!s"en" connec"!ons 'rom "he cl!en"s
across mul"!ple bro(ers. Th!s ma be needed !n cases +here "he opera"!ng ss"em per?process
descr!p"or l!m!" !s small.
4ome cus"omers ha&e 'ound "ha" ha&!ng se&eral connec"!on bro(ers !mpro&es
per'ormance.
The +ax=use=session and +ax=li*eti+e=session parame"ers help pro"ec" aga!ns" an
un'oreseen problems a''ec"!ng ser&er processes. The de'aul" &alues +!ll be su!"able 'or mos"
users.
Users o' Oracle Da"abase 11.1.0.O mus" appl "he da"abase pa"ch 'or bug OJPJJJ1 "o
a&o!d >uer errors. :" also enables .O3O7 "r!gger suppor". Th!s pa"ch !s no" needed +!"h 11.2
or 11.1.0.P on+ards.
Con*iguring PHP *or #:CP
PHP mus" be bu!l" +!"h "he OC:$ 1.I or la"er e/"ens!on. CPHP H.I con"a!ns OC:$ 1.JF.
DRCP 'unc"!onal!" !s onl a&a!lable +hen PHP OC:$ !s l!n(ed +!"h Oracle Da"abase 11g
cl!en" l!brar!es and connec"ed "o Oracle Da"abase 11g.
-e'ore us!ng DRCP, "he ne+ php"ini parame"er oci/"connection=class should be se" "o
spec!' "he connec"!on class used b all "he re>ues"s 'or pooled ser&ers b "he PHP
appl!ca"!on.
oci8.connection$class * N;E>E6EE
The parame"er can be se" !n php"ini, "htaccess or httpd"con* '!les. :" can also be se" and
re"r!e&ed programma"!call us!ng "he PHP 'unc"!ons ini$set%& and ini$get%&.
The OC:$ e/"ens!on has se&eral legac php"ini con'!gura"!on parame"ers 'or "un!ng
pers!s"en" connec"!ons. These +ere ma!nl used "o l!m!" !dle resource usage. 0!"h DRCP, "he
parame"ers s"!ll ha&e an e''ec" bu" !" ma be eas!er "o use "he DRCP pool con'!gura"!on
op"!ons.
(-0
!H! Connection !ooling and High A$aila5ility
)able &5' Existing php"ini para+eters *or persistent connections"
php.ini Para1eter )eha-ior ;ith #:CP
oci8.persistent$timeout %" "he "!meou" o' an !dle PHP connec"!on, PHP +!ll close
"he Oracle connec"!on "o "he bro(er. The de'aul" !s no
"!meou".
oci8.ma.$persistent The ma/!mum number o' un!>ue pers!s"en" connec"!ons
"ha" each PHP process +!ll ma!n"a!n "o "he bro(er. 0hen
"he l!m!" !s reached a ne+ pers!s"en" connec"!on beha&es
l!(e oci$connect%& and releases "he connec"!on a" "he
end o' "he scr!p". The de'aul" !s no l!m!". 7o"e) The DRCP
+axsie se""!ng +!ll s"!ll be en'orced b "he da"abase
!ndependen"l 'rom oci/"+ax=persistent.
oci8.ping$interCal The oci/"ping=interval &alue !s also used 'or non?
pers!s"en" connec"!ons +hen DRCP !s used. The de'aul"
!s O0 seconds.
0!"h oci/"ping=interval, "he non?DRCP recommenda"!on "o se" !" "o ?1 "o d!sable p!ng!ng, and
"o use appropr!a"e error chec(!ng s"!ll holds "rue +!"h DRCP. %lso, "he use o' 2%7 Csee la"erF
reduces "he chance o' !dle connec"!ons becom!ng unusable.
0eb ser&ers and "he ne"+or( should bene'!" 'rom oci/"state+ent=cache=sie be!ng se". 2or
bes" per'ormance !" should generall be larger "han "he s!1e o' "he +or(!ng se" o' 4B.
s"a"emen"s. To "une !", mon!"or general +eb ser&er load and "he %0R D5ytes sent $ia
#;L<Net to clientD &alues. The la""er s"a"!s"!c should bene'!" 'rom no" need!ng "o send
s"a"emen" me"a?da"a "o PHP. %d8us" "he s"a"emen" cache s!1e "o our sa"!s'ac"!on.
Once ou are happ +!"h "he s"a"emen" cache s!1e, "hen "une "he DRCP pool
session=cached=cursors &alue. Mon!"or %0R repor"s +!"h "he goal "o ma(e "he Dsession
cursor cache hitsD close "o "he number o' so'" parses. 4o'" parses can be calcula"ed 'rom
Dparse count FtotalGD m!nus Dparse count FhardGE.
,pplication #eplo61ent *or #:CP
PHP appl!ca"!ons mus" spec!' "he ser&er "pe POO.;D !n "he connec" s"r!ng. Us!ng OracleKs
;as Connec" sn"a/, "he PHP call "o connec" "o "he sales da"abase on +yhost +ould loo( l!(e)
)c * oci$pconnect%0m#user0+ 0m#password0+ 0m#host/sales7%&&)E*0&!
Or !' PHP uses an Oracle 7e"+or( connec" name "ha" loo(s l!(e)
)c * oci$pconnect%0m#user0+ 0m#password0+ 0salespool0&!
Then onl "he Oracle 7e"+or( con'!gura"!on '!le tnsna+es"ora needs "o be mod!'!ed)
salespool*%L-74B5E:53M*%6LLB-77*%EB3:343K*tcp&
%>37:*m#host.dom.com&
%E3B:*1521&&%43MM-4:$L6:6*%7-BZ54-$M6N-*sales&
(SE8@E8;%&&)E*)&&
:' "hese changes are made and "he da"abase !s no" ac"uall con'!gured 'or DRCP, or "he pool !s
no" s"ar"ed, "hen connec"!ons +!ll no" succeed and an error +!ll be re"urned "o PHP.
(-1
Bsing DRC! in !H!
%l"hough appl!ca"!ons can choose +he"her or no" "o use pooled connec"!ons a" run"!me,
care mus" be "a(en "o "he con'!gure "he da"abase appropr!a"el 'or "he number o' e/pec"ed
connec"!ons, and also "o s"op !nad&er"en" use o' non?pooled connec"!ons lead!ng "o a resource
shor"age.
Closing Connections
PHP scr!p"s "ha" do no" curren"l use oci$close%& should be e/am!ned "o see !' "he can use !"
"o e/pl!c!"l re"urn connec"!ons "o "he pool, allo+!ng ma/!mum use o' pooled ser&ers)
// 1. Lo some data/ase operations
)c * oci$pconnect%0m#user0+ 0m#password0+ 0m#host/sales:E33K-L0&!
. . .
oci$commit%)c&!
oci_c"ose($c)4 55 8e"ease the connection to the *8C% poo"
// 2. Lo lots o' non-data/ase work
. . .
// @. Lo some more data/ase operations
)c * oci$pconnect%0m#user0+ 0m#password0+ 0m#host/sales:E33K-L0&!
. . .
oci$commit%)c&!
oci$close%)c&!
Remember "o 'ree s"a"emen" and o"her resources "ha" !n"ernall !ncrease "he re'erence coun"
on "he PHP connec"!on and +!ll o"her+!se s"op a da"abase connec"!on 'rom clos!ng.
Pr!or "o OC:$ 1.I, clos!ng oci$connect%& and oci$new$connect%& connec"!ons had an e''ec"
bu" clos!ng an oci$pconnect%& connec"!on +as a no?op. 2rom OC:$ 1.I, oci$close%& on a
pers!s"en" connec"!on rolls bac( an uncomm!""ed "ransac"!on. %lso "he e/"ens!on +!ll do a roll
bac( +hen all PHP &ar!ables re'erenc!ng a pers!s"en" connec"!on go ou" o' scope, 'or e/ample
!' "he connec"!on +as opened !n a 'unc"!on and "he 'unc"!on has no+ '!n!shed. 2or DRCP, !n
add!"!on "o "he rollbac(, "he connec"!on !s also releasedG a subse>uen" oci$pconnect%& ma
ge" a d!''eren" connec"!on. 2or DRCP, "he bene'!" !s "ha" scr!p"s "a(!ng ad&an"age o' pers!s"en"
connec"!ons can e/pl!c!"l re"urn a ser&er "o "he pool +hen non?da"abase process!ng occurs,
allo+!ng o"her concurren" scr!p"s "o ma(e use o' "he pooled ser&er.
0!"h pooled ser&ers, "he recommenda"!on !s "o release "he connec"!on +hen "he scr!p"
does a s!gn!'!can" amoun" o' process!ng "ha" !s no" da"abase rela"ed. ;/pl!c!"l con"rol
comm!"s and rollbac(s so "here !s no une/pec"edl open "ransac"!on +hen "he close or end?o'?
scope occurs. 4cr!p"s coded l!(e "h!s can use oci$close%& "o "a(e ad&an"age o' DRCP bu" s"!ll
be por"able "o older &ers!ons o' "he OC:$ e/"ens!on.
:' beha&!or +here oci$close%& !s a no?op 'or all connec"!on "pes !s pre'erred, se" "he
php"ini parame"er oci/"old=oci=close=se+antics "o On.
Transactions )cross *e%connection
4cr!p"s should a&o!d re?open!ng connec"!ons !' "here are !ncomple"e "ransac"!ons)
// 1. Lo some data/ase operations
)c * oci$pconnect%0m#user0+ 0m#password0+ 0salespool0&!
// 7tart a transaction
)s * oci$parse%)c+ 0insert into m#ta/ Calues %1&0&!
(-2
!H! Connection !ooling and High A$aila5ility
)r * oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&! // no commit
...
// :(*7 no co--it or ro""bac0 done
// 2. 4ontinue data/ase operations on same credentials
)c * oci$pconnect%0m#user0+ 0m#password0+ 0salespool0&!
)s * oci$parse%)c+ 0insert into m#ta/ Calues %2&0&!
)r * oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&! // no commit
// 5ntend to commit /oth 1 ^ 2 /ut /ehaCior could /e random
oci$commit%)c&!
:' "here +as a node or ne"+or( 'a!lure 8us" pr!or "o po!n" 2, "he '!rs" "ransac"!on could be los".
The second connec"!on command ma re"urn a ne+, &al!d connec"!on !' a p!ng Csee
oci/"ping=intervalF occurs "o &al!da"e "he connec"!on, and "he scr!p" m!gh" no" be a+are "ha"
onl "he second par" o' "he "ransac"!on !s comm!""ed.
The scr!p" should do an e/pl!c!" comm!" or rollbac( be'ore "he second connec", or s!mpl
con"!nue "o use "he or!g!nal connec"!on. :" should al+as do appropr!a"e error handl!ng.
LOGO. and LOGO&& Triggers with D*C#
.O3O7 "r!ggers are use'ul 'or se""!ng sess!on a""r!bu"es needed b each PHP connec"!on. 2or
e/ample a "r!gger could be used "o e/ecu"e an 6K:-B 7-7753M s"a"emen" "o se" a da"e 'orma".
The .O3O7 "r!gger +!ll e/ecu"e +hen oci$pconnect%& '!rs" crea"es "he sess!on, and "he
sess!on +!ll be reused b subse>uen" pers!s"en" connec"!ons. 4cr!p"s sa&e "!me b no longer
al+as e/ecu"!ng code "o se" "he da"e 'orma".
The sugges"ed prac"!ce +!"h DRCP !s "o use .O3O7 "r!ggers onl 'or se""!ng sess!on
a""r!bu"es and no" 'or e/ecu"!ng per PHP?connec"!on log!c such as cus"om logon aud!"!ng. Th!s
recommenda"!on !s also "rue 'or pers!s"en" connec"!ons +!"h ded!ca"ed or shared ser&ers.
Da"abase ac"!ons "ha" mus" be per'ormed e/ac"l once per OC:$ connec"!on call should be
e/pl!c!"l e/ecu"ed !n "he PHP scr!p".
2rom Oracle 11gR2 on+ards, .O3O22 "r!ggers '!re 'or pooled ser&ers +hen sess!ons are
"erm!na"ed. 2or oci$connect%& and oci$new$connect%& connec"!ons, "h!s !s +!"h oci$close%&
or a" "he end o' "he scr!p". 2or oci$pconnect%& connec"!ons, !" can happen +hen "he pooled
ser&er process na"urall "erm!na"es or !"s sess!on needs "o be recrea"ed.
:" !s no" poss!ble "o depend on "r!ggers 'or "rac(!ng PHP OC:$ connec" calls. The cach!ng,
pool!ng, "!m!ng ou" and recrea"!on o' sess!ons and connec"!ons +!"h or +!"hou" DRCP can
d!s"or" an record. 0!"h pooled ser&ers, .O3O7 "r!ggers can '!re a" au"hen"!ca"!on and +hen
"he sess!on !s crea"ed, !n e''ec" '!r!ng "+!ce 'or "he !n!"!al connec"!on.
Changing #asswords with D*C# Connections
:n general, PHP appl!ca"!ons "ha" change pass+ords should a&o!d us!ng oci$pconnect%&. Th!s
call +!ll use "he old pass+ord "o ma"ch an open connec"!on !n PHPKs pers!s"en" connec"!on
cache +!"hou" re>u!r!ng re? au"hen"!ca"!on "o "he da"abase +!"h "he ne+ pass+ord. Th!s can
cause con'us!on o&er +h!ch pass+ord "o connec" +!"h s!nce !' "here !s no cached connec"!on !"
!s "he ne+ pass+ord "ha" mus" be used. 0!"h DRCP, "here !s a 'ur"her l!m!"a"!on ? connec"!ons
canno" be used "o change pass+ords programma"!call. PHP scr!p"s "ha" use
oci$password$change%& should con"!nue "o use ded!ca"ed or shared ser&ers.
(03
:onitoring DRC!
5onitoring #:CP
Da"a d!c"!onar &!e+s are a&a!lable "o mon!"or "he per'ormance o' DRCP. Da"abase
adm!n!s"ra"ors can chec( s"a"!s"!cs such as "he number o' bus and 'ree ser&ers, and "he
number o' h!"s and m!sses !n "he pool aga!ns" "he "o"al number o' re>ues"s 'rom cl!en"s. The
&!e+s are)
D-%NCPOO.N:72O
,WPROC;44
,W4;44:O7
,WCPOO.N4T%T4
,WCPOO.NCCN4T%T4
,WCPOO.NCO77N:72O
2or Oracle R%C, "here are 3,WCPOO.N4T%T4, 3,WCPOO.NCCN4T%T4 and
3,WCPOO.NCO77N:72O &!e+s correspond!ng "o "he !ns"ance?le&el &!e+s. These record DRCP
s"a"!s"!cs across clus"ered !ns"ances. :' a da"abase !ns"ance !n a clus"er !s shu" do+n, "he
s"a"!s"!cs 'or "ha" !ns"ance are purged 'rom "he 3,W &!e+s.
The DRCP s"a"!s"!cs are rese" each "!me "he pool !s s"ar"ed.
#),ACPOO'AIN9O <ie;
D-%NCPOO.N:72O d!splas con'!gura"!on !n'orma"!on abou" "he DRCP pool. The columns are
e>u!&alen" "o "he d/ms$connection$pool.con'igure$pool%& se""!ngs descr!bed !n "he "able o'
DRCP con'!gura"!on op"!ons, +!"h "he add!"!on o' a 4T%TU4 column. The s"a"us !s %CT:,; !' "he
pool has been s"ar"ed and :7%CT:,; o"her+!se. 7o"e "he pool name column !s called
CO77;CT:O7NPOO.. Th!s e/ample chec(s +he"her "he pool has been s"ar"ed and '!nds "he
ma/!mum number o' pooled ser&ers)
7SK select connection$pool+ status+ ma.siXe
'rom d/a$cpool$in'o!
43MM-4:53M$E33K 7:6:R7 N6,75]-
---------------------------- ---------------- ----------
7;7$L-A6RK:$43MM-4:53M$E33K 64:5Z- D0
:n Oracle 11gR2, D-%NCPOO.N:72O ga!ned 7UMNC-RO6 and M%=CO77NC-RO6 columns,
e>u!&alen" "o "he pool con'!gura"!on op"!ons o' "he same names. :n Oracle 11gR1 "he number
o' con'!gured bro(ers per !ns"ance can be 'ound 'rom "he ,WPROC;44 &!e+, 'or e/ample on
.!nu/ "h!s >uer sho+s one bro(er has been enabled)
7SK select program
'rom C)process
where program like 0oracleF%MF&0!
EB3YB6N
------------------------------------------------
oracleOlocalhost %M001&
(0&
!H! Connection !ooling and High A$aila5ility
<CP:OCESS and <CSESSION <ie;!
The ,W4;44:O7 &!e+ +!ll sho+ !n'orma"!on abou" "he curren"l ac"!&e DRCP sess!ons. :" can
also be 8o!ned +!"h ,WPROC;44 &!a Z)7-7753M.E6LLB * Z)EB34-77.6LLB "o correla"e "he
&!e+s.
<CCPOO'AST,TS <ie;
,WCPOO.N4T%T4 d!splas !n'orma"!on abou" "he DRCP s"a"!s"!cs 'or an !ns"ance.
)able &4' 7J-POOF=S)A)S 7ie,"
Colu1n #e!cription
E33K$M6N-
7ame o' "he Da"abase Res!den" Connec"!on Pool.
MRN$3E-M$7-BZ-B7
To"al number o' bus and 'ree ser&ers !n "he pool C!nclud!ng
"he au"hen"!ca"!on ser&ersF.
MRN$IR7;$7-BZ-B7
To"al number o' bus ser&ers !n "he pool Cno" !nclud!ng "he
au"hen"!ca"!on ser&ersF.
MRN$6R:>$7-BZ-B7
7umber o' au"hen"!ca"!on ser&ers !n "he pool.
MRN$B-SR-7:7
7umber o' cl!en" re>ues"s.
MRN$>5:7
To"al number o' "!mes cl!en" re>ues"s 'ound ma"ch!ng
pooled ser&ers and sess!ons !n "he pool.
MRN$N577-7
To"al number o' "!mes cl!en" re>ues"s could no" '!nd a
ma"ch!ng pooled ser&er and sess!on !n "he pool.
MRN$?65:7
To"al number o' cl!en" re>ues"s "ha" had "o +a!" due "o non?
a&a!lab!l!" o' 'ree pooled ser&ers.
?65:$:5N-
Reser&ed 'or 'u"ure use.
4K5-M:$B-S$:5N-3R:7
Reser&ed 'or 'u"ure use.
MRN$6R:>-M:546:53M7
To"al number o' au"hen"!ca"!ons o' cl!en"s done b "he pool.
MRN$ERBY-L
To"al number o' sess!ons purged b "he pool.
>57:3B54$N6,
Ma/!mum s!1e "ha" "he pool has e&er reached. 0!"h PHP
"h!s !s l!(el "o reach "he ma/!mum pool s!1e &alue.
The ,WCPOO.N4T%T4 &!e+ can be used "o assess ho+ e''!c!en" "he pool se""!ngs are. Th!s
e/ample >uer sho+s an appl!ca"!on us!ng "he pool e''ec"!&el. The lo+ number o' m!sses
!nd!ca"es "ha" ser&ers and sess!ons +ere reused. The +a!" coun" sho+s 8us" o&er 1^ o'
re>ues"s had "o +a!" 'or a pooled ser&er "o become a&a!lable)
7SK select num$re"uests+num$hits+num$misses+num$waits
'rom C)cpool$stats!
MRN$B-SR-7:7 MRN$>5:7 MRN$N577-7 MRN$?65:7
------------ ---------- ---------- ----------
1000@1 9999@ @8 105D
(0(
:onitoring DRC!
:' oci/"connection=class !s se" Callo+!ng pooled ser&ers and sess!ons "o be reusedF "hen
7UMNM:44;4 !s lo+. :' "he pool +axsie !s "oo small 'or "he connec"!on load "hen 7UMN0%:T4
!s h!gh)
MRN$B-SR-7:7 MRN$>5:7 MRN$N577-7 MRN$?65:7
------------ ---------- ---------- ----------
50@52 50@D8 D 501D9
Tune "he pool s!1e b mon!"or!ng "he 7UMN0%:T4 "rend. :' "he &alue !s h!gh "hen !ncrease "he
number o' pooled ser&ers.
:' "he connec"!on class !s le'" unse", "he shar!ng o' pooled ser&ers !s res"r!c"ed "o +!"h!n
each +eb ser&er process. ;&en !' "he pool s!1e !s large, sess!on shar!ng !s l!m!"ed caus!ng poor
u"!l!1a"!on o' pooled ser&ers and con"en"!on 'or "hem)
MRN$B-SR-7:7 MRN$>5:7 MRN$N577-7 MRN$?65:7
------------ ---------- ---------- ----------
PD152 1U9D1 DP211 15118
:' 7UMNH:T4 !s 0 or &er lo+, one po"en"!al cause !s "he use o' oci$connect%& s!nce "h!s !s
des!gned "o recrea"e "he sess!on each "!me !" !s called. Use oci$pconnect%& !ns"ead.
<CCPOO'ACCAST,TS <ie;
,WCPOO.NCCN4T%T4 d!splas !n'orma"!on abou" "he connec"!on class le&el s"a"!s"!cs 'or "he
pool per !ns"ance. The columns are s!m!lar "o "hose o' ,WCPOO.N4T%T4 descr!bed !n Table 1H,
+!"h a CC.%44N7%M; column g!&!ng "he name o' "he connec"!on sub?pool "he resul"s are 'or)
7SK select cclass$name+ num$re"uests+ num$hits+ num$misses
'rom C)cpool$cc$stats!
44K677$M6N- MRN$B-SR-7:7 MRN$>5:7 MRN$N577-7
-------------------------------- ------------ ---------- ----------
>B.N;E>E6EE 1000@1 9999@ @8
743::.7>6B-L 10 0 10
4T.345:7E:wsh/5ALt/UrgSwN#u;Cod6 1 0 1
2or PHP, "he CC.%44N7%M; &alue !s composed o' "he &alue o' "he username and o' "he
oci/"connection=class &alue used b "he connec"!ng PHP processes. The e/ample abo&e
sho+s an appl!ca"!on (no+n as MMPHP%PP us!ng "he pool e''ec"!&el.
2or programs l!(e 4B.SPlus "ha" +ere no" bu!l" us!ng OracleKs 4ess!on Pool!ng %P:s, "he
class name +!ll be 4H%R;D. The e/ample sho+s "ha" "en such connec"!ons +ere made as "he
user 4COTT. %l"hough "hese programs share "he same connec"!on class, ne+ sess!ons are
crea"ed 'or each connec"!on, (eep!ng each cleanl !sola"ed 'rom an un+an"ed sess!on
changes. Th!s !s s!m!lar "o us!ng PHPKs oci$connect%& +!"h DRCP pooled ser&ers.
The las" l!ne o' "he e/ample ou"pu" sho+s a ss"em genera"ed class name 'or an
appl!ca"!on "ha" crea"ed a connec"!on +!"hou" e/pl!c!"l se""!ng oci/"connection=class, or had !"
se" "o an emp" s"r!ng. Pool!ng +ould no" be e''ec"!&el used !' "h!s appl!ca"!on con"!nued "o
be e/ecu"ed. 4uch an en"r could be an !nd!ca"!on "ha" a php"ini '!le !s m!s?con'!gured.
(0)
!H! Connection !ooling and High A$aila5ility
!2C#OOL3CO..3I.&O !iew
Th!s &!e+ g!&es !ns!gh" !n"o cl!en" processes "ha" are connec"ed "o "he connec"!on bro(er,
ma(!ng !" eas!er "o mon!"or and "race appl!ca"!ons "ha" are curren"l us!ng pooled ser&ers or
are !dle.
Th!s &!e+ +as !n"roduced !n Oracle 11gR2.
)able &9' 7J-POOF=-O22=.2(O 7ie,"
Colu1n #e!cription
4N3M$6LLB
%ddress o' "he connec"!on bro(er
7-7753M$6LLB
%ddress o' "he sess!on assoc!a"ed +!"h "he
connec"!on. 7U.. !' "here !s no ac"!&e
sess!on. Can be 8o!ned +!"h
,W4;44:O7.4%DDR
43MM-4:53M$6LLB
%ddress o' "he connec"!on
R7-BM6N-
7ame o' "he user assoc!a"ed +!"h "he
connec"!on
EB3,;$R7-B
7ame o' "he pro/ user
44K677$M6N-
Connec"!on class assoc!a"ed +!"h "he
connec"!on
ERB5:;
0!ll be 4;.2 'or oci$pconnect%& calls or
7;0 o"her+!se
:6Y
7o" se" b PHP
7-BZ54-
T74 ser&!ce name 'or "he connec"!on
EB34-77$5L
Process :D o' "he PHP or %pache process
EB3YB6N
Program name o' "he PHP or %pache process
N64>5M-
Mach!ne name +here PHP !s runn!ng
:-BN5M6K
Term!nal !den"!'!er o' "he PHP process "ha"
crea"ed "he connec"!on
43MM-4:53M$N3L-
Reser&ed 'or !n"ernal use
43MM-4:53M$7:6:R7
4"a"us o' "he connec"!on) 7O7;,
CO77;CT:73, %CT:,;, 0%:T:73, :D.;
(0*
:onitoring DRC!
Mou can mon!"or ,WCPOO.NCO77N:72O "o, 'or e/ample, !den"!' m!s?con'!gured mach!nes "ha"
do no" ha&e "he connec"!on class se" correc"l. Th!s &!e+ maps "he mach!ne name "o "he class
name)
7SK select cclass$name+ machine 'rom C)cpool$conn$in'o!
44K677$M6N- N64>5M-
--------------------------------------- ------------
. . .
4T.345:7E:wsh/5ALt/UrgSwN#u;Cod6 cWlinu.
. . .
:n Oracle 11gR1 or !n h!ghl dnam!c s!"ua"!ons ou can '!nd "h!s same !n'orma"!on b "urn!ng
on OC: "rac!ng !n "he da"abase)
) s"lplus / as s#sd/a
7SK alter s#stem set eCents 01052D trace name conte.t 'oreCer+ leCel 10!
There !s no need "o res"ar" "he da"abase.
7o+ run "he appl!ca"!on "o genera"e "he "race '!les.
The "race '!le d!rec"or can be 'ound b do!ng show parameter /ackground$dump$dest !n
4B.SPlus. :n "he pooled ser&er "race '!les, search 'or 1pplsPopulate)
) grep kpplsEopulate J.trc
. . .
orcl@$l005$285UP.trc:kpplsEopulate: cso authenticated+
ke#*%4TJ4T.345:7E:wsh/5ALt/UrgSwN#u;Cod6JJ1Jorcl@J3B6)I67-J&
Mou can see "he correspondence be"+een "he @(e@ '!elds and "he class names sho+n earl!er
!n ,WCPOO.NCCN4T%T4. Open "he rela"ed "race '!le, 'or e/ample orcl6=lAA4=2/4?9"trc. 7ear
"he -T"O-.'SP',shb.(Dtb?rgE,!yu>vodA en"r !" con"a!ns)
. . .
JJJ 7-7753M 5L:%9.D985& 2012-0P-18 1P:1P:29.9U@
JJJ 7-BZ54- M6N-:%orcl@& 2012-0P-18 1P:1P:29.9U@
JJJ N3LRK- M6N-:%httpdOcA"in!x %:M7 Z1-Z@&& 2012-0P-18 1P:1P:29.9U@
JJJ 64:53M M6N-:%& 2012-0P-18 1P:1P:29.9U@

kpplsEostErocess7tate:%ac"uired*0&%call*37-77G-;&
kpplsh$cso$release$hdlr: cso*%0.c/'d/d88&
Belease %A6K7-&: cso*0.c/'d/d88
kpplsEreErocess7tate:%ac"uired*0&%call*36R:>&
6uthentication complete: cso*0.c/'d/d88
kpplsEopulate: cso authenticated+
ke#*%4TJ4T.345:7E:wsh/5ALt/UrgSwN#u;Cod6JJ1Jorcl@J3B6)I67-J&
kppls4lear7ession: sCso4t. * %0.a'5U8/c8&
kppls4lear7ession: Lestro#ing session* %0.c'PD02P8&
. . .
Read!ng bac( up "he "race '!le "o "he MODU.; 7%M; l!ne sho+s "he hos" name +as c0linux.
Th!s !s "he hos" %pache +as runn!ng on. Chec( "he php"ini o' "h!s mach!ne, ensur!ng "ha" !"
con"a!ns a &al!d oci/"connection=class parame"er.
Trac!ng can no+ be "urned o'')
alter s#stem set eCents 01052D trace name conte.t 'oreCer+ leCel 00!
(0+
!H! Connection !ooling and High A$aila5ility
High ,-aila$ilit6 With 9,N and :,C
Cl!en"s "ha" run !n h!gh a&a!lab!l!" con'!gura"!ons such as +!"h Oracle R%C or Da"a 3uard
Phs!cal 4"and?- can "a(e ad&an"age o' 2as" %ppl!ca"!on 7o"!'!ca"!on C2%7F e&en"s "o allo+
appl!ca"!ons "o respond >u!c(l "o da"abase node 'a!lures. 2%7 suppor" !n PHP ma be used
+!"h or +!"hou" DRCP Y "he "+o 'ea"ures are !ndependen".
0!"hou" 2%7, +hen a da"abase !ns"ance or mach!ne node 'a!ls une/pec"edl, PHP
appl!ca"!ons ma be bloc(ed +a!"!ng 'or a da"abase response un"!l a TCP "!meou" e/p!res.
;rrors are "here'ore delaed, some"!mes up "o se&eral m!nu"es.
- le&erag!ng 2%7 e&en"s, PHP appl!ca"!ons are >u!c(l no"!'!ed o' 'a!lures "ha" a''ec" "he!r
es"abl!shed da"abase connec"!ons. Connec"!ons "o a 'a!led da"abase !ns"ance are pro?ac"!&el
"erm!na"ed +!"hou" +a!"!ng 'or a po"en"!all leng"h TCP "!meou". Th!s allo+s PHP scr!p"s "o
reco&er >u!c(l 'rom a node or ne"+or( 'a!lure. The appl!ca"!on can reconnec" and con"!nue
process!ng +!"hou" "he user be!ng a+are o' a problem.
%lso, all !nac"!&e ne"+or( connec"!ons cached !n PHP "o "he connec"!on bro(er !n case o'
DRCP, and pers!s"en" connec"!ons "o "he ser&er processes or d!spa"cher !n case o' ded!ca"ed
or shared ser&er connec"!ons on "he 'a!led !ns"ances, are au"oma"!call cleaned up.
% subse>uen" PHP connec"!on call +!ll crea"e a ne+ connec"!on "o a sur&!&!ng R%C node,
ac"!&a"ed s"and?b da"abase, or e&en "he res"ar"ed s!ngle?!ns"ance da"abase.
Con*iguring 9,N E-ent! in the #ata$a!e
To ge" "he bene'!" o' h!gh a&a!lab!l!", "he da"abase ser&!ce "o +h!ch "he appl!ca"!ons connec"
mus" be enabled "o pos" 2%7 e&en"s. 2or e/ample, "o enable e&en"s on "he ser&!ce 4%.;4 !n
an Oracle 11gR2 da"abase 4%.;4D-)
) srCctl modi'# serCice Vd 76K-7LI Vs 76K-7 V" :BR-
The V" op"!on !nd!ca"es "ha" %B h!gh a&a!lab!l!" e&en"s should be enabled.
Con*iguring PHP *or 9,N
0!"h "he OC:$ e/"ens!on, a php"ini con'!gura"!on parame"er oci/"events allo+s PHP "o be
no"!'!ed o' 2%7 e&en"s)
oci8.eCents * 3n
2%7 suppor" !s onl a&a!lable +hen PHP uses OC:$ 1.I on+ards, and !s l!n(ed +!"h Oracle
Da"abase 10g Release 2 or 11g l!brar!es. PHP mus" connec" "o Oracle Da"abase 10g Release 2
or 11g.
0!"h older &ers!ons o' Oracle Da"abase, re&!e+ "he pa"ches 'or Oracle bugs P1JI2LL C'!/ed
!n Oracle 11.2.0.1F and $OP0I$L C'!/ed !n 11.2.0.2F "o !mpro&e log!n "!mes !n &ar!ous
cond!"!ons +hen us!ng oci/"events.
,pplication #eplo61ent *or 9,N
The error codes re"urned "o PHP +!ll generall be "he same as +!"hou" 2%7 enabled, so
appl!ca"!on error handl!ng can rema!n unchanged.
%l"erna"!&el, appl!ca"!ons can be enhanced "o reconnec" and re"r ac"!ons, "a(!ng
ad&an"age o' "he h!gher le&el o' ser&!ce g!&en b 2%7.
(0-
High A$aila5ility With 8AN and RAC
%s an e/ample, "he code belo+ does some +or( Cperhaps a ser!es o' upda"e s"a"emen"sF.
:' "here !s a connec"!on 'a!lure, !" reconnec"s, chec(s "he "ransac"!on s"a"e and re"r!es "he
+or(. The OC:$ e/"ens!on +!ll de"ec" "he connec"!on 'a!lure and be able reconnec" on re>ues",
bu" "he user scr!p" mus" also de"erm!ne "ha" +or( 'a!led, +h !" 'a!led, and be able "o con"!nue
"ha" +or(. The e/ample code de"ec"s connec"!ons errors so !" can !den"!' !" needs "o con"!nue
or re"r +or(. :" !s generall !mpor"an" no" "o redo opera"!ons "ha" alread comm!""ed upda"ed
da"a.
Tp!cal errors re"urned a'"er an !ns"ance 'a!lure are O:A3&2&46' )2S'not connected or
O:A3A6&&6' end3o*3*ile on co++unication channel. 4ome more connec"!on rela"ed errors are
sho+n !n "he e/ample bu" o"hers, and errors !nclud!ng s"andard da"abase errors, ma be
re"urned, depend!ng on "!m!ng.
'unction is4onnection-rror%)err&
(
switch%)err& (
case 22: /J session does not e.ist J/
case 28: /J session killed J/
case @U8: /J /u''er pool param incorrect J/
case P02: /J core dump J/
case P0@: /J 'atal error J/
case P0D: /J recursiCe 7SK error J/
case P09: /J attach 'ailed J/
case 1012: /J not logged in J/
case 10@@: /J init or shutdown in progress J/
case 10D1: /J internal error J/
case 10D@: /J 3racle not aCaila/le J/
case 1089: /J immediate shutdown in progress J/
case 1090: /J shutdown in progress J/
case 1092: /J instance terminated J/
case @11@: /J disconnect J/
case @11D: /J not connected J/
case @122: /J closing window J/
case @1@5: /J lost contact J/
case 1215@: /J :M7: not connected J/
case 2U1DP: /J 'atal or instance terminated J/
case 28511: /J Kost BE4 J/
return true!
=
return 'alse!
=
)c * do4onnect%&!
)err * do7ome?ork%)c&!
i' %is4onnection-rror%)err&& (
// reconnect+ 'ind what was committed+ and retr#
)c * do4onnect%&!
)err * check6pplication7tate6nd4ontinue?ork%)c&!
=
i' %)err& (
// end the application
handle-rror%)err&!
=
(00
!H! Connection !ooling and High A$aila5ility
The comple/!" !s +!"h !den"!'!ng +ha" +or( "he appl!ca"!on has comple"ed and +ha" needs
"o be redone a'"er reconnec"!on. Ma(e sure "he appl!ca"!on uses "ransac"!ons and does no"
au"o?comm!". One "echn!>ue 'or !den"!'!ng +ha" +or( rema!ns "o be done !s "o add a s"a"us
column "o a "able. ;ach par" o' "he scr!p" upda"es "he s"a"us column +hen !" has comple"ed.
:,C Connection 'oad )alancing With PHP
PHP OC:$ 1.I on+ards +!ll au"oma"!call balance ne+ connec"!ons across R%C !ns"ances +!"h
OracleAs Connec"!on .oad -alanc!ng CC.-F "o use resources e''!c!en"l. The balanc!ng happens
a" "he '!rs" connec" 'or each se" o' creden"!als !n a PHP process. The same R%C !ns"ance +!ll
"hen be used 'or "he l!'e o' "he PHP process.
:" !s recommended "o use 2%7 and C.- "oge"her.
7o PHP scr!p" changes are needed "o use C.-. The connec"!on balanc!ng !s handled
"ransparen"l b "he Oracle 7e" l!s"ener. To enable C.-, "he da"abase ser&!ce mus" be
mod!'!ed "o send load e&en"s "o "he l!s"ener. :n Oracle 11gR2 use "he -W 7>3B: or -W K3MY
op"!ons "o srvctl. 2or e/ample)
) srCctl modi'# serCice Vd 76K-7LI Vs 76K-7 VW K3MY
)able &?' -FI goal para+eter values"
Para1eter <alue Para1eter #e!cription
7>3B: Use 'or connec"!on load balanc!ng me"hod 'or appl!ca"!ons
"ha" ha&e shor"?l!&ed connec"!ons such as crea"ed b
oci$connect%& !n >u!c( scr!p"s. Th!s uses CPU?based
s"a"!s"!cs "o d!s"r!bu"e connec"!ons.
K3MY Use 'or appl!ca"!ons "ha" ha&e long?l!&ed connec"!ons such
as crea"ed b oci$pconnect%&. Th!s uses a s!mple sess!on?
based me"r!c "o d!s"r!bu"e connec"!ons
(01
CH,PTE: 15
PHP ,N# TI5ESTEN IN75E5O:G
#,T,),SE
T!mesTen !s an !n?memor da"abase "ha" can be used s"andalone or as a cache "o Oracle
da"abase. The produc" mar(e"!ng descr!p"!on g!&es "h!s o&er&!e+)
Oracle )i+es)en .n3!e+ory Database N)i+es)enO is a *ull3*eatured, +e+ory3
opti+ied, relational database ,ith persistence and recoverability" .t provides
applications ,ith the instant responsiveness and very high throughput reDuired by
database3intensive applications" Deployed in the application tier, )i+es)en operates
on databases that *it entirely in physical +e+ory N:A!O" Applications access the
)i+es)en database using standard SEF inter*aces" (or custo+ers ,ith existing
application data residing on the Oracle Database, )i+es)en is deployed as an in3
+e+ory cache database ,ith auto+atic data synchroniation bet,een )i+es)en and
the Oracle Database"
The na"!&e C !n"er'ace "o T!mesTen !s OD-C bu" "here !s an Oracle OC: laer on "op o' "h!s "ha"
allo+s some s"andard PHP OC:$ 'ea"ures "o +or(. Mou can bu!ld PHP OC:$ and connec" "o bo"h
Oracle Da"abase and T!mesTen :n?Memor Da"abase.
Man bas!c PHP scr!p"s +!ll +or( unchanged aga!ns" e!"her da"abase. Ho+e&er, T!mesTen
!s a d!''eren" da"abase "han Oracle Da"abase. 4ome PHP OC:$ 'ea"ures canno" be e/pec"ed "o
+or( "he same +a, or donA" +or( a" all. :n par"!cular .O- suppor" 'rom PHP OC:$ !s no"
a&a!lable, e&en "hough T!mesTen 11g Release 2 allo+s .O-4 "o be s"ored. Collec"!on suppor"
!snA" a&a!lable and ou m!gh" e/per!ence some edge cases +!"h b!nd!ng, par"!cularl !' our
code !s no" +ell 'ormed. ;rror messages m!gh" d!''er. :' ou are m!gra"!ng e/!s"!ng appl!ca"!ons
"o T!mesTen !s also !mpor"an" "o "es" "horoughl because T!mesTen does no" suppor" all 4B.,
P.<4B. or da"abase 'ea"ures o' Oracle Da"abase. Problem resolu"!on 'or us!ng PHP +!"h
T!mesTen !s &!a OT7 'orums, +h!ch !s "he same as 'or PHP +!"h Oracle Da"abase.
7a"!&e OD-C appl!ca"!ons +!ll generall be much 'as"er "han PHP due "o "he o&erheads o'
PHP, some o&erheads o' "he Oracle OC: laer "ha" s!"s on "op o' T!meTenAs na"!&e OD-C %P:,
and due "o "he scale?ou" arch!"ec"ure commonl used b PHP appl!ca"!ons no" be!ng d!rec"l
congruen" +!"h "he !n?memor h!gh per'ormance des!gn o' T!mesTen.
In!talling Ti1e!Ten on 'inu
:ns"all T!mesTen 'ollo+!ng "he Oracle )i+es)en .n3!e+ory Database .nstallation Guide &&"
These s"eps are summar!1ed belo+ us!ng OJ?b!" Oracle .!nu/ O.
1. Do+nload @T!mesTen 11.2.2.2.0 'or .!nu/ /$O COJ?b!"F@ 'rom "he T!mesTen do+nloads
page, http://www.oracle.com/technetwork/products/timesten/downloads/
2. %s root, crea"e a ne+ so'"+are o+ner and se" a pass+ord)
Q useradd -m -c ":imes:en 3wner" -d /home/ttadmin -s //in//ash ttadmin
Q chmod U55 /home/ttadmin
Q passwd ttadmin
(02
!H! and TimesTen 'n:emory Data5ase
I. Crea"e a ne+ ti+esten group and add "he T!mesTen adm!n!s"ra"or and "he %pache users
"o !")
Q groupadd timesten
Q usermod -a -Y timesten ttadmin
Q usermod -a -Y timesten apache
J. Crea"e "he !ns"ance reg!s"r)
Q mkdir /etc/:imes:en
Q chgrp ttadmin /etc/:imes:en
Q chmod UU0 /etc/:imes:en/
H. .og!n as "he ttad+in user.
O. :n a "erm!nal, e/"rac" "he do+nloaded so'"+are arch!&e)
) tar -.' /tmp/timesten112220.linu.8PPD.tar.gX
P. :ns"all T!mesTen)
) cd linu.8PPD
) ./setup.sh
%ccep" "he de'aul" &alues except 'or "he 3roup and "he Bu!c(4"ar" >ues"!ons. The
promp"s are ans+ered)
:ns"ance name) tt1122
:ns"all "he @Cl!en"<4e&er and Da"a manager@
:ns"all !n"o /home/ttadmin
Crea"e "he daemon d!rec"or /home/ttadmin/:imes:en/tt1122/in'o
Daemon logs are !n /home/ttadmin/:imes:en/tt1122/in'o
De'aul" por" 'or "he T!mesTen daemon) 5@@9P
Change "he group "o res"r!c" access 'rom ttadmin "o ti-esten.
;nable P.<4B.
:M7$6LN5M !s s(!pped and le'" unse"
The T!mesTen ser&er l!s"ens on 5@@9U
:ns"all "he Bu!c(4"ar" and Documen"a"!on) yes CTh!s !s no" "he de'aul".F
Crea"e "he DemoDa"a4"ore !n /home/ttadmin/:imes:en/tt1122/in'o
Do no" use Repl!ca"!on +!"h Oracle Clus"er+are
$. :' ou +an" "he da"abase "o s"ar" +hen "he mach!ne boo"s, log!n as "he roo" user and
'ollo+ "he s"eps g!&en on "he screen "o !ns"all "he s"ar"up scr!p"s !n ;etc;init"d'
Q cd /home/ttadmin/:imes:en/tt1122//in
Q ./setuproot -install
T!mesTen +!ll no+ be runn!ng.
5anaging Ti1e!Ten
The ;ho+e;ttad+in;)i+es)en;tt&&22;Duic1start;ttDuic1startenv"sh scr!p" !s a con&en!en" +a
"o se" en&!ronmen" &ar!ables be'ore access!ng "he sample da"abase.
(13
:anaging TimesTen
%s "he ttad+in user, chec( "he s"a"us o' "he !ns"ance b se""!ng "he en&!ronmen" and
runn!ng "he ttstatus command)
) source /home/ttadmin/:imes:en/tt1122/"uickstart/tt"uickstartenC.sh
) ttstatus
Th!s g!&es)
:imes:en status report as o' Non Tun 18 12:DD:50 2012
Laemon pid 2@P29 port 5@@9P instance tt1122
:imes:en serCer pid 2@P@8 started on port 5@@9U
----------------------------------------------------
Lata store /home/ttadmin/:imes:en/tt1122/in'o/LemoLata7tore/sampled/$1122
:here are no connections to the data store
Beplication polic# : Nanual
4ache 6gent polic# : Nanual
EK/7SK ena/led.
-----------------------------------------------------
6ccessi/le /# group timesten
-nd o' report
There !s a command?l!ne "ool 'or runn!ng ad hoc >uer!es aga!ns" an !ns"ance)
) ttis"l "dsn*sampled/$1122!uid*appuser"
:ns"all!ng "he sample da"abase !s sho+n !n "he ne/" sec"!on. The de'aul" appuser pass+ord !s
oracle.
:' ou need "o manuall s"op or s"ar" "he !ns"ance o' T!mesTen, log!n as ttad+in, se" "he
en&!ronmen", and run)
) ttdaemonadmin -start
or
) ttdaemonadmin -stop
:' ou +an" "o remo&e "he !ns"ance o' T!mesTen, '!rs" s"op !" and "hen, as root, run)
Q cd /home/ttadmin
Q :imes:en/tt1122//in/setup.sh -uninstall
Creating the Ti1e!Ten Sa1ple #ata$a!e
Crea"e "he sample da"abase b logg!ng !n as "he ttad+in opera"!ng ss"em user and 'ollo+!ng
"hese s"eps)
1. Run "he crea"!on scr!p")
) cd 2 /home/ttadmin/:imes:en/tt1122/"uickstart/sample$scripts/created/
) .//uild$sampled/.sh
2. Choose and remember pass+ords +hen promp"ed 'or "he ad+, appuser and xlauser
users.
(1&
!H! and TimesTen 'n:emory Data5ase
In!talling ,pache and PHP *or Ti1e!Ten
The pac(aged %pache and PHP b!nar!es are used belo+, bu" !ns"alla"!on can be cus"om!1ed as
needed us!ng s"eps sho+n earl!er !n "h!s boo(.
:ns"all %pache and PHP +!"h)
1. %s roo", use "he bundled pac(ages 'or "he +eb ser&er and 'or PHP)
Q #um install httpd php php-deCel
2. ;d!" ;etc;php"ini and add a "!me1one se""!ng us!ng an appropr!a"e "!me1one, 'or e/ample)
date.timeXone * 6merica/Kos$6ngeles
I. Do+nload "he la"es" OC:$ e/"ens!on 'rom P;C.. ;/"rac" and !ns"all !" +!"h)
Q tar -.' oci8-1.D.9.tgX
Q cd oci8-1.D.9
Q phpiXe
Q ./con'igure Vwith-oci8*instantclient+2
/home/ttadmin/:imes:en/tt1122/ttoracle$home/instantclient$11$2
Q make
Q make install
J. ;d!" ;etc;php"ini and add)
e.tension*oci8.so
H. Con'!gure %pache. :n ;etc;syscon*ig;httpd se" T74N%DM:7 and .DN.:-R%RMNP%TH)
::*/home/ttadmin/:imes:en/tt1122
e.port :M7$6LN5M*)::/network/admin/samples
e.port KL$K5IB6B;$E6:>*)::/li/:)::/ttoracle$home/instantclient$11$2
O. Ma(e sure 4;.!nu/ !s !n Perm!ss!&e mode b ed!"!ng ;etc;syscon*ig;selinux and reboo"!ng.
%l"erna"!&el "urn !" o'' "emporar!l +!"h)
Q seten'orce permissiCe
Chec=ing the In!tallation
Use "he httpd ser&!ce !' ou manuall need "o s"op and res"ar" %pache. 4!nce "he
con'!gura"!on 8us" changed +hen OC:$ +as !ns"alled, res"ar" !" no+)
Q serCice httpd restart
Tes" PHP b crea"!ng a '!le ;var;,,,;ht+l;pi"php)
<?php
phpin'o%&!
?
.oad "h!s !n a bro+ser us!ng http';;localhost;pi"php. Mou +!ll ge" "he normal page o'
con'!gura"!on !n'orma"!on abou" PHP. Chec( "here !s a sec"!on 'or OC:$.
(1(
Connecting to TimesTen With !H! .C'1
Connecting to Ti1e!Ten With PHP OCI.
The ttisDl e/ample g!&en earl!er sho+s "he creden"!als and connec" s"r!ng 'or "he sample
da"abase. These can be used !n PHP scr!p"s "o connec" "o T!mesTen. Tes" +!"h a bas!c >uer
scr!p" such as ;var;,,,;ht+l;oci/tt"php)
Script &25' ;var;,,,;ht+l;oci/tt"php
<?php
)c * oci$connect%"appuser"+ "oracle"+ "sampled/$1122"&!
i' %8)c& (
)m * oci$error%&!
trigger$error%04ould not connect to data/ase: 0 .
)m90message0<+ -$R7-B$-BB3B&!
=
)s * oci$parse%)c+ "select J 'rom emp"&!
i' %8)s& (
)m * oci$error%)c&!
trigger$error%04ould not parse statement: 0 .
)m90message0<+ -$R7-B$-BB3B&!
=
)r * oci$e.ecute%)s&!
i' %8)r& (
)m * oci$error%)s&!
trigger$error%04ould not e.ecute statement: 0 .
)m90message0<+ -$R7-B$-BB3B&!
=
echo "<ta/le /order*0102n"!
while %%)row *
oci$'etch$arra#%)s+ 345$67734H345$B-:RBM$MRKK7&& 8* 'alse& (
echo "<tr2n"!
'oreach %)row as )item& (
echo " <td".%)item 8** null ? htmlentities%)item+
-M:$SR3:-7& : "^n/sp!"&."</td2n"!
=
echo "</tr2n"!
=
echo "</ta/le2n"!
?
.oad "h!s !n a bro+ser +!"h http';;localhost;oci/tt"php. The >uer resul"s +!ll be d!splaed !n a
"able.
:' ou ge" a blan( screen or ha&e problems, chec( "he %pache log !n
;var;logs;httpd;error=log.
Con*iguring Ti1e!Ten
The de'aul" R%M pol!c o' T!mesTen !s in#se, mean!ng "ha" "he da"abase !s loaded !n"o
memor a" "!me o' '!rs" connec"!on, and unloaded +hen "he las" connec"!on comple"es. Th!s
(1)
!H! and TimesTen 'n:emory Data5ase
means "ha" "he '!rs" and las" connec"!ons can be slo+. Th!s !s mos" no"!ceable !' ou are us!ng
command l!ne scr!p"s or us!ng non?pers!s"en" connec"!ons.
Mou can change "he in#se grace per!od or al"er "he R%M pol!c +!"h ttBamEolic#7et%& "o
o&ercome "h!s. The changed &alue !s pers!s"en".
0!"h an in#se pol!c, "he slo+ unload?on?las"?connec" !ssue can be resol&ed b se""!ng a
grace per!od "!me "he da"abase !s (ep" !n R%M a'"er "he las" appl!ca"!on has d!sconnec"ed. 2or
e/ample "h!s PHP code se"s !" "o '!&e seconds, de'err!ng "he da"abase shu"do+n and allo+!ng
"he PHP appl!ca"!on "o close "he las" connec"!on +!"hou" dela)
)s * oci$parse%)cc+ "call ttBamEolic#7et%0inRse0+ 5&"&!
oci$e.ecute%)s&!
Ho+e&er !ns"ead o' in#se, a general recommenda"!on !s "o change "he R%M pol!c "o +anual'
)s * oci$parse%)cc+ "call ttBamEolic#7et%0manual0+ null&"&!
oci$e.ecute%)s&!
0!"h "h!s done, be'ore runn!ng appl!ca"!ons, ou mus" e/pl!c!"l load "he da"abase !n"o R%M b
us!ng "he ttAd+in u"!l!")
) tt6dmin -ramKoad
0hen "he da"abase !s no longer needed !" can be unloaded +!"h)
) tt6dmin -ramRnKoad
The T!mesTen manual d!scusses R%M pol!c!es and g!&es o"her op"!ons.
(1*
CH,PTE: 1(
PHP ,N# O:,C'E T04E#O
Oracle Tu/edo !s a "ransac"!on or!en"ed appl!ca"!on ser&er +h!ch can be used 'or de&elop!ng
and deplo!ng appl!ca"!ons +r!""en !n PHP, P"hon and Rub, as +ell as !n "he "rad!"!onal
languages C, C__, and CO-O.. Tu/edo !s based on a rou"!ng and >ueu!ng ss"em, +h!ch !s
h!ghl con'!gurable.
Th!s chap"er sho+s us!ng Oracle Tu/edo 11.1 +!"h PHP appl!ca"!ons runn!ng under %pache.
HTTP re>ues"s are 'or+arded 'rom %pache "o +od=tuxedo +h!ch "hen !n&o(es "he PHP scr!p"
eng!ne.
The +od=tuxedo componen" 'or handl!ng PHP Cand P"hon and RubF +eb re>ues"s !s l!censed
+!"h Oracle Service Architecture Feveraging )uxedo NSAF)O . :" !s a&a!lable on .!nu/ and
4olar!s. :" !s !ncluded !n 4%.T 'rom 11.1.1.2.2 on+ards. :n Tu/edo 12c, !" !s par" o' "he base
Tu/edo componen".
There !s a pre?con'!gured demons"ra"!on )uxedo Web Application Server De+o 7! 'or
,!r"ual-o/ a&a!lable "ha" sho+s s!m!lar e/amples "o "h!s chap"er. :" can be 'ound on "he
Tu/edo do+nload page)
http://www.oracle.com/technetwork/middleware/tu.edo/downloads/inde..html.
0!"h a ser&!ce or!en"a"ed arch!"ec"ure, Tu/edo also allo+s mul"!ple languages, !nclud!ng
PHP, "o be used as ser&!ce consumers and producers. Th!s !s no" co&ered !n "h!s manual.
In!talling Tuedo 11.1 and S,'T *or PHP We$ ,pplication!
-eg!n b re&!e+!ng "he prere>u!s!"es !n "he documen"a"!on a"
http://www.oracle.com/technetwork/middleware/tu.edo/documentation/inde..html.
(1+
(igure ?6' Oracle SAF) Web Appliction Server Architecture
!H! and .racle Tu%edo
Remember "o "urn o'' 4;.!nu/ be'ore beg!nn!ng "he !ns"alla"!on b ed!"!ng
;etc;syscon*ig;selinux and reboo"!ng.
In!talling Oracle Tuedo
To !ns"all Tu/edo, 'ollo+ "hese s"eps)
1. Crea"e a user "o be "he Tu/edo adm!n!s"ra"or and log!n as "ha" user, 'or e/ample c0ones"
2. :' ou !n"end "o run "he opera"!ng ss"em pac(aged %pache, ma(e "he ne+ user d!rec"or
readable "o "he +ebser&er)
) chmod U55 /home/cWones
I. Do+nload Oracle )uxedo &&g:& N&&"&"&"2"AO 'rom
http://www.oracle.com/technetwork/middleware/tu.edo/downloads/inde..html
J. Run "he Tu/edo !ns"aller)
) sh tu.edo111120$PD$Kinu.$01$.8P./in
H. % 3U: appears. 4"ar" "he menu b cl!c(!ng 2ext)
(1-
(igure ?5' Oracle )uxedo .nstaller .ntroduction
'nstalling Tu%edo &&D& and #ALT Aor !H! We5 Applications
O. Do a (ull .nstall)
P. Crea"e a ne+ Oracle Ho+e. Here, "he d!rec"or ;ho+e;c0ones;oracle +as chosen)
(10
(igure ?9' Oracle )uxedo -hoosing the Oracle Ho+e
(igure ?4' Oracle )uxedo .nstall Set !enu
!H! and .racle Tu%edo
$. :ns"all "he 4amples b chec(!ng "he bo/ !n "he bo""om r!gh" o' "he !ns"aller. .ea&e "he
Produc" :ns"alla"!on D!rec"or as "he de'aul".
L. Con'!rm "he !ns"alla"!on)
(11
(igure ??' Oracle )uxedo -hoosing the Product Directory
(igure ?/' Oracle )uxedo Pre3.nstallation Su++ary
'nstalling Tu%edo &&D& and #ALT Aor !H! We5 Applications
10. :n "he pos" !ns"alla"!on se"up, ;n"er a pass+ord 'or tlisten. Th!s +onA" be used 'or "h!s
e/ample)
11. 2or "h!s e/ample, comple"e "he !ns"alla"!on b choos!ng 2o "o con'!gur!ng .D%P !n "he 44.
:ns"alla"!on Cho!ce menu)
(12
(igure /A' Oracle )uxedo SSF -on*iguration
(igure ?8' Oracle )uxedo RtlistenR con*iguration
!H! and .racle Tu%edo
In!talling Oracle S,'T
To !ns"all Oracle 4%.T 'ollo+ "hese !ns"ruc"!ons)
1. Do+nload Oracle Service Architecture Feveraging )uxedo NSAF)O &&g:& N&&"&"&"2"2O 'rom
http://www.oracle.com/technetwork/middleware/tu.edo/downloads/inde..html
2. Run "he 4%.T !ns"aller)
) sh salt111122$PD$Kinu.$01$.8P./in
I. 4"ar" "he menu b cl!c(!ng 2ext)
J. :ns"all !n"o "he same home as Tu/edo, ;ho+e;c0ones;oracle'
(23
(igure /&' Oracle SAF) .nstallation .ntroduction
'nstalling Tu%edo &&D& and #ALT Aor !H! We5 Applications
H. Choose "o !ns"all "he SAF) -lient and Server. The cl!en" !s 'or "he 4er&!ce Componen"
%rch!"ec"ure +h!ch ma(es componen"s d!s"r!bu"able)
O. Re&!e+ "he !ns"all op"!ons and cl!c( .nstall)
(2&
(igure /2' Oracle SAF) -hoosing the Ho+e Directory
(igure /6' Oracle SAF) .nstall Set -hoice
!H! and .racle Tu%edo
P. The !ns"alla"!on o' 4%.T !s comple"e)
(2(
(igure /5' Oracle SAF) .nstallation :evie,
(igure /4' Oracle SAF) .nstallation -o+pletion
'nstalling !H! Aor .racle Tu%edo
In!talling PHP *or Oracle Tuedo
PHP mus" be bu!l" +!"h "he e+bded op"!on so !" can be loaded b +od=tuxedo.
1. :ns"all Oracle :ns"an" Cl!en" 'or "he PHP OC:$ ;/"ens!on. Do+nload "he basic and devel
pac(ages 'rom http://www.oracle.com/technetwork/data/ase/'eatures/instant-
client/inde.-09UD80.html and !ns"all +!"h)
Q rpm -i oracle-instantclient11.2-/asic-11.2.0.@.0-1..8P$PD.rpm
Q rpm -i oracle-instantclient11.2-deCel-11.2.0.@.0-1..8P$PD.rpm
2. Do+nload PHP 'rom http://php.net/downloads.php. Use PHP H.I.2 or h!gher.
I. ;/"rac", con'!gure and !ns"all PHP +!"h "he embedded op"!on, 'or e/ample +!"h)
) tar -W.' php-5.D.D.tar./X2
) cd php-5.D.D
) ./con'igure --pre'i.*/home/cWones/php --with-oci8*instantclient 2
--ena/le-em/ed
) make install
:n "h!s e/ample, OC:$ +!ll au"oma"!call loca"e "he :ns"an" Cl!en" RPMs. %d8us" "he
con'!gura"!on l!ne !' ou use Oracle cl!en" l!brar!es !n a d!''eren" loca"!on. Re'er "o "he
chap"er .nstalling and -on*iguring PHP"
J. Cop a php.!n! con'!gura"!on '!le)
) cp php8.ini-deCelopment )>3N-/php/li//php.ini
H. ;d!" "he ne+ php"ini and se" "he "!me 1one, 'or e/ample)
date.timeXone * 6merica/Kos$6ngeles
These s"eps ha&e crea"ed "he shared, embedded l!brar ;ho+e;c0ones;php;lib;libphp4"so"
In!talling Oracle Tuedo into ,pache
1. Tp!call Tu/edo !s !ns"alled !n Oracle HTTP 4er&er as sho+n !n "he Tu/edo manuals.
Ho+e&er 'or "h!s e/ample "he pac(aged ss"em %pache !s used.
;d!" ;etc;httpd;con*;httpd"con* and, 'or "he dura"!on o' "h!s e/ample, change "he user
and group so "ha" %pache runs as "he Tu/edo so'"+are o+ner, 'or e/ample)
Rser cWones
Yroup cWones
Mou could al"erna"!&el !ns"all %pache 2.2 as "he Tu/edo so'"+are o+ner, con'!gur!ng
!", 'or e/ample, +!"h ";con*igure 33pre*ixCJHO!E;apache 33enable3so 33,ith3
portC////" Mod!' an pa"hs sugges"ed belo+ !' ou choose "h!s op"!on.
2. %s "he roo" users, cop "he Tu/edo module !n"o %pacheAs modules d!rec"or)
Q cp /home/cWones/oracle/tu.edo11gB1/udatao/W/mod$tu.edo.so 2
/etc/httpd/modules/
I. :n ;etc;httpd;con*;httpd"con* load +od=tuxedo"so)
(2)
!H! and .racle Tu%edo
KoadNodule tu.edo$module modules/mod$tu.edo.so
J. %lso !n httpd"con*, loca"e "he D!rec"or d!rec"!&e 'or "he documen" roo" ;var;,,,;ht+l"
%dd an L.*!odule +od=tuxedo"cM bloc( a" "he bo""om o' "he sec"!on)
<Lirector# "/Car/www/html"
. . .
<5'Nodule mod$tu.edo.c
6dd>andler tu.edo-script .php
:u.7erCice m#phpdemo
:u.4on'ig /home/cWones/phpdemo/tu.con'ig
</5'Nodule
</Lirector#
Th!s 'or+ards re>ues"s 'or PHP '!les loca"ed !n %pacheAs documen" roo" d!rec"or "o
"he +yphpde+o ser&!ce o' Tu/edo +h!ch !s descr!bed !n "he
;ho+e;c0ones;phpde+o;tuxcon*ig con'!gura"!on '!le. The ne/" s"eps sho+ ho+ "o
crea"e "h!s ser&!ce and ho+ "o crea"e "he con'!gura"!on '!le. Change "he user d!rec"or
c0ones "o our Tu/edo so'"+are o+ner.
-ecause !" !s Tu/edo "ha" !n&o(es PHP, ou could also con'!gure %pache "o run !n "he
more e''!c!en" "hreaded mode "han "he s"andard %pache +od=php uses.
Con*iguring Oracle Tuedo *or PHP
The sample PHP appl!ca"!on does a da"abase >uer. 2ollo+ "hese s"eps "o con'!gure Tu/edo)
1. Ma(e a d!rec"or 'or "he sample appl!ca"!onAs con'!gura"!on)
) mkdir )>3N-/phpdemo
2. Crea"e a Tu/edo @Un!&ersal -ulle"!n -oard@ con'!gura"!on '!le. The s"a"e o' a Tu/edo
ss"em !s (ep" !n a Dbulle"!n boardE, hence "he con'!gura"!on '!le name. % b!nar &ers!on o'
"h!s con'!gura"!on '!le +!ll be used b Tu/edo adm!n!s"ra"!&e commands. 2or "h!s e/ample
"he con'!gura"!on '!le JHO!E;phpde+o;ubbphpde+o con"a!ns)
JB-73RB4-7
5E4G-; 12@D5P
L3N65M5L phpdemoapp
N67:-B phpdemo
N6,644-77-B7 50
N6,7-BZ-B7 50
N6,7-BZ54-7 100
N3L-K 7>N
KLI6K M
JN64>5M-7
L-A6RK::
6EEL5B*"/home/cWones/phpdemo"
(2*
ConAiguring .racle Tu%edo Aor !H!
:R,43MA5Y*"/home/cWones/phpdemo/tu.con'ig"
:R,L5B*"/home/cWones/oracle/tu.edo11gB1"
"localhost.localdomain" KN5L*phpdemo
JYB3RE7
YB3RE1
KN5L*phpdemo YBEM3*1 3E-M5MA3*M3M-
J7-BZ-B7
L-A6RK::
4K3E:*"-6"
?-I>MLKB 7BZYBE*YB3RE1 7BZ5L*1 4K3E:*"-6 -- -l E>E -7 m#phpdemo"
N5M*5 N6,*50 B-7:6B:*; N6,Y-M*255
J7-BZ54-7
Change c0ones !n "he d!rec"or pa"hs "o our user name. TU=CO72:3 g!&es "he name
o' "he b!nar '!le "ha" ubbphpde+o +!ll be comp!led "o, as sho+n !n "he ne/" sec"!on.
The :PC6;M &alue se"s "he address o' shared memor, e''ec"!&el Dnam!ngE "he
bulle"!n board.
The M%=%CC;44;R4, M%=4;R,;R4 and M%=4;R,:C;4 &alues con'!gure "he s!1e o'
Tu/edo da"a s"ruc"ures, de"erm!n!ng "he l!m!"s o' "he ss"em. One PHP appl!ca"!on !s
one ser&!ce. ;ach HTTP re>ues" +!ll be sen" "o a ser&er 'or process!ng.
M%=%CC;44;R4 !s "he number o' cl!en"s and ser&ers "ha" can connec" "o "he bulle"!n
board.
The MOD;. !s se" "o 4HM 'or Dshared memorE, +h!ch !s su!"able 'or "h!s
demons"ra"!onAs s!ngle mach!ne se"up.
The load balancer con"rol, .D-%., !s se" "o 2 as recommended 'or a s"andalone
ser&er.
O"her op"!ons e/!s", such as -.OC6T:M; 'or l!m!"!ng "he re>ues" "!me. The general U--
con'!gura"!on op"!ons are documen"ed !n "he #II-O2(.GN4O sec"!on o' "he (ile
(or+ats, Data Descriptions, !.Is, and Syste+ Processes :e*erence
http://docs.oracle.com/cd/-18050$01/tu.edo/docs11gr1/r'5/r'5.htmlQwp@@U0
051. There are o"her e/amples o' con'!gura"!on '!les !n "he e/ample d!rec"or!es under
JHO!E;oracle;tuxedo&&g:&;sa+ples;at+i.
The 0;-H7D.R en"r !s a ss"em process ser&er used +!"h +od=tuxedo 'or scr!p"s
+r!""en !n PHP, P"hon or Rub. :n "h!s e/ample, !" !s de'!ned "o handle PHP re>ues"s.
The name +yphpde+o ma"ches "he Tu/4er&!ce name !n httpd"con*. 0;-H7D.R
sn"a/ !s sho+n !n "he Oracle SAF) -o++and :e*erence
http://docs.oracle.com/cd/-18050$01/salt/docs11gr1/re'/comre'.htmlQwp118
5@0@.
(2+
!H! and .racle Tu%edo
Mour mach!ne name mus" be g!&en !n "he M%CH:7;4 sec"!on o' ubbphpde+o. 0!"hou"
"h!s, "he t+loadc* command Cused !n "he ne/" sec"!onF +!ll 'a!l +!"h -!D)#<=-A)'/9/
E::O:' t+loadc* cannot run on a non3+aster node. Use "he name re"urned b our
hostna+e command. :' our mach!ne has a long DHCP genera"ed name, ou can
"emporar!l se" a shor"er name b e/ecu"!ng "h!s as roo")
Q hostname phptu.
Ho+e&er !' ou do "h!s command, connec"!ons "o an Oracle da"abase +!ll 'a!l +!"h
O:A3255A/' could not generate uniDue server group na+e unless ou also add "he
name "o ;etc;hosts)
12U.0.0.1 localhost.localdomain localhost phptu.
Mou can also se" "he name !n httpd"con* "o a&o!d an %pache +arn!ng +hen "he +eb
ser&er !s s"ar"ed)
7erCerMame phptu.:80
I. -u!ld "he b!nar con'!gura"!on '!le 'rom ubbphpde+o)
) cd )>3N-/phpdemo
) source enC.sh
) tmloadc' -# u//phpdemo
Th!s crea"es "he '!le tuxcon*ig spec!'!ed b "he ubbphpde+o TU=CO72:3 d!rec"!&e.
Tu/edo uses tuxcon*ig "o se" up "he Dbulle"!n boardE on each ser&er mach!ne !n "he
Tu/edo doma!n.
Starting and 5anaging Tuedo
1. Crea"e a '!le JHO!E;phpde+o;env"sh "o se" "he en&!ronmen" 'or Tu/edo adm!n!s"ra"!on
commands)
e.port :R,L5B*)>3N-/oracle/tu.edo11gB1
e.port E6:>*):R,L5B//in:)E6:>
e.port KL$K5IB6B;$E6:>*):R,L5B/li/:)>3N-/php/li/:)KL$K5IB6B;$E6:>
e.port 6EEL5B*)>3N-/phpdemo
e.port :R,43MA5Y*)6EEL5B/tu.con'ig
e.port AKL:IKL5B@2*):R,L5B/udatao/W
e.port A5-KL:IK7@2*http.'ml@2
The D'!eld "ableE httpd"*+l62 maps "he HTTP header '!elds 'or +od=tuxedo. The l!brar
pa"h !ncludes "he loca"!on o' "he PHP embedded l!brar.
2. Run "he '!le "o se" "he en&!ronmen")
) source #$O%E/phpdemo/enC.sh
I. %pache needs "he same en&!ronmen". ;d!" ;etc;syscon*ig;httpd and add "hese &ar!ables)
e.port :R,L5B*/home/#ouruser/oracle/tu.edo11gB1
e.port AKL:IKL5B@2*):R,L5B/udatao/W
e.port A5-KL:IK7@2*http.'ml@2
(2-
#tarting and :anaging Tu%edo
e.port KL$K5IB6B;$E6:>*):R,L5B/li/:)KL$K5IB6B;$E6:>
:' ou !ns"alled our o+n %pache 2.2, add "he &ar!ables "o "he envvars '!le, 'or
e/ample ;opt;apache;bin;envvars, or o"her+!se ma(e sure "he shell "ha" s"ar"s %pache
has "he &alues se".
7o"e "ha" %pache does no" !n&o(e PHP and doesnA" need "he PHP l!brar d!rec"or !n
.DN.:-R%RMNP%TH.
J. Use t+boot "o s"ar" Tu/edo as "he Tu/edo so'"+are o+ner)
) t-boot <,
Iooting all admin and serCer processes in /home/cWones/phpdemo/tu.con'ig
5MA3: 3racle :u.edo+ Zersion 11.1.1.2.0+ PD-/it+ Eatch KeCel %none&
Iooting admin processes ...
e.ec IIK -6 :
process id*@P25 ... 7tarted.
Iooting serCer processes ...
e.ec ?-I>MLKB -6 -- -l E>E -7 m#phpdemo :
process id*@P2P ... 7tarted.
e.ec ?-I>MLKB -6 -- -l E>E -7 m#phpdemo :
process id*@P2U ... 7tarted.
e.ec ?-I>MLKB -6 -- -l E>E -7 m#phpdemo :
process id*@P28 ... 7tarted.
e.ec ?-I>MLKB -6 -- -l E>E -7 m#phpdemo :
process id*@P29 ... 7tarted.
e.ec ?-I>MLKB -6 -- -l E>E -7 m#phpdemo :
process id*@P@0 ... 7tarted.
P processes started.
Mou can see "he ser&!ces runn!ng b us!ng t+ad+in, +h!ch g!&es !n'orma"!on abou"
"he Tu/edo @-ulle"!n -oards@)
) tmadmin
printserCice
7erCice Mame Boutine Mame Erog Mame Yrp Mame 5L Nachine Q Lone 7tatus
------------ ------------ --------- -------- -- ------- ------ ------
m#phpdemo 7Z4?-I ?-I>MLKB YB3RE1 1 simple 0 6Z65K
7Z4?-I 7Z4?-I ?-I>MLKB YB3RE1 1 simple 0 6Z65K
m#phpdemo 7Z4?-I ?-I>MLKB YB3RE1 2 simple 0 6Z65K
7Z4?-I 7Z4?-I ?-I>MLKB YB3RE1 2 simple 0 6Z65K
m#phpdemo 7Z4?-I ?-I>MLKB YB3RE1 @ simple 0 6Z65K
7Z4?-I 7Z4?-I ?-I>MLKB YB3RE1 @ simple 0 6Z65K
m#phpdemo 7Z4?-I ?-I>MLKB YB3RE1 D simple 0 6Z65K
7Z4?-I 7Z4?-I ?-I>MLKB YB3RE1 D simple 0 6Z65K
m#phpdemo 7Z4?-I ?-I>MLKB YB3RE1 5 simple 0 6Z65K
7Z4?-I 7Z4?-I ?-I>MLKB YB3RE1 5 simple 0 6Z65K
2or more !n'orma"!on on t+ad+in see )he #se o* t+ad+inN&O !n
http://docs.oracle.com/cd/-1@20@$01/tu.edo/tu.PD/tag/adminops.htm.
(20
!H! and .racle Tu%edo
There !s a separa"el !ns"allable Oracle )uxedo Syste+ and Application !onitor
N)SA!O 'or Tu/edo "ha" can be used "o mon!"or and manage "he Tu/edo and 4%.T. :"
!ncludes graph!ng and aler"!ng 'unc"!onal!". Da"a can be &!e+ed !n real "!me or
h!s"or!call. T4%M !s a&a!lable 'rom "he Tu/edo +eb pages,
http://www.oracle.com/us/products/middleware/tu.edo/tsam/inde..html.
H. To handle re>ues"s 'or PHP scr!p"s, s"ar" %pache as roo")
Q serCice httpd start
O. 0hen '!n!shed +!"h "he e/ample, shu"do+n %pache '!rs")
Q serCice httpd stop
Then shu"do+n Tu/edo as "he Tu/edo so'"+are o+ner)
) tmshutdown -#
<eri*6ing PHP and Tuedo
1. Crea"e ;var;,,,;ht+l;phpin*o"php con"a!n!ng)
<?php
phpin'o%&!
?
2. .oad "he '!le !n a bro+ser http';;localhost;phpin*o"php" The s"andard PHP con'!gura"!on
screen !s sho+n.
I. Crea"e a da"abase >uer scr!p", ;var;,,,;ht+l;ocitux"php)
Script &' ocitux"php
<?php
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "select cit# 'rom locations"&!
oci$e.ecute%)s&!
echo "<ta/le /order*0102n"!
while %%)row * oci$'etch$arra#%)s+ 345$67734&& 8* 'alse& (
echo " <tr2n"!
echo " <td".htmlentities%)row9045:;0<+ -M:$SR3:-7&."</td2n"!
echo " </tr2n"!
=
echo "</ta/le2n"!
?
J. Th!s '!le can be run b load!ng "he UR. http';;localhost;ocitux"php)
(21
@eriAying !H! and Tu%edo
;/!s"!ng PHP appl!ca"!ons can ma(e use o' Tu/edo &!a +od=tuxedo allo+!ng "hem "o be
!n"egra"ed !n"o a h!ghl managed en&!ronmen".
(22
(igure /9' Output *ro+ ocitux"php
!H! and .racle Tu%edo
)33
CH,PTE: 1+
G'O),'I@,TION
Th!s chap"er d!scusses global appl!ca"!on de&elopmen" !n a PHP and Oracle Da"abase
en&!ronmen". :" addresses "he bas!c "as(s assoc!a"ed +!"h de&elop!ng and deplo!ng global
:n"erne" appl!ca"!ons, !nclud!ng de&elop!ng locale a+areness, cons"ruc"!ng HTM. con"en" !n
"he user?pre'erred language, and presen"!ng da"a 'ollo+!ng "he cul"ural con&en"!ons o' "he
locale o' "he user.
-u!ld!ng a global :n"erne" appl!ca"!on "ha" suppor"s d!''eren" locales re>u!res good
de&elopmen" prac"!ces. % locale re'ers "o a na"!onal language and "he reg!on !n +h!ch "he
language !s spo(en. The appl!ca"!on !"sel' mus" be a+are o' "he locale pre'erence o' "he user
and be able "o presen" con"en" 'ollo+!ng "he cul"ural con&en"!ons e/pec"ed b "he user. :" !s
!mpor"an" "o presen" da"a +!"h appropr!a"e locale charac"er!s"!cs, such as "he correc" da"e and
number 'orma"s. Oracle Da"abase !s 'ull !n"erna"!onal!1ed "o pro&!de a global pla"'orm 'or
de&elop!ng and deplo!ng global appl!ca"!ons.
E!ta$li!hing the En-iron1ent )et;een Oracle and PHP
Correc"l se""!ng up "he connec"!&!" be"+een "he PHP eng!ne and "he Oracle da"abase !s "he
'!rs" s"ep !n bu!ld!ng a global appl!ca"!on. :" guaran"ees da"a !n"egr!" across all "!ers. Mos"
:n"erne" based s"andards suppor" Un!code as a charac"er encod!ng. Th!s chap"er 'ocuses on
us!ng Un!code as "he charac"er se" 'or da"a e/change.
Setting the 'anguage? Territor6 and Character Set With N'SA',NG
OC:$ !s an Oracle OC: appl!ca"!on, and rules "ha" appl "o OC: also appl "o PHP. Oracle locale
beha&!or C!nclud!ng "he cl!en" charac"er se" used !n OC: appl!ca"!onsF !s de'!ned b OracleKs
national language support 7.4N.%73 en&!ronmen" &ar!able. Th!s en&!ronmen" &ar!able has
"he 'orm)
<language$<territor#.<character set
2or e/ample, 'or a 3erman user !n 3erman runn!ng an appl!ca"!on !n Un!code, 7.4N.%73
should be se" "o)
Y-BN6M$Y-BN6M;.6K@2R:A8
The language and "err!"or se""!ngs con"rol Oracle beha&!ors such as "he Oracle da"e 'orma",
error message language, and "he rules used 'or sor" order. The charac"er se" %.I2UT2$ !s "he
Oracle name 'or UT2?$. Mou should use a charac"er se" compa"!ble +!"h "he opera"!ng ss"em,
'or e/ample on 0!ndo+s +here "here !s no UT2?$, ou could use 0;$M40:712H2 "o ma"ch
"he ;ngl!sh 0!ndo+s code page 12H2.
:n some opera"!ng ss"em en&!ronmen"s ou ma also need "o se" "he .CN%.. and .%73
en&!ronmen" &ar!ables, 'or e/ample "hese could be added "o ;etc;syscon*ig;httpd)
e.port MK7$K6MY*AB-M4>$AB6M4-.?-85738859E1
e.port K4$6KK*'rench
e.port K6MY*'rench
)3&
,lo5alization
The 7.4N.%73 charac"er se" can also be passed as a parame"er "o "he OC:$ connec"!on
'unc"!ons. Do!ng "h!s !s recommended 'or connec"!on per'ormance reasons, e&en !' 7.4N.%73
!s also se".
:' "he charac"er se" used b PHP OC:$ does no" ma"ch "he charac"er se" used b "he
da"abase, Oracle +!ll "r "o con&er" +hen da"a !s !nser"ed and >uer!ed. Th!s ma reduce
run"!me per'ormance. %lso an accura"e mapp!ng !s no" al+as be poss!ble, resul"!ng !n da"a
be!ng con&er"ed "o >ues"!on mar(s.
There are o"her en&!ronmen" &ar!ables "ha" can be used "o se" par"!cular aspec"s o'
global!1a"!on. 2or !n'orma"!on on 7.4N.%73 and o"her Oracle language en&!ronmen" &ar!ables,
see "he Oracle documen"a"!on.
The sec"!on Setting the Oracle Environ+ent on Finux !n "he .nstalling and -on*iguring PHP
chap"er d!scusses ho+ en&!ronmen" &ar!ables can be se" 'or %pache.
:' "he global!1a"!on se""!ngs are !n&al!d, PHP ma 'a!l "o connec" "o Oracle and g!&e an error
l!(e O:A3&2?A4' -annot access 2FS data *iles or invalid environ+ent speci*ied"
4ome global!1a"!on &alues can be changed per connec"!on)
)s * oci$parse%)c+"alter session set nls$territor#*german# nls$language*german"&!
oci$e.ecute%)s&!
%'"er e/ecu"!ng "h!s, Oracle error messages +!ll be !n 3erman and some local!1a"!on 'ea"ures
such as "he de'aul" da"e 'orma" +!ll ha&e changed.
Cau"!on) 0hen chang!ng "he sess!on se""!ngs 'or a persistent PHP connec"!on, "he ne/" "!me
"he connec"!on !s used, "he old &alues +!ll s"!ll be !n e''ec".
:' PHP !s !ns"alled on Oracle HTTP 4er&er, ou mus" se" 7.4N.%73 as an en&!ronmen" &ar!able
!n JO:A-FE=HO!E;op+n;con*;op+n"x+l)
<ias-component id*">::E$7erCer"
<process-t#pe id*">::E$7erCer" module-id*"3>7"
<enCironment
<Caria/le id*"E-BK5K5I"
Calue*"L:2oracle21012T2--26pache26pache2mod$perl2site25.P.12li/"/
<Caria/le id*"E>EB4" Calue*"L:2oracle21012T2--26pache26pache2con'"/
<Caria/le id*"MK7$K6MY" Calue*"german$german#.al@2ut'8"/
</enCironment
<module-data
<categor# id*"start-parameters"
<data id*"start-mode" Calue*"ssl-disa/led"/
</categor#
</module-data
<process-set id*">::E$7erCer" numprocs*"1"/
</process-t#pe
</ias-component
Mou mus" res"ar" "he 0eb l!s"ener "o !mplemen" "he change.
To '!nd "he language and "err!"or curren"l used b PHP, and "he charac"er se" +!"h +h!ch
"he da"abase s"ores da"a, e/ecu"e)
)s * oci$parse%)c+
"select s#s$conte.t%0userenC0+ 0language0& as nls$lang 'rom dual"&!
)3(
4sta5lishing the 4n$ironment >et/een .racle and !H!
oci$e.ecute%)s&!
)res * oci$'etch$arra#%)s+ 345$67734&!
echo )res90MK7$K6MY0< . "2n"!
Ou"pu" !s o' "he 'orm)
6N-B546M$6N-B546.?-8N7?5M1252
Setting the Oracle Nu1$er 9or1at With N'SAN05E:ICACH,:,CTE:S
OC:$ 'e"ches numbers as PHP s"r!ngs. The con&ers!on !s done b Oracle be'ore "he &alues are
re"urned "o "he appl!ca"!on code. :" !s poss!ble "o lose prec!s!on or ge" errors !n PHP +hen
s"r!ngs no" us!ng "he U4 dec!mal and "housands separa"or con&en"!ons e/pec"ed b PHP are
la"er cas" "o numbers 'or ar!"hme"!c. To a&o!d problems !" !s recommended "o e/pl!c!"l se" "he
number con&ers!on 'orma".
The 'ollo+!ng e/amples !llus"ra"e "he d!''erences !n "he dec!mal charac"er and group
separa"or be"+een "he Un!"ed 4"a"es and 3erman +hen numbers are con&er"ed "o s"r!ngs b
Oracle.
7SK alter session set nls$territor# * america!
7ession altered.
7SK select emplo#ee$id -mp5L+
2 su/str%'irst$name+1+1&[[0.0[[last$name "-mpMame"+
@ to$char%salar#+ 099Y999L990& "7alar#"
D 'rom emplo#ees
5 where emplo#ee$id < 105!
-NE5L -mpMame 7alar#
---------- --------------------------- ----------
100 7.Ging 2D+000.00
101 M.Gochhar 1U+000.00
102 K.Le >aan 1U+000.00
10@ 6.>unold 9+000.00
10D I.-rnst P+000.00
7SK alter session set nls$territor# * german#!
7ession altered.
7SK select emplo#ee$id -mp5L+
2 su/str%'irst$name+1+1&[[0.0[[last$name "-mpMame"+
@ to$char%salar#+ 099Y999L990& "7alar#"
D 'rom emplo#ees
5 where emplo#ee$id < 105!
-NE5L -mpMame 7alar#
---------- --------------------------- ----------
100 7.Ging 2D.000+00
101 M.Gochhar 1U.000+00
102 K.Le >aan 1U.000+00
10@ 6.>unold 9.000+00
)3)
,lo5alization
10D I.-rnst P.000+00
The 'orma" ALL3LLLDLLA con"a!ns "he A3A "housands separa"or and ADA dec!mal separa"or a"
"he appropr!a"e places !n "he des!red ou"pu" number. :n "he "+o "err!"or!es, "he ac"ual
charac"er d!splaed !s d!''eren".
The e>u!&alen" PHP e/ample !s)
Script &24' nu+*or+at"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
)s * oci$parse%)c+ "alter session set nls$territor# * german#"&!
oci$e.ecute%)s&!
)s * oci$parse%)c+ "select 12@.5PU as num 'rom dual"&!
oci$e.ecute%)s&!
)r * oci$'etch$arra#%)s+ 345$67734&!
)n1 * )r90MRN0<! // Calue as 'etched
Car$dump%)n1&!
)n2 * %'loat&)n1! // now cast it to a num/er
Car$dump%)n2&!
?
The ou"pu" !s)
string%U& "12@+5PU"
'loat%12@&
:' 7.4NT;RR:TORM had !ns"ead been se" "o america "he ou"pu" +ould ha&e been correc")
string%U& "12@.5PU"
'loat%12@.5PU&
The problem can also occur depend!ng on "he "err!"or componen" o' 7.4N.%73, or "he &alue
o' 7.4N7UM;R:CNCH%R%CT;R4. The la""er &ar!able can be used "o o&err!de "he number
'orma" +h!le o"her "err!"or se""!ngs rema!n !n e''ec". :" can be se" as an en&!ronmen" &ar!able
!n ;etc;syscon*ig;httpd or !n "he shell "ha" runs "he PHP e/ecu"able)
e.port MK7$K6MY*6N-B546M$6N-B546.6K@2R:A8
e.port MK7$MRN-B54$4>6B64:-B7*".+"
The 7.4N7UM;R:CNCH%R%CT;R4 en&!ronmen" &ar!able !s onl e&alua"ed !' 7.4N.%73 !s also
se".
The &alue can also be se" +!"h a .O3O7 "r!gger, or b us!ng an %.T;R 4;44:O7 command
!n PHP)
)s * oci$parse%)c+ "alter session set nls$numeric$characters * 0.+0"&!
oci$e.ecute%)s&!
Chang!ng "he se""!ng !n PHP !s l!(el "o be "he slo+es" o' "he me"hods.
)3*
4sta5lishing the 4n$ironment >et/een .racle and !H!
The "!p Do 2ot Set the Date or 2u+eric (or+at #nnecessarily !n "he chap"er -onnecting to
Oracle #sing O-./ sho+s ho+ an %.T;R 4;44:O7 command can be used !n a da"abase .O3O7
"r!gger.
Setting the Oracle #ate 9or1at With N'SA#,TEA9O:5,T
The bas!c da"e 'orma" used b Oracle depends on our 3lobal!1a"!on se""!ngs, such as "he
&alue !n 7.4N.%73.
The "hree d!''eren" da"e presen"a"!on 'orma"s !n Oracle are s"andard, shor", and long
da"es. The 'ollo+!ng e/amples !llus"ra"e "he d!''erences be"+een "he shor" da"e and long da"e
'orma"s 'or bo"h "he Un!"ed 4"a"es and 3erman.
7SK alter session set nls$territor# * america nls$language * american!
7SK select emplo#ee$id -mp5L+
2 su/str%'irst$name+1+1&[[0.0[[last$name "-mpMame"+
@ to$char%hire$date+0L70& ">iredate"+
D to$char%hire$date+0LK0& "Kong >ireLate"
5 'rom emplo#ees
PJ where emplo#ee$id <105!
-NE5L -mpMame >iredate Kong >ireLate
---------- ---------------- ---------- -----------------------------
100 7.Ging 0P/1U/198U ?ednesda#+ Tune 1U+ 198U
101 M.Gochhar 09/21/1989 :hursda#+ 7eptem/er 21+ 1989
102 K.Le >aan 01/1@/199@ ?ednesda#+ Tanuar# 1@+ 199@
10@ 6.>unold 01/0@/1990 ?ednesda#+ Tanuar# @+ 1990
10D I.-rnst 05/21/1991 :uesda#+ Na# 21+ 1991
7SK alter session set nls$territor#*german# nls$language*german!
7SK select emplo#ee$id -mp5L+
2 su/str%'irst$name+1+1&[[0.0[[last$name "-mpMame"+
@ to$char%hire$date+0L70& ">iredate"+
D to$char%hire$date+0LK0& "Kong >ireLate"
5 'rom emplo#ees
PJ where emplo#ee$id <105!
-NE5L -mpMame >iredate Kong >ireLate
---------- ----------------- -------- ------------------------------
100 7.Ging 1U.0P.8U Nittwoch+ 1U. Tuni 198U
101 M.Gochhar 21.09.89 Lonnerstag+ 21. 7eptem/er 1989
102 K.Le >aan 1@.01.9@ Nittwoch+ 1@. Tanuar 199@
10@ 6.>unold 0@.01.90 Nittwoch+ @. Tanuar 1990
10D I.-rnst 21.05.91 Lienstag+ 21. Nai 1991
:n add!"!on "o "hese "hree 'orma" s"les ou can cus"om!1e "he 'orma" us!ng man o"her da"e
'orma" spec!'!ers. 4earch "he Oracle 4B. language documen"a"!on 'or Dda"e"!me 'orma"
elemen"sE "o see a l!s".
:' "he da"e 'orma" der!&ed 'rom "he 7.4N.%73 se""!ng !s no" "he one ou +an" 'or our PHP
sess!on, ou can o&err!de "he 'orma" b se""!ng "he en&!ronmen" &ar!able 7.4ND%T;N2ORM%T
!n ;etc;syscon*ig;httpd or !n "he shell "ha" runs "he PHP e/ecu"able)
e.port MK7$K6MY*6N-B546M$6N-B546.6K@2R:A8
)3+
,lo5alization
e.port MK7$L6:-$A3BN6:*0;;;;-NN-LL >>2D:N5:770
7o"e !' ou se" 7.4ND%T;N2ORM%T as an en&!ronmen" &ar!able, ou also need "o se"
7.4N.%73 o"her+!se "he &ar!able !s !gnored.
%l"erna"!&el ou can se" !" !n a .O3O7 "r!gger, or change !" a'"er connec"!ng !n PHP)
)s * oci$parse%)c+ "alter session set nls$date$'ormat*0;;;;-NN-LL >>2D:N5:770"&!
oci$e.ecute%)s&!
4ubse>uen" >uer!es +!ll re"urn "he ne+ 'orma")
)s * oci$parse%)c+ "select s#sdate 'rom dual"&!
)r * oci$e.ecute%)s&!
)row * oci$'etch$arra#%)s+ 345$67734&!
echo "Late is " . )row9"7;7L6:-"< . "2n"!
The ou"pu" !s)
Late is 200U-08-01 11:D@:@0
One ad&an"age o' se""!ng "he da"e 'orma" globall !ns"ead o' us!ng :3$4>6B%& !s !" allo+s PHP
and Oracle "o share a common 'orma" 'or !nser"s and >uer!es)
Script &29' date*or+at"php
<?php
)c * oci$connect%0hr0+ 0welcome0+ 0localhost/,-0&!
// 7et de'ault 3racle date 'ormat
)s * oci$parse%)c+ "alter session set nls$date$'ormat*0;;;;-NN-LL >>2D:N5:770"&!
oci$e.ecute%)s&!
// :his E>E Late 'ormat matches the new 3racle 'ormat
)d * date%0;-m-d >:i:s0&!
echo "5nserting )d2n"!
)s * oci$parse%)c+ "insert into emplo#ees
%emplo#ee$id+ last$name+ email+ hire$date+ Wo/$id&
Calues %1+ 0Tones0+ 0cWOe.ample.com0+ :dt+ 07:$4K-BG0&"&!
oci$/ind$/#$name%)s+ ":dt"+ )d&!
oci$e.ecute%)s&!
)s * oci$parse%)c+ "select hire$date 'rom emplo#ees where emplo#ee$id * 1"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
?
The ou"pu" !s)
5nserting 2008-10-2@ 0D:01:1U
arra#%1& (
9">5B-$L6:-"<*
arra#%1& (
90<*
)3-
4sta5lishing the 4n$ironment >et/een .racle and !H!
string%19& "2008-10-2@ 0D:01:1U"
=
=
Da"e 'orma"s can be e/pl!c!"l al"ered b a language se""!ng)
7SK select to$char%s#stimestamp+
0L#+ dd Non #### hh2D:mi:ss tXhtXm0+0MK7$L6:-$K6MYR6Y-*6merican0& 'rom dual!
:3$4>6B%7;7:5N-7:6NE+0L;+LLN3M;;;;>>2D:N5:77:]>:]
-------------------------------------------------
:hu+ 0U Tun 2012 1U:05:55 -0U00
7SK select to$char%s#stimestamp+
0L#+ dd Non #### hh2D:mi:ss tXhtXm0+0MK7$L6:-$K6MYR6Y-*Yerman0& 'rom dual!
:3$4>6B%7;7:5N-7:6NE+0L;+LLN3M;;;;>>2D:N5:77:
---------------------------------------------
Lo+ 0U Tun 2012 1U:05:5P -0U00
Here, "he da o' "he +ee( has been "ransla"ed.
Setting the #e*ault Se!!ion Ti1e @one With O:,AS#T@
The OR%N4DT9 en&!ronmen" &ar!able se"s "he "!me 1one used +hen >uer!ng T:M;4T%MP
0:TH .OC%. T:M; 9O7; columns. :" also a''ec"s T:M;4T%MP &alues con&er"ed "o T:M;4T%MP
0:TH T:M; 9O7; or T:M;4T%MP 0:TH .OC%. T:M; 9O7; da"a "pes. :" does no" a''ec"
4M4D%T; and 4M4T:M;4T%MP &alues +h!ch use "he da"abase ser&er "!me.
Mou can se" OR%N4DT9 "o a "!me1one, an o''se" or a reg!on)
) e.port 3B6$7L:]*0-05:000
5anipulating String!
To handle da"a !n PHP, "here are se&eral e/"ens!ons "ha" can be used. The common e/"ens!ons
are +bstring, intl and iconv. These can be !ns"alled and con'!gured l!(e an o"her PHP source
code or P;C. e/"ens!on.
Once +bstring !s !ns"alled, ou can change "he beha&!or o' "he s"andard PHP s"r!ng
'unc"!ons b se""!ng +bstring"*unc=overload !n php"ini "o one o' "he Overload se""!ngs. 2or
more !n'orma"!on, see "he PHP +bstring re'erence manual a" http://php.net/m/string.
Mour appl!ca"!on code should use 'unc"!ons such as m/$strlen%& "o calcula"e "he number o'
charac"ers !n s"r!ngs. Th!s ma re"urn d!''eren" &alues "han strlen%&, +h!ch re"urns "he
number o' b"es !n a s"r!ng.
The intl pac(age !mplemen"s some :n"erna"!onal Componen"s 'or Un!code C:CUF
'unc"!onal!" such as Colla"ors and Transl!"era"ors.
#eter1ining the 'ocale o* the 0!er
:n a global en&!ronmen", our appl!ca"!on should accommoda"e users +!"h d!''eren" locale
pre'erences. Once !" has de"erm!ned "he pre'erred locale o' "he user, "he appl!ca"!on should
)30
,lo5alization
cons"ruc" HTM. con"en" !n "he language o' "he locale and 'ollo+ "he cul"ural con&en"!ons
!mpl!ed b "he locale.
% common me"hod "o de"erm!ne "he locale o' a user !s 'rom "he de'aul" :4O locale se""!ng
o' "he bro+ser. Usuall a bro+ser sends !"s locale pre'erence se""!ng "o "he HTTP ser&er +!"h
"he Accept3Fanguage HTTP header. :' "he Accept3Fanguage header !s 7U.., "hen "here !s no
locale pre'erence !n'orma"!on a&a!lable, and "he appl!ca"!on should 'all bac( "o a prede'!ned
de'aul" locale.
The 'ollo+!ng PHP code re"r!e&es "he :4O locale 'rom "he Accept3Fanguage HTTP header
"hrough "he )$7-BZ-B 4er&er &ar!able.
)s * )$7-BZ-B9">::E$644-E:$K6MYR6Y-"<
The intl pac(ageAs .ocale))accep"2romH""p me"hod could also be used.
#e-eloping 'ocale ,;arene!!
Once "he locale pre'erence o' "he user has been de"erm!ned, "he appl!ca"!on can call locale?
sens!"!&e 'unc"!ons, such as da"e, "!me, and mone"ar 'orma""!ng "o 'orma" "he HTM. pages
accord!ng "o "he cul"ural con&en"!ons o' "he locale.
0hen ou +r!"e global appl!ca"!ons !mplemen"ed !n d!''eren" programm!ng en&!ronmen"s,
ou should enable "he snchron!1a"!on o' user locale se""!ngs be"+een "he d!''eren"
en&!ronmen"s. 2or e/ample, PHP appl!ca"!ons "ha" call P.<4B. procedures should map "he :4O
locales "o "he correspond!ng 7.4N.%73U%3; and 7.4NT;RR:TORM &alues and change "he
parame"er &alues "o ma"ch "he locale o' "he user be'ore call!ng "he P.<4B. procedures. The
P.<4B. UT.N:1$7 pac(age con"a!ns mapp!ng 'unc"!ons "ha" can map be"+een :4O and Oracle
locales.
Table 1$ sho+s ho+ some commonl used locales are de'!ned !n :4O and Oracle
en&!ronmen"s.
)able &/' Focale representations in .SO, SEF and PF;SEF progra++ing
environ+ents"
'ocale 'ocale I# N'SA',NG0,GE N'SATE::ITO:G
Ch!nese CP.R.C.F Xh-4M 75NEK5A5-L 4>5M-7- 4>5M6
Ch!nese CTa!+anF Xh-:? :B6L5:53M6K 4>5M-7- :65?6M
;ngl!sh CU.4.%F en-R7 6N-B546M 6N-B546
;ngl!sh CUn!"ed 6!ngdomF en-YI -MYK57> RM5:-L G5MYL3N
2rench CCanadaF 'r-46 46M6L56M AB-M4> 46M6L6
2rench C2ranceF 'r-AB AB-M4> AB6M4-
3erman de Y-BN6M Y-BN6M;
:"al!an it 5:6K56M 5:6K;
*apanese Wa T6E6M-7- T6E6M
6orean ko G3B-6M G3B-6
Por"uguese C-ra1!lF pt-IB IB6]5K56M E3B:RYR-7- IB6]5K
Por"uguese pt E3B:RYR-7- E3B:RY6K
)31
Determining the Locale oA the Bser
'ocale 'ocale I# N'SA',NG0,GE N'SATE::ITO:G
4pan!sh es 7E6M57> 7E65M
Encoding HT5' Page!
The encod!ng o' an HTM. page !s !mpor"an" !n'orma"!on 'or a bro+ser and an :n"erne"
appl!ca"!on. Mou can "h!n( o' "he page encod!ng as "he charac"er se" used 'or "he locale "ha"
an :n"erne" appl!ca"!on !s ser&!ng. The bro+ser mus" (no+ abou" "he page encod!ng so "ha" !"
can use "he correc" 'on"s and charac"er se" mapp!ng "ables "o d!spla "he HTM. pages.
:n"erne" appl!ca"!ons mus" (no+ abou" "he HTM. page encod!ng so "he can process !npu"
da"a 'rom an HTM. 'orm.
:ns"ead o' us!ng d!''eren" na"!&e encod!ngs 'or "he d!''eren" locales, Oracle recommends
"ha" ou use UT2?$ CUn!code encod!ngF 'or all page encod!ngs. Th!s encod!ng no" onl
s!mpl!'!es "he cod!ng 'or global appl!ca"!ons, bu" !" also enables mul"!l!ngual con"en" on a
s!ngle page.
Speci*6ing the Page Encoding *or HT5' Page!
Mou can spec!' "he encod!ng o' an HTM. page e!"her !n "he HTTP header, or !n HTM. page
header.
Speci*6ing the Encoding in the HTTP Header
To spec!' HTM. page encod!ng !n "he HTTP header, !nclude "he -ontent3)ype HTTP header !n
"he HTTP spec!'!ca"!on. :" spec!'!es "he con"en" "pe and charac"er se". The -ontent3)ype HTTP
header has "he 'ollo+!ng 'orm)
4ontent-:#pe: te.t/html! charset*ut'-8
The charset parame"er spec!'!es "he encod!ng 'or "he HTM. page. The poss!ble &alues 'or "he
charset parame"er are "he :%7% names 'or "he charac"er encod!ngs "ha" "he bro+ser suppor"s.
:" !s !mpor"an" "o be cons!s"en" us!ng "he page encod!ng. 2or e/ample, "he htmlentities%&
encod!ng parame"er should ma"ch "he page encod!ng so "ha" charac"ers are recogn!1ed and
escaped properl. O"her+!se our appl!ca"!on +!ll be &ulnerable "o secur!" a""ac(s.
Speci*6ing the Encoding in the HT5' Page Header
Use "h!s me"hod pr!mar!l 'or s"a"!c HTM. pages. To spec!' HTM. page encod!ng !n "he HTM.
page header, spec!' "he charac"er encod!ng !n "he HTM. header as 'ollo+s)
<meta http-e"uiC*"4ontent-:#pe" content*"te.t/html!charset*ut'-8"
The charset parame"er spec!'!es "he encod!ng 'or "he HTM. page. %s +!"h "he -ontent3)ype
HTTP Header, "he poss!ble &alues 'or "he charset parame"er are "he :%7% C:n"erne" %ss!gned
7umbers %u"hor!"F names 'or "he charac"er encod!ngs "ha" "he bro+ser suppor"s.
Speci*6ing the Page Encoding in PHP
Mou can spec!' "he encod!ng o' an HTM. page !n "he -ontent3)ype HTTP header !n PHP b
se""!ng "he de*ault=charset con'!gura"!on &ar!able !n php"ini)
)32
,lo5alization
de'ault$charset * R:A-8
7o"e "he de'aul" &alue o' "h!s charac"er se" d!rec"!&e +as changed "o UT2?$ !n PHP H.J. Mou
can al"erna"!&el use "he PHP header%& 'unc"!on "o se" "he con"en" "pe)
header%04ontent-:#pe: te.t/html! charset*ut'-80&!
Th!s se""!ng does no" !mpl an con&ers!on o' ou"go!ng pages. Mour appl!ca"!on mus" ensure
"ha" "he ser&er?genera"ed pages are encoded !n UT2?$.
Organi8ing the Content o* HT5' Page! *or Tran!lation
Ma(!ng "he user !n"er'ace a&a!lable !n "he local language o' "he user !s a 'undamen"al "as( !n
global!1!ng an appl!ca"!on. Transla"able sources 'or "he con"en" o' an HTM. page belong "o "he
'ollo+!ng ca"egor!es)
Te/" s"r!ngs !ncluded !n "he appl!ca"!on code
4"a"!c HTM. '!les, !mages '!les, and "empla"e '!les such as C44
Dnam!c da"a s"ored !n "he da"abase
String! in PHP
Mou should e/"ernal!1e "ransla"able s"r!ngs +!"h!n our PHP appl!ca"!on log!c, so "ha" "he "e/" !s
read!l a&a!lable 'or "ransla"!on. These "e/" messages can be s"ored !n 'la" '!les or da"abase
"ables depend!ng on "he "pe and "he &olume o' "he da"a be!ng "ransla"ed. PHPAs gettext
e/"ens!on !s o'"en used 'or "h!s purpose.
Static 9ile!
4"a"!c '!les such as HTM. and "e/" s"ored as !mages are read!l "ransla"able. 0hen "hese '!les
are "ransla"ed, "he should be "ransla"ed !n"o "he correspond!ng language +!"h UT2?$ as "he
'!le encod!ng. To d!''eren"!a"e "he languages o' "he "ransla"ed '!les, s"age "he s"a"!c '!les o'
d!''eren" languages !n d!''eren" d!rec"or!es or +!"h d!''eren" '!le names.
#ata *ro1 the #ata$a!e
Dnam!c !n'orma"!on such as produc" names and produc" descr!p"!ons !s "p!call s"ored !n
"he da"abase. To d!''eren"!a"e &ar!ous "ransla"!ons, "he da"abase schema hold!ng "h!s
!n'orma"!on should !nclude a column "o !nd!ca"e "he language. To selec" "he des!red language,
ou mus" !nclude a ?>-B- clause !n our >uer.
Pre!enting #ata 0!ing Con-ention! Epected $6 the 0!er
Da"a !n "he appl!ca"!on mus" be presen"ed !n a +a "ha" con'orms "o "he e/pec"a"!on o' "he
user. O"her+!se, "he mean!ng o' "he da"a can be m!s!n"erpre"ed. 2or e/ample, "he da"e
\12<11<0LK !mpl!es \11"h December 200LK !n "he Un!"ed 4"a"es, +hereas !n "he Un!"ed 6!ngdom
!" means \12"h 7o&ember 200LK. 4!m!lar con'us!on e/!s"s 'or number and mone"ar 'orma"s o'
"he users. 2or e/ample, "he smbol \.K !s a dec!mal separa"or !n "he Un!"ed 4"a"esG !n 3erman
"h!s smbol !s a "housand separa"or.
)&3
!resenting Data Bsing Con$entions 4%pected 5y the Bser
D!''eren" languages ha&e "he!r o+n sor"!ng rules. 4ome languages are colla"ed accord!ng
"o "he le""er se>uence !n "he alphabe", some accord!ng "o "he number o' s"ro(e coun"s !n "he
le""er, and some languages are ordered b "he pronunc!a"!on o' "he +ords. Presen"!ng da"a
no" sor"ed !n "he l!ngu!s"!c se>uence "ha" our users are accus"omed "o can ma(e search!ng
'or !n'orma"!on d!''!cul" and "!me consum!ng.
Depend!ng on "he appl!ca"!on log!c and "he &olume o' da"a re"r!e&ed 'rom "he da"abase, !"
ma be more appropr!a"e "o 'orma" "he da"a a" "he da"abase le&el ra"her "han a" "he
appl!ca"!on le&el. Oracle o''ers man 'ea"ures "ha" help "o re'!ne "he presen"a"!on o' da"a
+hen "he locale pre'erence o' "he user !s (no+n. ;arl!er !n "h!s chap"er, e/amples us!ng da"e
and numer!c 'orma"s +ere sho+n. The ne/" sec"!on pro&!des ano"her e/ample o' a locale?
sens!"!&e opera"!on !n 4B..
Oracle 'ingui!tic Sort!
4pa!n "rad!"!onall "rea"s ch, ll as +ell as U as un!>ue le""ers, ordered a'"er c, l and n,
respec"!&el. The 'ollo+!ng e/amples !llus"ra"e "he e''ec" o' us!ng a 4pan!sh sor" aga!ns" "he
emploee names -hen and -hung.
7SK alter session set nls$sort * /inar#!
7SK select emplo#ee$id -mp5L+
2 last$name "Kast Mame"
@ 'rom emplo#ees
D where last$name like 04F0
5 order /# last$name!
-NE5L Kast Mame
---------- -------------------------
18U 4a/rio
1D8 4am/rault
15D 4am/rault
110 4hen
188 4hung
119 4olmenares
7SK alter session set nls$sort * spanish$m!
7SK select emplo#ee$id -mp5L+
2 last$name "Kast Mame"
@ 'rom emplo#ees
D where last$name like 04F0
5 order /# last$name!
-NE5L Kast Mame
---------- -------------------------
18U 4a/rio
1D8 4am/rault
15D 4am/rault
119 4olmenares
110 4hen
188 4hung
)&&
,lo5alization
Oracle Error 5e!!age!
The 7.4N.%73U%3; parame"er also con"rols "he language o' "he da"abase error messages
be!ng re"urned 'rom "he da"abase. 4e""!ng "h!s parame"er pr!or "o subm!""!ng our 4B.
s"a"emen" ensures "ha" language?spec!'!c da"abase error messages +!ll be logged b "he
appl!ca"!on.
Cons!der "he 'ollo+!ng ser&er message)
3B6-009D2: ta/le or Ciew does not e.ist
0hen "he 7.4N.%73U%3; parame"er !s se" "o (rench, "he ser&er message appears as 'ollo+s)
3B6-009D2: ta/le ou Cue ine.istante
2or more d!scuss!on o' global!1a"!on suppor" 'ea"ures !n Oracle Da"abase &&g =;, see Wor1ing
in a Global Environ+ent !n "he Oracle Database Express Edition 2 Day Developer%s Guide.
)&(
CH,PTE: 1.
TESTING PHP ,N# THE OCI.
E4TENSION
Th!s chap"er d!scusses runn!ng "he PHP "es" su!"e on .!nu/. The PHP source code !ncludes
command?l!ne "es"s 'or all "he core 'unc"!onal!" and e/"ens!ons. Mou should run "hese "es"s
a'"er bu!ld!ng PHP on .!nu/.
:" !s a good !dea "o pro?ac"!&el "es" our appl!ca"!ons +!"h PHP Drelease cand!da"esE and
snapsho"s, http://snaps.php.net. Please repor" problems so "he can be '!/ed pr!or "o each
'!nal PHP release. Th!s ensures PHP con"!nues do!ng +ha" ou need !" "o do. Cons!der
con"r!bu"!ng ne+ "es"s "o "he PHP commun!". %dd!ng "es"s "ha" are rele&an" "o our
appl!ca"!on reduces "he r!s(s o' PHP de&elopers brea(!ng PHP 'ea"ures !mpor"an" "o ou.
Please send ne+ "es"s or repor" !ssues +!"h PHPKs "es" su!"e "o php-"aOlists.php.net.
:unning OCI. Te!t!
The "es"s !n "he PHP source d!rec"or ext;oci/;tests &er!' "he beha&!or o' "he OC:$ e/"ens!on.
2or "he "es"s "o run success'ull some con'!gura"!on !s needed)
1. 4e" "he Oracle connec"!on de"a!ls b ed!"!ng ext;oci/;tests;details"inc and upda"!ng "he
creden"!als sec"!on)
)user * "s#stem"!
)password * "s#stempwd"!
)d/ase * "localhost/,-"!
The "es"s rel on be!ng able "o crea"e "ables, "pes, s"ored procedures, and so on. :' ou
change )user, ou ma ha&e "o gran" "ha" da"abase user some e/"ra pr!&!leges.
0!"h OC:$ 1.J, !' ou are us!ng Oracle Da"abase 11g Connec"!on Pool!ng, also se")
)test$drcp * :BR-
To use DRCP, "he pool mus" also be enabled !n "he da"abase and "he PHP connec"!on
s"r!ng mus" spec!' "ha" a pooled da"abase ser&er should be used, 'or e/ample)
)d/ase * "localhost/,-:pooled"!
:ns"ead o' ed!"!ng details"inc, e>u!&alen" en&!ronmen" &ar!ables can be se" !n a "erm!nal
+!ndo+)
) e.port E>E$3458$:-7:$R7-B*s#stem
) e.port E>E$3458$:-7:$E677*s#stempwd
) e.port E>E$3458$:-7:$LI*localhost/,-
) e.port E>E$3458$:-7:$LB4E*A6K7-
2. Chec( "ha" variables=order has A;A !n our php"ini, 'or e/ample)
)&)
Testing !H! and the .C'1 4%tension
Caria/les$order * "-YE47"
0!"hou" "h!s 'lag, "he Oracle en&!ronmen" &ar!ables are no" propaga"ed "hrough "he "es"
ss"em and OC:$ "es"s can 'a!l "o connec".
I. 4e" an necessar Oracle en&!ronmen" &ar!ables !n our shell. 2or e/ample, 'or PHP l!n(ed
+!"h Oracle Da"abase &&g <E en"er)
) source /u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
2or o"her da"abase ed!"!ons run oraenv and en"er "he !den"!'!er o' our da"abase)
) source /usr/local//in/oraenC
3B64K-$75L * 9< ? orcl
:' Oracle !s on a d!''eren" mach!ne, ou ma manuall need "o se" "he en&!ronmen"
&ar!ables "ha" are o"her+!se se" b "hese scr!p"s.
J. 4ome o' "he OC:$ "es"s "a(e longer "han "he de'aul" "es" "!meou" per!od, par"!cularl !' "he
da"abase !s on a remo"e ser&er. ;!"her !ncrease "he "es" su!"e "!meou")
) e.port :-7:$:5N-3R:*P00
or s(!p "he slo+ "es"s)
) e.port 7G5E$7K3?$:-7:7*1
H. Run PHPKs "es" su!"e +!"h)
) cd php-5.D
) make test
:' ou +an" "o run 8us" "he OC:$ "es"s use)
) make test :-7:7*e.t/oci8
;ach "es" scr!p" !s e/ecu"ed and !"s s"a"us repor"ed.
**************************************************************
E>E : /home/m#home/php-5.D/sapi/cli/php
E>E$76E5 : cli
E>E$Z-B753M : 5.D.D
]-ML$Z-B753M: 2.D+0
E>E$37 : Kinu. - Kinu. cW-olP2.PD 2.P.@9-100
5M5 actual : /usr/local/apache/con'/php.ini
Nore .5M5s :
4?L : /home/m#home/php-5.D
-.tra dirs :
Z6KYB5ML : not used
**************************************************************
Bunning selected tests.
E677 oci$/ind$arra#$/#$name%& and inCalid Calues 1 9arra#$/ind$001.phpt<
E677 oci$/ind$arra#$/#$name%& and inCalid Calues 2 9arra#$/ind$002.phpt<
E677 oci$/ind$arra#$/#$name%& and inCalid Calues @ 9arra#$/ind$00@.phpt<
...
)&*
Running .C'1 Tests
4uccess'ul "es"s beg!n +!"h P%44. Tes"s "ha" are "o be s(!pped !n "he curren"
con'!gura"!on are mar(ed 46:P. 2a!l!ng "es"s are mar(ed 2%:.. % summar o' "he "es"
resul"s !s g!&en a" "he comple"!on o' "he "es"s.
:unning a Single Te!t
To run onl one or "+o "es"s, e/ecu"e run3tests"php d!rec"l and pass "he "es" names as
parame"ers. 2or e/ample, "o run a scr!p" called de+otest"phpt, do "he 'ollo+!ng)
) cd php-5.D
) e.port :-7:$E>E$-,-4R:6IK-*/home/m#home/php-5.D/sapi/cli/php
) ):-7:$E>E$-,-4R:6IK- run-tests.php e.t/oci8/tests/demotest.phpt
The &ar!able T;4TNPHPN;=;CUT%-.; !s used !ns!de "he con"roll!ng run3tests"php scr!p" +hen !"
!n&o(es de+otest"phpt. :n "he e/ample, "he same PHP b!nar !s also used "o run "he run3
tests"php scr!p" !"sel', bu" "he could be d!''eren" e/ecu"ables. The "es" ou"pu" !s s!m!lar "o "he
pre&!ous ou"pu".
Te!t! that 9ail
The ou"pu" o' 'a!l!ng "es"s !s (ep" 'or anals!s. 2or e/ample, !' ext;oci/;tests;de+otest"phpt
'a!ls, "he 'ollo+!ng '!les +!ll be !n ext;oci/;tests)
)able &8' )est *iles and their contents"
9ile na1e 9ile Content!
de+otest"phpt Tes" 'rame+or( scr!p"
de+otest"php PHP '!le e/ecu"ed
de+otest"out Tes" ou"pu"
de+otest"exp ;/pec"ed ou"pu" as coded !n "he "phpt '!le
de+otest"di** D!''erence be"+een ac"ual and e/pec"ed ou"pu"
de+otest"log %c"ual and e/pec"ed ou"pu" !n a s!ngle '!le
:" !s common 'or "he 'ull PHP "es" su!"e "o repor" some "es" 'a!lures. Th!s !s because man PHP
e/"ens!ons are +rappers around ss"em l!brar!es +!"h sl!gh"l d!''eren" beha&!ors on d!''eren"
pla"'orms or &ers!ons. %lso some ss"em con'!gura"!ons ma res"r!c" access, 'or e/ample "o
ne"+or( por"s. Mou can re&!e+ commonl seen d!''erences a" http://"a.php.net/reports.
The PHP "es" !n'ras"ruc"ure doesnA" prac"!call allo+ "es"s "o accep" d!''erences across all
&ers!ons o' Oracle Da"abase. %lso !' ou use "he la"es" OC:$ e/"ens!on +!"h an older &ers!on o'
PHP, d!''erences !n PHPAs Car$dump%& ou"pu" can ma(e "es"s appear "o 'a!l.
Creating OCI. Te!t!
To add a ne+ OC:$ "es", crea"e a phpt '!le !n ext;oci/;tests us!ng "he "es" '!le 'orma". 0hen ou
run +a1e test "he ne+ '!le !s au"oma"!call run, or ou can call !" e/pl!c!"l as sho+n abo&e.
2or e/ample, crea"e de+otest"phpt)
)&+
Testing !H! and the .C'1 4%tension
Script &2?' de+otest"phpt
--:-7:--
Lemo to test the :est s#stem
--7G5E5A--
<?php
i' %8e.tension$loaded%0oci80&& die%"skip no oci8 e.tension"&!
?
--A5K---
<?php
re"uire %$$L5B$$.0/connect.inc0&!
)s * oci$parse%)c+ "select user 'rom dual"&!
oci$e.ecute%)s&!
oci$'etch$all%)s+ )res&!
Car$dump%)res&!
echo "Lone2n"!
?
***L3M-***
<?php e.it%0&! ?
---,E-4:--
arra#%1& (
9"R7-B"<*
arra#%1& (
90<*
string%P& "7;7:-N"
=
=
***L3M-***
The "es" beg!ns +!"h a commen" "ha" !s d!splaed +hen "he "es" runs. The 7G5E5A sec"!on
causes "he "es" "o be s(!pped +hen "he OC:$ e/"ens!on !s no" enabled !n PHP. The A5K- sec"!on
!s "he PHP code "o be e/ecu"ed. The -,E-4: sec"!on has "he e/pec"ed ou"pu". The '!le
connect"inc !s 'ound !n ext;oci/;tests;connect"inc. :" !ncludes details"inc, connec"s "o Oracle,
and re"urns "he connec"!on resource !n )c.
The l!ne ***L3M-*** !s ou"s!de "he e/ecu"ed scr!p" and !s echoed &erba"!m, &er!'!ng "ha"
"he scr!p" comple"ed. The e/"ra PHP bloc( con"a!n!ng e.it%0& ma(es call!ng "he "es" d!rec"l
!n PHP +!"hou" us!ng run3tests"php a l!""le cleaner)
) php de-otest.phpt
--:-7:--
Lemo to test the :est s#stem
--7G5E5A--
--A5K---
arra#%1& (
9"R7-B"<*
arra#%1& (
90<*
string%P& "7;7:-N"
=
=
Lone
***L3M-***
)&-
Creating .C'1 Tests
Runn!ng l!(e "h!s, some o' "he de+otest"phpt "es" 'rame+or( con"en" !s sho+n, bu" code
e/ecu"es and onl "he ac"ual, and no" "he e/pec"ed, ou"pu" !s d!splaed. Th!s can ma(e !"
eas!er "o >u!c(l &al!da"e "es"s, +!"hou" ha&!ng "o se" T;4TNPHPN;=;CUT%-.; and !n&o(e run3
tests"php"
The page Writing )ests a" http://"a.php.net/write-test.php sho+s o"her sec"!ons a
"es" '!le can ha&e, !nclud!ng +as "o se" argumen"s and php"ini parame"ers. Th!s page also
has gener!c e/amples and help'ul !n'orma"!on on +r!"!ng "es"s. The sec"!ons o' a "phpt '!le are
documen"ed a" http://"a.php.net/phpt$details.php.
0r!"!ng good un!"s "es"s !s an ar". Ma(!ng a "es" por"able, accura"e, s!mple and sel'?
d!agnos!ng re>u!res '!ne 8udgmen" and "!d programm!ng.
OCI. Te!t Helper Script!
%long +!"h connect"inc and details"inc, "here are se&eral use'ul scr!p"s !n ext;oci/;tests 'or
crea"!ng and dropp!ng bas!c "ables and "pes, "hese !nclude)
create=table"inc
create=type"inc
drop=table"inc
drop=type"inc
Mou can !nclude "hese !n an ne+ "es"s ou +r!"e.
Ma(e sure ne+ "es"s crea"e an needed ob8ec"s and drop "hem a" "he end o' "he "es". Use
un!>ue names 'or each ob8ec", 'or e/ample !' "he "es" de+otest"phpt needs "o crea"e Cand
dropF a "able, a good "able name +ould be D;MOT;4TNT%-.
Con*iguring the #ata$a!e 9or Te!ting
4ome"!mes !" !s poss!ble 'or rap!dl e/ecu"!ng OC:$ "es" scr!p"s "o 'lood "he da"abase +!"h
connec"!ons. Th!s ma be no"!ceable +!"h Oracle Da"abase =;, +h!ch has smaller de'aul"s.
Random "es"s 'a!l +!"h errors l!(e "he 'ollo+!ng)
3B6-1251P :M7:listener could not 'ind aCaila/le handler with matching protocol
stack
or)
3B6-12520: :M7:listener could not 'ind aCaila/le handler 'or re"uested t#pe o'
serCer
The bes" general solu"!on !s "o use DRCP connec"!ng pool!ng solu"!on as d!scussed !n "he
chap"er PHP -onnection Pooling and High Availability. %n al"erna"!&e me"hod su!"able 'or "he
spec!'!c case o' "es"!ng !s "o !ncrease "he number o' DprocessesE "ha" Oracle can handle. Th!s
me"hod !s also appl!cable +hen connec"!on pool!ng !s no" des!red or a&a!lable, 'or e/ample
+hen us!ng Oracle Da"abase 10.2.
To !ncrease "he number o' processes !n Oracle)
1. Mou ma need "o su as "he oracle user so ou ha&e opera"!ng ss"em pr!&!leges +hen
s"ar"!ng 4B.SPlus)
) su V oracle
Eassword:
)&0
Testing !H! and the .C'1 4%tension
2. 4e" "he Oracle en&!ronmen" &ar!ables needed b 4B.SPlus, 'or e/ample)
) source /u01/app/oracle/product/11.2.0/.e//in/oracle$enC.sh
I. Use 4B.SPlus "o connec" as a pr!&!leged da"abase user)
) s"lplus / as s#sd/a
J. Chec( "he curren" &alue o' processes us!ng "he 7>3? E6B6N-:-B EB34-77-7 command)
7SK show para-eter processes
M6N- :;E- Z6KR-
------------------------- ----------- -----------
...
processes integer D0
H. :ncrease "he &alue "o, sa, 100)
7SK a"ter s,ste- set processes;1$$ scope;sp2i"e4
7#stem altered.
O. Res"ar" "he da"abase us!ng "he 7>R:L3?M 5NN-L56:-, 'ollo+ed b "he 7:6B:RE command)
7SK sh!tdown i--ediate
Lata/ase closed.
Lata/ase dismounted.
3B64K- instance shut down.
7SK start!p
3B64K- instance started.
:otal 7#stem Ylo/al 6rea 289D0P9UP /#tes
Ai.ed 7iXe 1258D88 /#tes
Zaria/le 7iXe 9PDU20U2 /#tes
Lata/ase Iu''ers 188UD@P80 /#tes
Bedo Iu''ers29@2U@P /#tes
Lata/ase mounted.
Lata/ase opened.
P. Use "he 7>3? E6B6N-:-B EB34-77-7 command "o con'!rm "he ne+ &alue !s !n e''ec")
7SK show para-eter processes
M6N- :;E- Z6KR-
------------------------- ----------- ----------
...
processes integer 100
$. ;/!" 4B.SPlus us!ng "he -,5: command)
7SK exit
L. 7o+ "he "es"s can be run aga!n)
) make test :-7:7*e.t/oci8
)&1
Testing !H! Applications
Te!ting PHP ,pplication!
Mou should &er!' our appl!ca"!ons +or( correc"l +!"h an ne+ PHP b!nar be'ore pu""!ng !"
!n"o produc"!on. Th!s g!&es load and real?l!'e "es"!ng no" poss!ble +!"h PHPKs command?l!ne "es"
su!"e. %ppl!ca"!on le&el "es"!ng br!ngs e&en more challenges. There are se&eral PHP "es"
'rame+or(s +!"h soph!s"!ca"ed 'ea"ures "ha" m!gh" be su!"ed "o crea"e appl!ca"!on "es" su!"es.
The !nclude PHP#nit and Si+ple)est. These are no" co&ered !n "h!s manual.
)&2
Testing !H! and the .C'1 4%tension
)(3
,PPEN#I4 ,
T:,CING OCI. INTE:N,'S
Th!s append!/ d!scusses "rac!ng "he OC:$ !n"ernals. To see e/ac"l +ha" calls "o "he Oracle
da"abase "he OC:$ e/"ens!on ma(es, ou can "urn on debugg!ng ou"pu". Th!s !s mos"l use'ul
'or "he ma!n"a!ners o' "he OC:$ e/"ens!on.
Ena$ling OCI. #e$ugging output
Trac!ng can be "urned on !n our scr!p" +!"h oci$internal$de/ug%&. 2or a scr!p" "ha" connec"s
and does an !nser")
Script &2/' trace"php
<?php
oci_interna"_deb!g(1&! // turn on tracing
)c * oci$connect%"hr"+ "welcome"+ "localhost/,-"&!
)s * oci$parse%)c+ "insert into testta/le Calues %0m# data0&"&!
oci$e.ecute%)s+ 345$M3$6R:3$43NN5:&!
?
Mou ge" ou"pu" l!(e)
3458 L-IRY: 345Mls-nCironmentZaria/leYet at %phpsrc/php-5.D/e.t/oci8/oci8.c:18U@&
3458 L-IRY K1: Yot M3 cached connection at %phpsrc/php-5.D/e.t/oci8/oci8.c:1918&
3458 L-IRY: 345-nCMls4reate at %phpsrc/php-5.D/e.t/oci8/oci8.c:291P&
3458 L-IRY: 345>andle6lloc at %phpsrc/php-5.D/e.t/oci8/oci8.c:2U@U&
3458 L-IRY: 345>andle6lloc at %phpsrc/php-5.D/e.t/oci8/oci8.c:2UD9&
3458 L-IRY: 345>andle6lloc at %phpsrc/php-5.D/e.t/oci8/oci8.c:2UPP&
3458 L-IRY: 3456ttr7et at %phpsrc/php-5.D/e.t/oci8/oci8.c:2U8P&
3458 L-IRY: 3456ttr7et at %phpsrc/php-5.D/e.t/oci8/oci8.c:2U95&
3458 L-IRY: 3457essionEool4reate at %phpsrc/php-5.D/e.t/oci8/oci8.c:280U&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:2821&
3458 L-IRY K1: create$spool: %0.a8815D8& at %phpsrc/php-5.D/e.t/oci8/oci8.c:2825&
3458 L-IRY K1: using shared pool: %0.a8815D8& at %phpsrc/php-
5.D/e.t/oci8/oci8.c:@1D@&
3458 L-IRY: 345>andle6lloc at %phpsrc/php-5.D/e.t/oci8/oci8.c:@15D&
3458 L-IRY: 345>andle6lloc at %phpsrc/php-5.D/e.t/oci8/oci8.c:@1PD&
3458 L-IRY: 3456ttr7et at %phpsrc/php-5.D/e.t/oci8/oci8.c:@1U@&
3458 L-IRY: 3456ttr7et at %phpsrc/php-5.D/e.t/oci8/oci8.c:@185&
3458 L-IRY: 3456ttrYet at %phpsrc/php-5.D/e.t/oci8/oci8.c:@19U&
3458 L-IRY: 3456ttrYet at %phpsrc/php-5.D/e.t/oci8/oci8.c:@198&
3458 L-IRY K1: %numopen*0&%num/us#*0&%num'ree*0& at %phpsrc/php-
5.D/e.t/oci8/oci8.c:@200&
3458 L-IRY: 3457essionYet at %phpsrc/php-5.D/e.t/oci8/oci8.c:@211&
3458 L-IRY: 3456ttrYet at %phpsrc/php-5.D/e.t/oci8/oci8.c:@22P&
3458 L-IRY: 3456ttrYet at %phpsrc/php-5.D/e.t/oci8/oci8.c:@228&
3458 L-IRY: 3454onte.tYetZalue at %phpsrc/php-5.D/e.t/oci8/oci8.c:@2@0&
)(&
Tracing .C'1 'nternals
3458 L-IRY: 3454onte.tYetZalue at %phpsrc/php-5.D/e.t/oci8/oci8.c:@@25&
3458 L-IRY: 345Nemor#6lloc at %phpsrc/php-5.D/e.t/oci8/oci8.c:@@@2&
3458 L-IRY: 3454onte.t7etZalue at %phpsrc/php-5.D/e.t/oci8/oci8.c:@@DP&
3458 L-IRY: 3456ttr7et at %phpsrc/php-5.D/e.t/oci8/oci8.c:@25P&
3458 L-IRY K1: Mew Mon-Eersistent 4onnection address: %0./D52d1P0& at
%phpsrc/php-5.D/e.t/oci8/oci8.c:21PU&
3458 L-IRY K1: num$persistent*%0&+ num$links*%1& at %phpsrc/php-
5.D/e.t/oci8/oci8.c:21P9&
3458 L-IRY: 345>andle6lloc at %phpsrc/php-5.D/e.t/oci8/oci8$statement.c:5U&
3458 L-IRY: 3457tmtErepare2 at %phpsrc/php-5.D/e.t/oci8/oci8$statement.c:U2&
3458 L-IRY: 3456ttr7et at %phpsrc/php-5.D/e.t/oci8/oci8$statement.c:12@&
3458 L-IRY: 3456ttrYet at %phpsrc/php-5.D/e.t/oci8/oci8$statement.c:D@@&
3458 L-IRY: 3457tmt-.ecute at %phpsrc/php-5.D/e.t/oci8/oci8$statement.c:DP1&
3458 L-IRY: 3457tmtBelease at %phpsrc/php-5.D/e.t/oci8/oci8$statement.c:UPP&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8$statement.c:UUD&
3458 L-IRY: 345:ransBoll/ack at %phpsrc/php-5.D/e.t/oci8/oci8.c:22D1&
3458 L-IRY: 3457essionBelease at %phpsrc/php-5.D/e.t/oci8/oci8.c:2D02&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:2288&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:2291&
3458 L-IRY: 3457essionEoolLestro# at %phpsrc/php-5.D/e.t/oci8/oci8.c:@29@&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:@29U&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:@@01&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:@@05&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:11DD&
3458 L-IRY: 345>andleAree at %phpsrc/php-5.D/e.t/oci8/oci8.c:11D9&
Man o' "hese calls 8us" alloca"e local resources ChandlesF and se" local s"a"e CattributesF, bu"
some re>u!re a round trip "o "he da"abase.
One o' "hese !s "he 345:ransBoll/ack%& call near "he end o' "he scr!p". The
OC:N7ON%UTONCOMM:T 'lag sa!d no" "o au"o?comm!" and "here +as no e/pl!c!" oci$commit%&
call. %s par" o' PHPKs end o' HTTP re>ues" shu"do+n a" "he conclus!on o' "he scr!p", "he
rollbac( +as !ssued.
7o"e) !' ou change "o au"o?comm!" mode ou +!ll no" see a call "o 345:rans4ommit%&
because "he comm!" message !s p!gg?bac(ed +!"h OracleAs s"a"emen" e/ecu"!on call, "hus
sa&!ng a round?"r!p. :' a scr!p" onl !nser"s one ro+ !" !s '!ne "o au"o?comm!". O"her+!se, do "he
"ransac"!on managemen" oursel'.
)((
,PPEN#I4 )
OCI. PHP.INI P,:,5ETE:S
Th!s append!/ g!&es an o&er&!e+ o' "he php"ini parame"ers 'or "he OC:$ e/"ens!on. De"a!led
d!scuss!on o' "he!r use !s co&ered !n pre&!ous chap"ers.
The parame"ers can be changed !n "he PHP con'!gura"!on '!le php"ini, 'or e/ample)
oci8.de'ault$pre'etch * U5
,ar!ables can also be se" !n %pacheAs httpd"con*)
<5'Nodule mod$php5.c
php$admin$'lag oci8.old$oci$close$semantics 3n
php$admin$Calue oci8.connection$class N;E>E6EE
</5'Nodule
The +eb ser&er mus" be res"ar"ed 'or an changes "o "a(e e''ec".
The loca"!on o' php"ini can be 'ound b runn!ng "he command l!ne PHP e/ecu"able php
--ini. The curren" &alues o' "he OC:$ parame"ers can be 'ound b runn!ng php --ri oci8.
.oad!ng phpin*o"php !n a bro+ser +!ll sho+ all parame"ers and !s e>u!&alen" "o php -i)
Script &28' phpin*o"php
<?php
phpin'o%&!
?
:' ou m!gh" ha&e mul"!ple &ers!ons o' PHP !ns"alled, chec( "he se""!ngs &!a bo"h command l!ne
and a bro+ser.
:' ou are us!ng 0!ndo+s, remember "o ed!" php"ini us!ng adm!n!s"ra"!&e pr!&!leges.
Ena$ling PHP OCI. in php+ini
On 0!ndo+s, ou +!ll need "o enable OC:$ !n php"ini. :' ou are us!ng OC:$ +!"h Oracle 11gR2
cl!en" l!brar!es "han add)
e.tension*php$oci8$11g.dll
:' ou are us!ng OC:$ +!"h Oracle 10gR2 cl!en" l!brar!es "han add)
e.tension*php$oci8.dll
Onl one o' "hese e/"ens!ons can be enabled a" a "!me.
:' PHP OC:$ +as comp!led as a shared e/"ens!on on .!nu/, ou +!ll need "o enable !" !n
php"ini +!"h)
e.tension*oci8.so
:' OC:$ +as bu!l" s"a"!call !n"o "he PHP e/ecu"able ou do no" need "o se" "h!s.
On bo"h pla"'orms, ma(e sure extension=dir !s se" "o "he d!rec"or con"a!n!ng "he shared
l!brar.
)()
.C'1 phpDini !arameters
PHP OCI. php+ini Para1eter!
The php"ini d!rec"!&es 'or OC:$ are sho+n !n "he ne/" "able)
)able 2A' O-./ php"ini para+eters
Na1e #e*ault <alid :ange #e!cription
oci8.connection$class null % shor"
s"r!ng
% user?chosen name 'or Oracle
Da"abase 11g Connec"!on Pool!ng
CDRCPF. :n general, use "he same
name 'or all +eb ser&ers runn!ng
"he same appl!ca"!on. Can also be
se" +!"h ini$set%&.
:n"roduced !n OC:$ 1.I.
oci8.de'ault$pre'etch 100
Pr!or "o
OC:$
1.I.J
"he
de'aul"
+as 10
RQ 0
Pr!or "o
OC:$ 1.J !"
had "o be
RQ 1
The number o' e/"ra ro+s "ha"
Oracle 'e"ches and !n"ernall
bu''ers +hene&er a >uer ro+ !s
phs!call re"r!e&ed 'rom "he
da"abase. Th!s !mpro&es >uer
per'ormance b reduc!ng "he
number o' ne"+or( accesses "o
"he da"abase. 2rom Oracle 11gR2
on+ards "h!s parame"er also
a''ec"s 'e"ch!ng 'rom R;2
CUR4OR4.
%lso see oci$set$pre'etch%&.
oci8.eCents O'' O'' or On %llo+s PHP "o rece!&e 2as"
%ppl!ca"!on 7o"!'!ca"!on C2%7F
e&en"s 'rom Oracle "o g!&e
!mmed!a"e no"!'!ca"!on o' a
da"abase node or ne"+or( 'a!lure.
The da"abase mus" also be
con'!gured "o pos" e&en"s.
:n"roduced !n OC:$ 1.I.
oci8.ma.$persistent ?1 RQ ?1
?1 means
no l!m!"
Ma/!mum number o' pers!s"en"
connec"!ons each PHP process
caches. 7o"e "h!s !s no" a ss"em?
+!de "o"al.
oci8.old$oci$close$semantics O'' O'' or On Toggles +he"her oci$close%& uses
"he old beha&!or, +h!ch +as a Dno?
opE.
)(*
!H! .C'1 phpDini !arameters
Na1e #e*ault <alid :ange #e!cription
oci8.persistent$timeout ?1 R ?1
?1 means
no "!meou"
Ho+ man seconds a pers!s"en"
connec"!on !s allo+ed "o rema!n
!dle be'ore be!ng "erm!na"ed b !"s
PHP process. PHP processes +!ll
chec( "h!s each "!me "he process
!s reused.
oci8.ping$interCal O0 RQ 0
?1 means
no e/"ra
chec(
occurs
Ho+ man seconds a pers!s"en"
connec"!on can be unused be'ore
an e/"ra chec( dur!ng
oci$pconnect%& &er!'!es "he
da"abase connec"!on !s s"!ll &al!d.
oci8.priCileged$connect O'' O'' or On Toggles +he"her 4M4D-% and
4M4OP;R connec"!ons are
perm!""ed.
oci8.statement$cache$siXe 20 RQ 0 :mpro&es da"abase per'ormance
b cach!ng "he g!&en number o'
4B. s"a"emen"s !n PHP. 4e""!ng !"
"o 0 d!sables s"a"emen" cach!ng.
)(+
.C'1 phpDini !arameters
)(-
,PPEN#I4 C
OCI. 90NCTION N,5ES IN PHP " ,N#
PHP 5
:n PHP H se&eral e/"ens!ons !nclud!ng OC:$ under+en" 'unc"!on name s"andard!1a"!on. PHP J
'unc"!ons l!(e 345Kogin%& became oci$connect%&, "he 'unc"!on 345Earse%& became
oci$parse%&, and so on. %l"hough depreca"ed, "he old OC:$ names s"!ll e/!s" as al!ases. PHP J
scr!p"s do no" necessar!l need "o be changed +hen m!gra"!ng. P;C. OC:$ releases 'rom 1.1
on+ards ha&e "he ne+ 'unc"!on names.
7o"e) The OC:$ 1.J e/"ens!on bu!lds and runs +!"h PHP J and PHP H. :' ou are s"!ll us!ng PHP
J and canno" upgrade "o PHP H, ou should replace "he OC:$ code +!"h "he ne+ &ers!on "o ge"
!mpro&ed s"ab!l!" and per'ormance op"!m!1a"!ons. 4"eps "o !ns"all 'rom P;C. are g!&en !n "h!s
boo(.
2unc"!on names !n PHP are case !nsens!"!&e. There seems "o be a common accep"ance 'or PHP
J names "o be +r!""en +!"h a cap!"al!1ed pre'!/ bu" "he PHP H names "o be all lo+ercase.
Table 21 sho+s "he PHP J OC:$ 'unc"!ons and g!&es "he!r PHP H replacemen"s. 7o"e se&eral
'unc"!ons such as oci'reedesc%& and ocilo/close%& +ere onl usable as me"hods !n PHP J.
)able 2&' :elationship bet,een O-./%s PHP 5 and PHP 4 *unction na+es"
Operation ,ction PHP " Na1e PHP 5 Na1e
Connec"!on Open
connec"!on
ocilogon%& oci$connect%&
Open ne+
connec"!on
ocinlogon%& oci$new$connect%&
Pers!s"en"
connec"!on
ociplogon%& oci$pconnect%&
Cand ne+ php"ini parame"ersF
Close
connec"!on
ocilogo''%& oci$close%&
Cursor Open cursor ocinewcursor%& oci$new$cursor%&
Close
cursor
oci'reecursor%&
oci'reestatement%&
oci$'ree$statement%&
Pars!ng Parse
s"a"emen"
ociparse%& oci$parse%&
-!nd!ng -!nd
&ar!able
oci/ind/#name%& oci$/ind$/#$name%&
)(0
.C'1 8unction Names in !H! * and !H! +
Operation ,ction PHP " Na1e PHP 5 Na1e
-!nd arra 7o" a&a!lable oci$/ind$arra#$/#$name%&
De'!n!ng De'!ne
ou"pu"
&ar!ables
ocide'ine/#name%& oci$de'ine$/#$name%&
;/ecu"!on ;/ecu"e
s"a"emen"
ocie.ecute%& oci$e.ecute%&
2e"ch!ng 2e"ch ro+ oci'etch%& oci$'etch%&
2e"ch ro+ oci'etchinto%& oci$'etch$arra#%&
oci$'etch$row%&
oci$'etch$assoc%&
oci$'etch$o/Wect%&
2e"ch all
ro+s
oci'etchstatement%& oci$'etch$all%&
2e"ch
column
ociresult%& oci$result%&
:s "he
column
7U..`
ocicolumnisnull%& oci$'ield$is$null%&
Cancel
2e"ch
ocicancel%& oci$cancel%&
Transac"!on
Managemen"
Comm!" ocicommit%& oci$commit%&
Rollbac( ociroll/ack%& oci$roll/ack%&
Descr!p"ors ocinewdescriptor%& oci$new$descriptor%&
oci'reedesc%& oci$'ree$descriptor%&
;rror
Handl!ng
ocierror%& oci$error%&
.ong Ob8ec"s
C.O-sF
ocisaCelo/%& 345-Ko/::saCe%&
ocisaCelo/'ile%& 345-K3I::import%&
ociwritelo/to'ile%& 345-K3I::e.port%&
ociwritetemporar#lo/%& 345-Ko/::write:emporar#%&
ociloadlo/%& 345-Ko/::load%&
ocicloselo/%& 345-Ko/::close%&
Collec"!ons ocinewcollection%& oci$new$collection%&
oci'reecollection%& 345-4ollection::'ree%&
)(1
.C'1 8unction Names in !H! * and !H! +
Operation ,ction PHP " Na1e PHP 5 Na1e
ocicollappend%& 345-4ollection::append%&
ocicollgetelem%& 345-4ollection::get-lem%&
ocicollassign%& 345-4ollection::assign%&
ocicollassignelem%& 345-4ollection::assign-lem%&
ocicollsiXe%& 345-4ollection::siXe%&
ocicollma.%& 345-4ollection::ma.%&
ocicolltrim%& 345-4ollection::trim%&
Me"ada"a 4"a"emen"
"pe
ocistatementt#pe%& oci$statement$t#pe%&
7ame o'
resul"
column
ocicolumnname%& oci$'ield$name%&
4!1e o'
resul"
column
ocicolumnsiXe%& oci$'ield$siXe%&
Da"a "pe
o' resul"
column
ocicolumnt#pe%& oci$'ield$t#pe%&
Da"a "pe
o' resul"
column
ocicolumnt#peraw%& oci$'ield$t#pe$raw%&
Prec!s!on o'
resul"
column
ocicolumnprecision%& oci$'ield$precision%&
4cale o'
resul"
column
ocicolumnscale%& oci$'ield$scale%&
7umber o'
ro+s
a''ec"ed
ocirowcount%& oci$num$rows%&
7umber o'
columns
re"urned
ocinumcols%& oci$num$'ields%&
Chang!ng
Pass+ord
ocipasswordchange%& oci$password$change%&
)(2
.C'1 8unction Names in !H! * and !H! +
Operation ,ction PHP " Na1e PHP 5 Na1e
Mon!"or!ng,
Tun!ng and
%ud!"!ng
7o" a&a!lable oci$set$module$name%&
oci$set$action%&
oci$set$client$in'o%&
oci$set$client$identi'ier%&
Trac!ng ociinternalde/ug%& oci$internal$de/ug%&
Upgrad!ng %llo+
mul"!ple
&ers!ons o'
P.<4B.
ob8ec"s "o
be used
7o" a&a!lable oci$set$edition%&
Oracle Cl!en"
,ers!on
7o" a&a!lable oci$client$Cersion%&
4er&er
,ers!on
ociserCerCersion%& oci$serCer$Cersion%&
Tun!ng ocisetpre'etch%& oci$set$pre'etch%&
Cand ne+ php"ini parame"erF
))3
,PPEN#I4 #
THE O)SO'ETE O:,C'E E4TENSION
Th!s append!/ compares "he long obsole"e Oracle PHP e/"ens!on "o "he curren" OC:$
e/"ens!on. ,er rarel ou m!gh" come across PHP scr!p"s "ha" use "h!s earl Oracle %P:. :" !s
no longer !ncluded +!"h PHP. The 'unc"!onal!" !" o''ered +as l!m!"ed. Upgrad!ng "o "he ne+
OC:$ e/"ens!on m!gh" be as s!mple as enabl!ng "he ne+er OC:$ e/"ens!on !n "he PHP b!nar
and renam!ng "he old 'unc"!on calls !n our scr!p"s. Pa some a""en"!on "o "ransac"!on
managemen" and connec"!on handl!ng changes. :" !s +!se "o "es" our appl!ca"!on and ma(e
sure !" beha&es as ou e/pec" !" "o.
Oracle and OCI. Co1pari!on
The 'ollo+!ng "able sho+s "he general rela"!onsh!p be"+een "he obsole"e and curren"
e/"ens!ons)
)able 22' :elationship bet,een the O-./ and the obsolete Oracle extensions"
Operation ,ction O:, *unction Io$!oleteJ OCI. *unction
Connec"!on Open
connec"!on
ora$logon%& oci$connect%&
Open ne+
connec"!on
7o" a&a!lable oci$new$connect%&
Pers!s"en"
connec"!on
ora$plogon%& oci$pconnect%&
Cand ne+ php"ini parame"ersF
Close
connec"!on
ora$logo''%& oci$close%&
Used 'or
mon!"or!ng,
aud!"!ng and
,PD
7o" a&a!lable oci$set$client$identi'ier%&
Cursor Open cursor ora$open%& oci$new$cursor%&
Close cursor ora$close%& oci$'ree$statement%&
Pars!ng Parse
s"a"emen"
ora$parse%& oci$parse%&
-!nd!ng -!nd &ar!able ora$/ind%& oci$/ind$/#$name%&
-!nd arra 7o" a&a!lable oci$/ind$arra#$/#$name%&
;/ecu"!on ;/ecu"e
s"a"emen"
ora$e.ec%& oci$e.ecute%&
))&
The .5solete .racle 4%tension
Operation ,ction O:, *unction Io$!oleteJ OCI. *unction
Prepare,
e/ecu"e and
'e"ch
ora$do%& oci$parse%&
2ollo+ed b
oci$e.ecute%&
and one o')
oci$'etch$all%&
oci$'etch$arra#%&
oci$'etch$assoc%&
oci$'etch$o/Wect%&
oci$'etch$row%&
oci$'etch%&
2e"ch!ng 2e"ch ro+ ora$'etch%& oci$'etch%&
2e"ch ro+ ora$'etch$into oci$'etch$arra#%&
oci$'etch$row%&
oci$'etch$assoc%&
oci$'etch$o/Wect%&
2e"ch all ro+s 7o" a&a!lable oci$'etch$all%&
2e"ch column ora$getcolumn%& oci$result%&
:s "he column
7U..`
7o" a&a!lable oci$'ield$is$null%&
Cancel 2e"ch 7o" a&a!lable oci$cancel%&
Transac"!on
Managemen"
Comm!" ora$commit%& oci$commit%&
Comm!" mode ora$commiton%&
ora$commito''%&
Pass OC:N7ON%UTONCOMM:T 'lag
"o oci$e.ecute%&
Rollbac( ora$roll/ack%& oci$roll/ack%&
;rror
Handl!ng
ora$error%&
ora$errorcode%&
oci$error%&
))(
.racle and .C'1 Comparison
Operation ,ction O:, *unction Io$!oleteJ OCI. *unction
.ong Ob8ec"s
C.O-4F
7o" a&a!lable 345-Ko/-append
345-Ko/-close
345-Ko/-eo'
345-Ko/-erase
345-Ko/-e.port
345-Ko/-'lush
345-Ko/-'ree
345-Ko/-getIu''ering
345-Ko/-import
345-Ko/-load
345-Ko/-read
345-Ko/-rewind
345-Ko/-saCe
345-Ko/-saCeAile
345-Ko/-seek
345-Ko/-setIu''ering
345-Ko/-siXe
345-Ko/-tell
345-Ko/-truncate
345-Ko/-write
345-Ko/-write:emporar#
345-Ko/-write:oAile
Collec"!ons 7o" a&a!lable 345-4ollection-append
345-4ollection-assign
345-4ollection-assign-lem
345-4ollection-'ree
345-4ollection-get-lem
345-4ollection-ma.
345-4ollection-siXe
345-4ollection-trim
Me"ada"a 4"a"emen"
"pe
7o" a&a!lable oci$statement$t#pe%&
7ame o'
resul" column
ora$columnname%& oci$'ield$name%&
)))
The .5solete .racle 4%tension
Operation ,ction O:, *unction Io$!oleteJ OCI. *unction
4!1e o' resul"
column
ora$columnsiXe%& oci$'ield$siXe%&
Da"a "pe o'
resul" column
ora$columnt#pe%& oci$'ield$t#pe%&
oci$'ield$t#pe$raw%&
Prec!s!on o'
resul" column
7o" a&a!lable oci$'ield$precision%&
4cale o' resul"
column
7o" a&a!lable oci$'ield$scale%&
7umber o'
ro+s e''ec"ed
ora$numrows%& oci$num$rows%&
7umber o'
columns
re"urned
ora$numcols%& oci$num$'ields%&
4B.
Mon!"or!ng
4end
me"ada"a "o
Oracle 'or
"rac!ng and
mon!"or!ng
7o" a&a!lable oci$set$module$name%&
oci$set$action%&
oci$set$client$in'o%&
Chang!ng
Pass+ord
7o" a&a!lable oci$password$change%&
Trac!ng 7o" a&a!lable oci$internal$de/ug%&
Oracle Cl!en"
and 4er&er
,ers!ons
7o" a&a!lable oci$client$Cersion%&
oci$serCer$Cersion%&
Tun!ng 7o" a&a!lable oci$set$pre'etch%&
Cand ne+ php"ini parame"erF
Upgrad!ng %llo+ mul"!ple
&ers!ons o'
P.<4B.
ob8ec"s "o be
used
7o" a&a!lable oci$set$edition%&
))*
,PPEN#I4 E
:ESO0:CES
Th!s append!/ g!&es l!n(s "o documen"a"!on, resources and ar"!cles d!scussed !n "h!s boo(, and
"o o"her +eb s!"es o' !n"eres". Th!s boo( !"sel' can be 'ound 'ree onl!ne a")
http://www.oracle.com/technetwork/topics/php/underground-php-oracle-manual-
098250.html
General In*or1ation and 9oru1!
PHP Developer Center on Oracle 4ec%nology >etwor0 HO4>I
http://www.oracle.com/technetwork/topics/php/whatsnew/
O4> PHP Discussion /oru&
http://www.oracle.com/technetwork/'orums/php/
#logJ C%ristop%er Kones on OP1)
http:///logs.oracle.com/opal/
1s04o&
3eneral Oracle language and appl!ca"!on des!gn help
http://asktom.oracle.com/
Oracle )inux
https://linu..oracle.com/
Oracle Support
http://support.oracle.com/
OracleLs /ree and Open Source So8tware
http://oss.oracle.com/
Oracle #ocu1entation and Whitepaper!
Oracle 11g elease , Docu&entation )ibrary
http://www.oracle.com/pls/d/112/homepage
))+
Resources
Oracle 4i&es4en In(3e&ory Database Docu&entation
http://www.oracle.com/technetwork/products/timesten/documentation/
Oracle Database Express Edition Docu&entation
http://www.oracle.com/technetwork/products/e.press-edition/documentation/
Oracle Call Interface Programmer's Guide 11g elease , H11.,I
http://docs.oracle.com/cd/-11882$01/appdeC.112/e10PDP/toc.htm
Oracle Database Express Edition 2 Day + PHP Deeloper's Guide !!g "elease 2 #!!$2%
http://docs.oracle.com/cd/-1UU81$01/appdeC.112/e18555/toc.htm
Oracle Database &et 'erices (dministrator's Guide !!g "elease 2 #!!$2%
http://docs.oracle.com/cd/-11882$01/network.112/e108@P/toc.htm
Oracle Database P)*'+) )anguage "eference !!g "elease 2 #!!$2%
http://docs.oracle.com/cd/-11882$01/appdeC.112/e25519/toc.htm
Oracle Database '+) )anguage "eference !!g "elease 2 #!!$2%
http://docs.oracle.com/cd/-11882$01/serCer.112/e2P088/toc.htm
Oracle 4uxedo Docu&entation
http://www.oracle.com/technetwork/middleware/tu.edo/documentation/inde..html
'%itepaper, Oracle -uxedo, (n Enterprise Platform for Dynamic )anguages
http://www.oracle.com/technetwork/middleware/tu.edo/tu.edo-d#namic-langs-
twp-D01DU1.pd'
Selected PHP and Oracle )oo=!
Oracle Database !!g P)*'+) Programming
M!chael Mc.aughl!n, Oracle Press, 200$.
Oracle Database (.(/ 0 PHP 1eb (pplication Deelopment
.ee -arne and M!chael Mc.aughl!n, Oracle Press, 200$
PHP Oracle 1eb Deelopment
Mul! ,as!l!e&, Pac(" Publ!sh!ng, 200P
2eginning PHP and Oracle, 3rom &oice to Professional
0. *ason 3!lmore and -ob -rla, %press, 200P
))-
#elected !H! and .racle >ooks
(pplication Deelopment 4it5 Oracle 0 PHP on )inux for 2eginners
:&an -aross and 4haranam 4hah, 4hro'' Publ!shers a D!s"r!bu"ers, 2
nd
;d!"!on 200P
Oracle Database !6g Express Edition PHP 1eb Programming
M!chael Mc.aughl!n, Osbourne Oracle Press, 200O
Easy Oracle PHP, Create Dynamic 1eb Pages 4it5 Oracle Data
Mladen 3ogala, Rampan" TechPress, 200O
So*t;are and Source Code
PHP Distribution eleases
4ource and 0!ndo+s b!nar!es
http://www.php.net/downloads.php
PHP Snaps%ots Hincludes OCI!I
4napsho"s o' PHPAs source code and 0!ndo+s b!nar!es
http://snaps.php.net/
PHP Source Hincludes OCI!I
http://git.php.net/?p*php-src.git
https://githu/.com/php/php-src
PEC) OCI! Source pac0age HstandaloneI
http://pecl.php.net/package/oci8
?end Server
http://www.oracle.com/technetwork/topics/php/Xend-serCer-09P@1D.html
Oracle Instant Client
http://www.oracle.com/technetwork/data/ase/'eatures/instant-client/inde.-
09UD80.html
Oracle >et#eans IDE
http://net/eans.org/
Oracle S9) Developer
http://www.oracle.com/technetwork/deCeloper-tools/s"l-deCeloper/oCerCiew/
1DOdb Database 1bstraction )ibrary 8or PHP Hand Pyt%onI
http://adod/.source'orge.net/
))0
Resources
PHP$nit PHP $nit 4ester
http://www.phpunit.de/
Si&ple4est PHP $nit 4ester
http://www.simpletest.org/
6debug ( Debugger and Pro8iler 4ool 8or PHP
http://www..de/ug.org/
PHP 'in=!
PHP Ho&e Page
http://php.net/
PHP Docu&entation
http://php.net/docs.php
PHP Oracle OCI! Docu&entation
http://php.net/oci8
PHP 9uality 1ssurance Site
http://"a.php.net/
PHP #ug Syste&
http:///ugs.php.net/
PHP 'i0i
http://wiki.php.net/
))1
G'OSS,:G
,non61ou! )loc=
% P.<4B. bloc( "ha" appears !n our appl!ca"!on and !s no" named or s"ored !n "he
da"abase. :n man appl!ca"!ons, P.<4B. bloc(s can appear +here&er 4B. s"a"emen"s can
appear. % P.<4B. bloc( groups rela"ed declara"!ons and s"a"emen"s. -ecause "hese bloc(s
are no" s"ored !n "he da"abase, "he are generall 'or one?"!me use.
,W:
%u"oma"!c 0or(load Repos!"or. Used "o s"ore and repor" s"a"!s"!cs on da"abase
per'ormance.
)inding
% me"hod o' !nclud!ng da"a !n 4B. s"a"emen"s "ha" allo+s 4B. s"a"emen"s "o be e''!c!en"l
reused +!"h d!''eren" da"a.
)9I'E
The -2:.; da"a "pe s"ores uns"ruc"ured b!nar da"a !n opera"!ng?ss"em '!les ou"s!de "he
da"abase. % -2:.; column or a""r!bu"e s"ores a '!le loca"or "ha" po!n"s "o an e/"ernal '!le
con"a!n!ng "he da"a.
)'O)
The -.O- da"a "pe s"ores uns"ruc"ured b!nar da"a !n "he da"abase.
CH,:
The CH%R da"a "pe s"ores '!/ed?leng"h charac"er s"r!ngs !n "he da"abase.
C'O) and NC'O)
The C.O- and 7C.O- da"a "pes s"ore up "o e!gh" "erab"es o' charac"er da"a !n "he
da"abase. C.O-s s"ore da"abase charac"er se" da"a, and 7C.O-s s"ore Un!code na"!onal
charac"er se" da"a.
Collection T6pe
% collec"!on !s an ordered group o' elemen"s, all o' "he same "pe. ;ach elemen" has a
un!>ue subscr!p" "ha" de"erm!nes !"s pos!"!on !n "he collec"!on. P.<4B. da"a "pes T%-.;
and ,%RR%M enable collec"!on "pes such as arras, bags, l!s"s, nes"ed "ables, se"s and
"rees.
Connection Identi*ier
The s"r!ng used "o !den"!' +h!ch da"abase "o connec" "o, 'or e/ample, localhost/,-.
))2
Connection String
The 'ull s"r!ng used "o !den"!' +h!ch da"abase "o connec" "o commonl used 'or 4B.SPlus.
:" con"a!ns "he username, pass+ord and connec" !den"!'!er, 'or e/ample,
hr/welcomeOlocalhost/,-.
#ata #ictionar6
% se" o' "ables and &!e+s "ha" are used as a read?onl re'erence abou" "he da"abase.
#ata$a!e
% da"abase s"ores and re"r!e&es da"a. ;ach da"abase cons!s"s o' one or more da"a '!les.
%l"hough ou ma ha&e more "han one da"abase per mach!ne, "p!call a s!ngle Oracle
da"abase con"a!ns mul"!ple schemas. % schema !s o'"en e>ua"ed +!"h a user. Mul"!ple
appl!ca"!ons can use "he same da"abase +!"hou" an con'l!c" b us!ng d!''eren" schemas.
#ata$a!e 'in=
% po!n"er "ha" de'!nes a one?+a commun!ca"!on pa"h 'rom an Oracle Da"abase ser&er "o
ano"her da"abase ser&er. % da"abase l!n( connec"!on allo+s local users "o access da"a on a
remo"e da"abase.
#ata$a!e Na1e
The name o' "he da"abase. :n PHP, "h!s !s "he "e/" used !n oci$connect%& calls. %lso see
Easy -onnect.
#ata t6pe
;ach column &alue and cons"an" !n a 4B. s"a"emen" has a da"a "pe, +h!ch !s assoc!a"ed
+!"h a spec!'!c s"orage 'orma", cons"ra!n"s, and a &al!d range o' &alues. 0hen ou crea"e a
"able, ou mus" spec!' a da"a "pe 'or each o' !"s columns. 2or e/ample, 7UM-;R, or
D%T;.
#,TE
The D%T; da"a "pe s"ores po!n"?!n?"!me &alues Cda"es and "!mesF !n a da"abase "able.
#,TETI5E
%n e/"ens!on o' "he da"e "pe +!"h grea"er prec!s!on "han D%T; and +!"h an assoc!a"ed
"!me1one.
#),
Da"abase %dm!n!s"ra"or. % person +ho adm!n!s"ers "he Oracle da"abase. Th!s person !s a
spec!al!s" !n Oracle da"abases, and +ould usuall ha&e 4M4D-% access "o "he da"abase.
)*3
##'
4B.Ks Da"a De'!n!"!on .anguage. 4B. s"a"emen"s "ha" de'!ne "he da"abase s"ruc"ure or
schema, l!(e 4B-6:-, 6K:-B, and LB3E.
#5'
4B.Ks Da"a Man!pula"!on .anguage. 4B. s"a"emen"s "ha" de'!ne or manage "he da"a !n "he
da"abase, l!(e 7-K-4:, 5M7-B:, REL6:- and L-K-:-.
#:CP
Da"abase Res!den" Connec"!on Pool!ng. :n"roduced !n Oracle Da"abase 11g, "h!s
connec"!on pool!ng allo+s mul"!ple cl!en" processes and mach!nes "o share connec"!on
da"a s"ruc"ures on "he da"abase ser&er, reduc!ng "he memor re>u!remen"s o' large
numbers o' users.
Ea!6 Connect
% s!mple hos"name and da"abase connec" !den"!'!er "ha" !s used "o !den"!' +h!ch da"abase
"o connec" "o.
Git
%n open source &ers!on con"rol ss"em used 'or de&elopmen" o' PHP.
H:
The sample user crea"ed b de'aul" +!"h an Oracle seed da"abase !ns"alla"!on. The HR user
has access "o "he Human Resources demons"ra"!on "ables !n "he HR schema.
Inde
:nde/es are op"!onal s"ruc"ures assoc!a"ed +!"h da"abase "ables. :nde/es can be crea"ed "o
!ncrease "he per'ormance o' da"a re"r!e&al.
In!tance
The Oracle :ns"ance !s "he runn!ng componen" o' an Oracle da"abase ser&er. 0hen an
Oracle da"abase !s s"ar"ed, a ss"em global area C43%F !s alloca"ed and Oracle bac(ground
processes are s"ar"ed. The comb!na"!on o' "he bac(ground processes and memor bu''ers
!s called an Oracle !ns"ance.
In!tant Client
The Oracle :ns"an" Cl!en" !s a small se" o' l!brar!es, +h!ch allo+s appl!ca"!ons "o connec" "o
an Oracle Da"abase. % subse" o' "he 'ull Oracle Cl!en", !" re>u!res m!n!mal !ns"alla"!on bu"
has 'ull 'unc"!onal!". :ns"an" Cl!en" !s do+nloadable 'rom OT7 and !s usable and
d!s"r!bu"able 'or 'ree.
)*&
'O)
% large ob8ec". .O-4 ma be pers!s"en" Cs"ored !n "he da"abaseF or "emporar. 4ee -FOI,
IFOI, and I(.FE.
'O) 'ocator
% Dpo!n"erE "o .O- da"a.
5ateriali8ed <ie;
% ma"er!al!1ed &!e+ pro&!des access "o "able da"a b s"or!ng "he resul"s o' a >uer !n a
separa"e da"abase schema ob8ec". Unl!(e an ord!nar &!e+, +h!ch does no" "a(e up an
s"orage space or con"a!n an da"a, a ma"er!al!1ed &!e+ con"a!ns "he ro+s resul"!ng 'rom a
>uer aga!ns" one or more base "ables or &!e+s.
NCH,: and N<,:CH,:2
7CH%R and 7,%RCH%R2 are Un!code da"a "pes "ha" s"ore Un!code charac"er da"a !n "he
da"abase.
N05)E:
The 7UM-;R da"a "pe s"ores '!/ed and 'loa"!ng?po!n" numbers !n "he da"abase.
O$3ect Pri-ilege
% r!gh" "o per'orm a par"!cular ac"!on on a spec!'!c da"abase schema ob8ec". D!''eren"
ob8ec" pr!&!leges are a&a!lable 'or d!''eren" "pes o' schema ob8ec"s. The pr!&!lege "o dele"e
ro+s 'rom "he D;P%RTM;7T4 "able !s an e/ample o' an ob8ec" pr!&!lege.
OCI
Oracle Call :n"er'ace. The ma!n C %P: 'or access!ng "he Oracle Da"abase. 2!rs" !n"roduced !n
&ers!on e!gh" o' Oracle Da"abase !" !s commonl re'erred "o as OC:$.
OCI.
PHPAs ma!n e/"ens!on 'or access!ng Oracle Da"abase :" !s !mplemen"ed us!ng calls "o
OracleAs OC: %P:.
O:,C'EAHO5E in!tall
%n Oracle Cl!en" or Oracle Da"abase !ns"all. These !ns"alls con"a!n all so'"+are re>u!red b
PHP !n a d!rec"or h!erarch. Th!s se" o' d!rec"or!es !ncludes b!nar!es, u"!l!"!es, con'!gura"!on
scr!p"s, demons"ra"!on scr!p"s and error message '!les 'or each componen" o' Oracle. %n
program us!ng Oracle "p!call re>u!res "he OR%C.;NHOM; en&!ronmen" &ar!able "o be se"
"o "he "op le&el !ns"alla"!on d!rec"or.
)*(
Oracle Net
The ne"+or(!ng componen" o' Oracle "ha" connec"s cl!en" "ools such as PHP "o local or
remo"e da"abases. The Oracle 7e" l!s"ener !s a process "ha" handles connec"!on re>ues"s
'rom cl!en"s and passes "hem "o "he "arge" da"abase.
OTN
The Oracle Technolog 7e"+or( !s OracleKs 'ree repos!"or o' ar"!cles on Oracle
"echnolog!es. :" also hos"s so'"+are do+nloads and man d!scuss!on 'orums, !nclud!ng one
on PHP.
Pac=age
% group o' P.<4B. procedures, 'unc"!ons, and &ar!able de'!n!"!ons s"ored !n "he Oracle
da"abase. Procedures, 'unc"!ons, and &ar!ables !n pac(ages can be called 'rom o"her
pac(ages, procedures, or 'unc"!ons.
P#O
PHP Da"a Ob8ec"s. % da"a abs"rac"!on laer 'or PHP. :" cons!s"s o' "+o par"s, a gener!c laer
and da"abase &endor spec!'!c dr!&ers, each o' +h!ch ma e/pose da"abase spec!'!c
'ea"ures.
PE,:
The PHP ;/"ens!on and %ppl!ca"!on Repos!"or !s a repos!"or 'or reusable pac(ages +r!""en
!n PHP.
PEC'
The PHP ;/"ens!on Commun!" .!brar !s a repos!"or o' PHP e/"ens!ons "ha" can be l!n(ed
!n"o "he PHP b!nar.
PHP
% popular, !n"erpre"ed scr!p"!ng language commonl used 'or +eb appl!ca"!ons. PHP !s a
recurs!&e acronm 'or DPHP) Hper"e/" PreprocessorE.
php.ini
The con'!gura"!on '!le used b PHP. Man Cbu" no" allF op"!ons "ha" are se" !n php"ini can
also be se" a" run"!me us!ng ini$set%&. 4s"ems can be con'!gured "o read mul"!ple
!n!"!al!1a"!on '!les.
P'2S&'
OracleKs procedural language e/"ens!on "o 4B.. :" !s a ser&er?s!de, s"ored, procedural
language "ha" enables ou "o m!/ 4B. s"a"emen"s +!"h procedural cons"ruc"s. 0!"h
P.<4B., ou can crea"e and run P.<4B. program un!"s such as procedures, 'unc"!ons, and
pac(ages. P.<4B. program un!"s generall are ca"egor!1ed as anonmous bloc(s, s"ored
'unc"!ons, s"ored procedures, and pac(ages.
)*)
Prepared State1ent
% 4B. s"a"emen" "ha" has been parsed b "he da"abase. :n Oracle, !" !s generall called a
parsed s"a"emen".
Procedure! and 9unction!
% P.<4B. procedure or 'unc"!on !s a schema ob8ec" "ha" cons!s"s o' a se" o' 4B. s"a"emen"s
and o"her P.<4B. programm!ng cons"ruc"s, grouped "oge"her, s"ored !n "he da"abase, and
run as a un!" "o sol&e a spec!'!c problem or per'orm a se" o' rela"ed "as(s.
:egular Epre!!ion
% pa""ern used "o ma"ch da"a. Oracle has se&eral 'unc"!ons "ha" accep" regular
e/press!ons.
:ound Trip
% call and re"urn se>uence 'rom PHP OC:$ "o "he Da"abase per'ormed b "he underl!ng
dr!&er l!brar!es. ;ach round "r!p "a(es ne"+or( "!me and mach!ne CPU resources. The 'e+er
round "r!ps per'ormed, "he more scalable a ss"em !s l!(el "o be. PHP OC:$ 'unc"!ons ma
!n!"!a"e 1ero or man round "r!ps.
Sche1a
% schema !s a collec"!on o' da"abase ob8ec"s. % schema !s o+ned b a da"abase user and
has "he same name as "ha" user. 4chema ob8ec"s are "he log!cal s"ruc"ures "ha" d!rec"l
re'er "o "he da"abaseAs da"a. 4chema ob8ec"s !nclude s"ruc"ures l!(e "ables, &!e+s, and
!nde/es.
S#F
4o'"+are De&elopmen" 6!". Oracle :ns"an" Cl!en" has an 4D6 'or bu!ld!ng programs "ha" use
"he :ns"an" Cl!en" l!brar!es.
SeBuence
% se>uen"!al ser!es o' Oracle !n"egers o' up "o I$ d!g!"s de'!ned !n "he da"abase.
Ser-ice Na1e
% ser&!ce name !s a s"r!ng "ha" !s "he global da"abase name, compr!sed o' "he da"abase
name and doma!n name. Mou can ob"a!n !" 'rom "he 4;R,:C;N7%M;4 parame"er !n "he
da"abase !n!"!al!1a"!on parame"er '!le or b us!ng 7>3? E6B6N-:-B7 !n 4B.SPlus. :" !s used
dur!ng connec"!on "o !den"!' +h!ch da"abase "o connec" "o.
SI# IS6!te1 Identi*ierJ
The ss"em !den"!'!er !s commonl used "o mean "he da"abase name al!as !n "he
connec"!on s"r!ng.
)**
SI# ISe!!ion Identi*ierJ
% sess!on !den"!'!er !s a un!>ue number ass!gned "o each da"abase user sess!on +hen a
user connec"s "o "he da"abase.
S&'>Plu!
The "rad!"!onal command l!ne "ool 'or e/ecu"!ng 4B. s"a"emen"s a&a!lable +!"h all Oracle
da"abases. %l"hough recen"l superseded b 3U: "ools l!(e OracleKs 'ree 4B. De&eloper,
4B.SPlus rema!ns hugel popular. :" !s also con&en!en" "o sho+ e/amples us!ng 4B.SPlus.
Stored Procedure! and 9unction!
% P.<4B. bloc( "ha" Oracle s"ores !n "he da"abase and can be called b name 'rom an
appl!ca"!on. 2unc"!ons are d!''eren" "han procedures !n "ha" 'unc"!ons re"urn a &alue +hen
e/ecu"ed. 0hen ou crea"e a s"ored procedure or 'unc"!on, Oracle parses "he procedure or
'unc"!on, and s"ores !"s parsed represen"a"!on !n "he da"abase.
S6non61
% snonm !s an al!as 'or an da"abase "able, &!e+, ma"er!al!1ed &!e+, se>uence,
procedure, 'unc"!on, pac(age, "pe, *a&a class schema ob8ec", user?de'!ned ob8ec" "pe, or
ano"her snonm.
SGS
%n Oracle da"abase adm!n!s"ra"!&e user accoun" name. 4M4 has access "o all base "ables
and &!e+s 'or "he da"abase da"a d!c"!onar.
SGS#),
%n Oracle da"abase ss"em pr!&!lege "ha", b de'aul", !s ass!gned onl "o "he 4M4 user. :"
enables 4M4 "o per'orm h!gh?le&el adm!n!s"ra"!&e "as(s such as s"ar"!ng up and shu""!ng
do+n "he da"abase.
SGSOPE:
4!m!lar "o 4M4D-%, bu" +!"h a l!m!"ed se" o' pr!&!leges "ha" allo+s bas!c adm!n!s"ra"!&e
"as(s +!"hou" ha&!ng access "o user da"a.
SGSTE5
%n Oracle da"abase adm!n!s"ra"!&e user accoun" name "ha" !s used "o per'orm all
adm!n!s"ra"!&e 'unc"!ons o"her "han s"ar"!ng up and shu""!ng do+n "he da"abase.
S6!te1 pri-ilege
The r!gh" "o per'orm a par"!cular ac"!on, or "o per'orm an ac"!on on an da"abase schema
ob8ec"s o' a par"!cular "pe. 2or e/ample, "he pr!&!leges "o crea"e "ables and "o dele"e "he
ro+s o' an "able !n a da"abase.
)*+
Ta$le
Tables are "he bas!c un!" o' da"a s"orage. Da"abase "ables hold all user?access!ble da"a.
;ach "able has columns and ro+s.
Ta$le!pace
Tablespaces are "he log!cal un!"s o' Oracle da"a s"orage made up o' one or more da"a'!les.
Tablespaces are o'"en crea"ed 'or !nd!&!dual appl!ca"!ons because "ablespaces can be
con&en!en"l managed. Users are ass!gned a de'aul" "ablespace "ha" holds all "he da"a "he
users crea"es. % da"abase !s made up o' de'aul" and D-%?crea"ed "ablespaces.
Te1porar6 Ta$le
% 3lobal Temporar Table !s a spec!al "able "ha" holds sess!on?pr!&a"e da"a "ha" e/!s"s onl
'or "he dura"!on o' a "ransac"!on or sess!on. The "able !s crea"ed be'ore "he appl!ca"!on
runs.
Ti1e!Ten
%n !n?memor da"abase "ha" can be s"andalone +!"h '!le?bac(ed s"orage, or can ac" as a
cache 'or Oracle Da"abase.
Tn!na1e!.ora
The Oracle 7e" con'!gura"!on '!le used 'or connec"!ng "o a da"abase. The '!le maps an al!as
"o a local or remo"e da"abase and allo+s &ar!ous con'!gura"!on op"!ons 'or connec"!ons.
The al!as !s used !n "he PHP connec"!on s"r!ng. T74 s"ands 'or Transparen" 7e"+or(
4ubs"ra"e.
Tran!action
% se>uence o' 4B. s"a"emen"s +hose changes are e!"her all comm!""ed, or all rolled bac(.
Trigger
% s"ored procedure assoc!a"ed +!"h a da"abase "able, &!e+, or e&en". The "r!gger can be
called a'"er "he e&en", "o record !", or "a(e some 'ollo+?up ac"!on. The "r!gger can be called
be'ore "he e&en", "o pre&en" erroneous opera"!ons or '!/ ne+ da"a so "ha" !" con'orms "o
bus!ness rules.
0'N
Unbrea(able .!nu/ 7e"+or(. :" pro&!des Oracle .!nu/ so'"+are pa"ches, upda"es
and '!/es 'or suppor" subscr!bers.
0!er
% da"abase user !s o'"en e>ua"ed "o a schema. ;ach user connec"s "o "he da"abase +!"h a
username and secre" pass+ord, and has access "o "ables, and so on, !n "he da"abase.
)*-
<,:CH,: and <,:CH,:2
These da"a "pes s"ore &ar!able?leng"h charac"er s"r!ngs !n "he da"abase. The names are
curren"l snonms bu" ,%RCH%R2 !s recommended "o ensure ma/!mum compa"!b!l!" o'
appl!ca"!ons !n 'u"ure.
<ie;
,!e+s are cus"om!1ed presen"a"!ons o' da"a !n one or more "ables or o"her &!e+s. % &!e+
can also be cons!dered a s"ored >uer. ,!e+s do no" ac"uall con"a!n da"a. Ra"her, "he
der!&e "he!r da"a 'rom "he "ables on +h!ch "he are based, re'erred "o as "he base "ables o'
"he &!e+s.
<P#
,!r"ual Pr!&a"e Da"abase. %n Oracle Da"abase 'ea"ures "ha" allo+s ou "o crea"e secur!"
pol!c!es res"r!c"!ng access "o da"a a" "he ro+ and column le&el.
45'T6pe
=M.Tpe !s a da"abase da"a "pe "ha" can be used "o s"ore =M. da"a !n "able columns.
)*0
The Underground PHP
and Oracle Manual
About this Book
This book is for PHP programmers developing applications for Oracle
Database. It bridges the gap between the many PHP and Oracle
books available and shows how to use the PHP scripting language
with Oracle Database. You may be starting out with PHP for your
Oracle Database. You may be a PHP programmer wanting to learn
Oracle. You may be unsure how to install PHP or Oracle. Or you may
just want to know the latest best practices. This book gives you
the fundamental building blocks needed to create high-performance
PHP Oracle Web applications.
About the Authors
Christopher Jones works for Oracle on dynamic scripting languages
with a strong focus on PHP. He is a lead maintainer of PHPs open
source OCI8 extension and works closely with the PHP community.
He also helps ensure that future versions of Oracle Database are
compatible with PHP. He is the author of various technical articles on
PHP and Oracle technology, and has presented at conferences including
PHP|Tek, the International PHP Conference, the OReilly Open Source
Convention, and ZendCon. He also helps present Oracle PHP tutorials
and PHPFests worldwide.
Alison Holloway is a Consulting Technical Writer at Oracle with a number
of years experience in advanced technology. She has presented at various
PHP conferences. Most recently she has been working with Oracle VM.