reference/oci8/configure.xml
5e41012cfdf8f2eff5fa56de446c7656afac536c
...
...
@@ -1,28 +1,594 @@
1
-
<?xml version="1.0" encoding="iso-8859-1"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<section xml:id="oci8.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3
+
<section xml:id="oci8.installation">
4
4
&reftitle.install;
5
+

6
+

7
+
<section xml:id="oci8.configure" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
8
+
<title>Configuring PHP with OCI8</title>
9
+
<para>
10
+
Review the
11
+
previous <link linkend="oci8.requirements">Requirements</link>
12
+
section before configuring OCI8.
13
+
</para>
14
+
<para>
15
+
Before starting the web server, OCI8 typically requires several
16
+
Oracle environment variables (see below) to locate libraries, point
17
+
to configuration files, and set some basic properties such as the
18
+
character set used by Oracle libraries. The variables must be set
19
+
<emphasis>before</emphasis> any PHP process starts.
20
+
</para>
21
+
<para>
22
+
The PHP binary must link with the same, or more recent, major version of
23
+
Oracle libraries as it was configured with. For example, if you build
24
+
OCI8 with Oracle 19 libraries, then PHP should also be deployed
25
+
and run with Oracle 19 libraries. PHP applications can connect to other
26
+
versions of Oracle Database, since Oracle has client-server cross-version compatibility.
27
+
</para>
28
+
</section>
29
+
<section>
30
+
<title>Installing OCI8 from PECL Using the pecl Command</title>
31
+
<para xmlns:xlink="http://www.w3.org/1999/xlink">
32
+
The OCI8 extension can be added to an existing PHP installation by using
33
+
the <link xlink:href="&url.pecl.package;oci8">PECL</link> repository.
34
+
</para>
5
35
<para>
6
-
You have to compile PHP with the option
7
-
<option role="configure">--with-oci8[=DIR]</option>, where DIR defaults to
8
-
your environment variable ORACLE_HOME.
36
+
<itemizedlist>
37
+
<listitem>
38
+
<para>
39
+
If you are behind a firewall, set PEAR's proxy, for example:
40
+
</para>
41
+
<para>
42
+
<informalexample>
43
+
<screen>
44
+
<![CDATA[
45
+
pear config-set http_proxy http://my-proxy.example.com:80/
46
+
]]>
47
+
</screen>
48
+
</informalexample>
49
+
</para>
50
+
</listitem>
51
+
<listitem>
52
+
<para>
53
+
Run
54
+
</para>
55
+
<para>
56
+
<informalexample>
57
+
<screen>
58
+
<![CDATA[
59
+
pecl install oci8
60
+
]]>
61
+
</screen>
62
+
</informalexample>
63
+
</para>
64
+
<para>
65
+
For PHP 7, use <literal>pecl install oci8-2.2.0</literal>
66
+
</para>
67
+
</listitem>
68
+
<listitem>
69
+
<para>
70
+
When prompted, enter either the value of <literal>$ORACLE_HOME</literal>, or
71
+
<literal>instantclient,/path/to/instant/client/lib</literal>.
72
+
</para>
73
+
<para>
74
+
Note: Do not enter variable names like <literal>$ORACLE_HOME</literal>
75
+
or <literal>$HOME</literal> because <literal>pecl</literal> will not
76
+
expand them. Instead, enter an expanded path, for
77
+
example <literal>/opt/oracle/product/19c/dbhome_1</literal>
78
+
or <literal>instantclient,/Users/myname/Downloads/instantclient_19_8</literal>
79
+
</para>
80
+
</listitem>
81
+
<listitem>
82
+
<para>
83
+
If you get an error <literal>oci8_dtrace_gen.h: No such file or
84
+
directory</literal>, it means PHP was built
85
+
with <link linkend="features.dtrace">DTrace Dynamic Tracing</link> enabled.
86
+
Install using:
87
+
</para>
88
+
<para>
89
+
<informalexample>
90
+
<screen>
91
+
<![CDATA[
92
+
$ export PHP_DTRACE=yes
93
+
$ pecl install oci8
94
+
]]>
95
+
</screen>
96
+
</informalexample>
97
+
</para>
98
+
</listitem>
99
+
<listitem>
100
+
<para>
101
+
Edit your &php.ini; file and add the line:
102
+
</para>
103
+
<para>
104
+
<informalexample>
105
+
<screen>
106
+
<![CDATA[
107
+
extension=oci8.so
108
+
]]>
109
+
</screen>
110
+
</informalexample>
111
+
</para>
112
+
<para>
113
+
Make sure the &php.ini;
114
+
directive <link linkend="ini.extension-dir">extension_dir</link> is
115
+
set to the directory that <filename>oci8.so</filename> was installed
116
+
in.
117
+
</para>
118
+
</listitem>
119
+
</itemizedlist>
120
+
</para>
121
+
</section>
122
+
<section>
123
+
<title>Installing OCI8 from PECL Using phpize</title>
124
+
<para xmlns:xlink="http://www.w3.org/1999/xlink">
125
+
To install OCI8 on an existing PHP installation when
126
+
the <literal>pecl</literal> command is not available, manually download
127
+
the <link xlink:href="&url.pecl.package;oci8">PECL</link> OCI8 package,
128
+
e.g. <filename>oci8-3.0.0.tgz</filename>.
9
129
</para>
10
130
<para>
11
-
If you're using <link xlink:href="&url.oracle.instant.client;">Oracle Instant
12
-
Client</link>, you need to build PHP with the option
13
-
<option role="configure">--with-oci8=instantclient,/path/to/oic/lib</option>. Note
14
-
that Oracle Instant Client support first appeared in versions 4.3.11 and
15
-
5.0.4.
131
+
<itemizedlist>
132
+
<listitem>
133
+
<para>
134
+
Extract the package:
135
+
</para>
136
+
<para>
137
+
<informalexample>
138
+
<screen>
139
+
<![CDATA[
140
+
tar -zxf oci8-3.0.0.tgz
141
+
cd oci8-3.0.0
142
+
]]>
143
+
</screen>
144
+
</informalexample>
145
+
</para>
146
+
</listitem>
147
+
<listitem>
148
+
<para>
149
+
Prepare the package:
150
+
</para>
151
+
<para>
152
+
<informalexample>
153
+
<screen>
154
+
<![CDATA[
155
+
phpize
156
+
]]>
157
+
</screen>
158
+
</informalexample>
159
+
</para>
160
+
</listitem>
161
+
<listitem>
162
+
<para>
163
+
Configure the package, either
164
+
using <literal>$ORACLE_HOME</literal> or Instant Client
165
+
</para>
166
+
<para>
167
+
<informalexample>
168
+
<screen>
169
+
<![CDATA[
170
+
./configure -with-oci8=shared,$ORACLE_HOME
171
+
]]>
172
+
</screen>
173
+
</informalexample>
174
+
</para>
175
+
<para>
176
+
or
177
+
</para>
178
+
<para>
179
+
<informalexample>
180
+
<screen>
181
+
<![CDATA[
182
+
./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
183
+
]]>
184
+
</screen>
185
+
</informalexample>
186
+
</para>
187
+
</listitem>
188
+
<listitem>
189
+
<para>
190
+
Install the package:
191
+
</para>
192
+
<para>
193
+
<informalexample>
194
+
<screen>
195
+
<![CDATA[
196
+
make install
197
+
]]>
198
+
</screen>
199
+
</informalexample>
200
+
</para>
201
+
</listitem>
202
+
<listitem>
203
+
<para>
204
+
If you get an error <literal>oci8_dtrace_gen.h: No such file or
205
+
directory</literal>, it means PHP was built
206
+
with <link linkend="features.dtrace">DTrace Dynamic Tracing</link> enabled.
207
+
Re-run the <literal>configure</literal> and <literal>make</literal>
208
+
commands after setting this environment variable:
209
+
</para>
210
+
<para>
211
+
<informalexample>
212
+
<screen>
213
+
<![CDATA[
214
+
$ export PHP_DTRACE=yes
215
+
]]>
216
+
</screen>
217
+
</informalexample>
218
+
</para>
219
+
</listitem>
220
+
<listitem>
221
+
<para>
222
+
Edit your &php.ini; file and add the line:
223
+
</para>
224
+
<para>
225
+
<informalexample>
226
+
<screen>
227
+
<![CDATA[
228
+
extension=oci8.so
229
+
]]>
230
+
</screen>
231
+
</informalexample>
232
+
</para>
233
+
<para>
234
+
Make sure the &php.ini;
235
+
directive <link linkend="ini.extension-dir">extension_dir</link> is
236
+
set to the directory that <filename>oci8.so</filename> was installed
237
+
in.
238
+
</para>
239
+
</listitem>
240
+
</itemizedlist>
241
+
</para>
242
+
</section>
243
+
<section>
244
+
<title>Installing OCI8 as a Shared Extension when Building PHP</title>
245
+
<para>
246
+
If you are building PHP from source code, the
247
+
configuration <literal>shared</literal> option can be used to build OCI8 as a shared library
248
+
that can be dynamically loaded into PHP. Building a shared extension allows
249
+
OCI8 to be upgraded easily without impacting the rest of PHP.
250
+
</para>
251
+
<para>
252
+
Configure OCI8 using one of the following configure options.
253
+
</para>
254
+
<para>
255
+
<itemizedlist>
256
+
<listitem>
257
+
<para>
258
+
If using the free <link xmlns="http://docbook.org/ns/docbook"
259
+
xmlns:xlink="http://www.w3.org/1999/xlink"
260
+
xlink:href="&url.oracle.instant.client;">Oracle Instant
261
+
Client</link> libraries, then do:
262
+
</para>
263
+
<para>
264
+
<informalexample>
265
+
<screen>
266
+
<![CDATA[
267
+
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
268
+
]]>
269
+
</screen>
270
+
</informalexample>
271
+
</para>
272
+
<para>
273
+
If Instant Client 12.2 (or earlier) is installed from ZIP files, make sure to create
274
+
the library symbolic link first, for example <literal>ln -s
275
+
libclntsh.so.12.1 libclntsh.so</literal>.
276
+
</para>
277
+
<para>
278
+
If using an RPM-based installation of Oracle Instant Client, the
279
+
configure line will look like this:
280
+
</para>
281
+
<para>
282
+
<informalexample>
283
+
<screen>
284
+
<![CDATA[
285
+
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
286
+
]]>
287
+
</screen>
288
+
</informalexample>
289
+
</para>
290
+
<para>
291
+
For example, <option role="configure">--with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib</option>
292
+
</para>
293
+
</listitem>
294
+
<listitem>
295
+
<para>
296
+
If using an Oracle database or full Oracle Client installation then do:
297
+
</para>
298
+
<para>
299
+
<informalexample>
300
+
<screen>
301
+
<![CDATA[
302
+
./configure --with-oci8=shared,$ORACLE_HOME
303
+
]]>
304
+
</screen>
305
+
</informalexample>
306
+
</para>
307
+
<para>
308
+
Make sure the web server user
309
+
(<literal>nobody</literal>, <literal>www</literal>) has access to
310
+
the libraries, initialization files
311
+
and <filename>tnsnames.ora</filename> (if used) under
312
+
the <literal>$ORACLE_HOME</literal> directory. With Oracle
313
+
10<emphasis>g</emphasis>R2, you may need to run
314
+
the <filename>$ORACLE_HOME/install/changePerm.sh</filename>
315
+
utility to give directory access.
316
+
</para>
317
+
</listitem>
318
+
</itemizedlist>
319
+
</para>
320
+
<para>
321
+
After configuration, follow the usual PHP building procedure,
322
+
e.g. <emphasis>make install</emphasis>. The OCI8 shared extension
323
+
<filename>oci8.so</filename> library will be created. It may need
324
+
to be manually moved to the PHP extension directory, specified by
325
+
the <link linkend="ini.extension-dir">extension_dir</link> option in
326
+
your &php.ini; file.
327
+
</para>
328
+
<para>
329
+
To complete installation of OCI8, edit &php.ini; and add the line:
330
+
</para>
331
+
<para>
332
+
<informalexample>
333
+
<screen>
334
+
<![CDATA[
335
+
extension=oci8.so
336
+
]]>
337
+
</screen>
338
+
</informalexample>
339
+
</para>
340
+
</section>
341
+
<section>
342
+
<title>Installing OCI8 as a Statically Compiled Extension when Building PHP</title>
343
+
<para>
344
+
If you are building PHP from source code, you can configure PHP to include
345
+
OCI8 as a static extension using one of the following configure options.
346
+
</para>
347
+
<para>
348
+
<itemizedlist>
349
+
<listitem>
350
+
<para>
351
+
If using Oracle Instant Client, then do:
352
+
</para>
353
+
<para>
354
+
<informalexample>
355
+
<screen>
356
+
<![CDATA[
357
+
./configure --with-oci8=instantclient,/path/to/instant/client/lib
358
+
]]>
359
+
</screen>
360
+
</informalexample>
361
+
</para>
362
+
</listitem>
363
+
<listitem>
364
+
<para>
365
+
If using an Oracle database or full Oracle Client installation then do:
366
+
</para>
367
+
<para>
368
+
<informalexample>
369
+
<screen>
370
+
<![CDATA[
371
+
./configure --with-oci8=$ORACLE_HOME
372
+
]]>
373
+
</screen>
374
+
</informalexample>
375
+
</para>
376
+
</listitem>
377
+
</itemizedlist>
378
+
</para>
379
+
<para>
380
+
After configuration, follow the usual PHP building procedure,
381
+
e.g. <emphasis>make install</emphasis>. After successful
382
+
compilation, you do not need to add <filename>oci8.so</filename> to
383
+
&php.ini;. No additional build steps are required.
384
+
</para>
385
+
</section>
386
+
<section>
387
+
<title>Installing OCI8 on Windows</title>
388
+
<para xmlns:xlink="http://www.w3.org/1999/xlink">
389
+
The OCI8 extension can be added to an existing PHP installation by using the
390
+
DLLs from <link xlink:href="&url.pecl.package;oci8">PECL</link> repository or
391
+
the libraries in your PHP installation's <literal>ext</literal> directory.
392
+
</para>
393
+
<para>
394
+
With Oracle 12<emphasis>c</emphasis> (or later) libraries, uncomment one of
395
+
the &php.ini; lines <literal>extension=php_oci8_12c.dll</literal>
396
+
or <literal>extension=php_oci8_11g.dll</literal>
397
+
or <literal>extension=php_oci8.dll</literal>. Only one of these DLLs may be
398
+
enabled at a time. DLLs with higher versions may contain more
399
+
functionality. Not all DLLs may be available for all versions of PHP. Make
400
+
sure <link linkend="ini.extension-dir">extension_dir</link> is set to the
401
+
directory containing the PHP extension DLLs.
402
+
</para>
403
+
<para>
404
+
If using Instant Client, set the system <envar>PATH</envar>
405
+
environment variable to the Oracle library directory.
406
+
</para>
407
+
</section>
408
+
<section>
409
+
<title>Setting the Oracle Environment</title>
410
+
<para>
411
+
Before using this extension, make sure that the Oracle environment
412
+
variables are properly set for the web daemon user. If your web
413
+
server is automatically started at boot time then make sure that the
414
+
boot-time environment is also configured correctly.
415
+
</para>
416
+
<note>
417
+
<para>
418
+
Do not set Oracle environment variables
419
+
using <function>putenv</function> in a PHP script because Oracle
420
+
libraries may be loaded and initialized before your script
421
+
runs. Variables set with <function>putenv</function> may then cause
422
+
conflicts, crashes, or unpredictable behavior. Some functions may
423
+
work but others might give subtle errors. The variables should be
424
+
set up <emphasis>before</emphasis> the web server is started.
425
+
</para>
426
+
</note>
427
+
<para>
428
+
On Red Hat Linux and variants, export variables at the end of
429
+
<filename>/etc/sysconfig/httpd</filename>. Other systems with
430
+
Apache 2 may use an <filename>envvars</filename> script in the
431
+
Apache <filename>bin</filename> directory. A third option, the
432
+
Apache <literal>SetEnv</literal> directive
433
+
in <filename>httpd.conf</filename>, may work in some systems but is
434
+
known to be insufficient in others.
435
+
</para>
436
+
<para>
437
+
To check that environment variables are set correctly,
438
+
use <function>phpinfo</function> and check
439
+
the <emphasis>Environment</emphasis> (not the <emphasis>Apache
440
+
Environment</emphasis>) section contains the expected variables.
441
+
</para>
442
+
<para>
443
+
The variables that might be needed are included in the following
444
+
table. Refer to the Oracle documentation for more information on
445
+
all the available variables.
446
+
<table>
447
+
<title>Common Oracle Environment Variables</title>
448
+
<tgroup cols="2">
449
+
<thead>
450
+
<row>
451
+
<entry>Name</entry>
452
+
<entry>Purpose</entry>
453
+
</row>
454
+
</thead>
455
+
<tbody>
456
+
<row>
457
+
<entry>ORACLE_HOME</entry>
458
+
<entry>Contains the directory of the full Oracle Database
459
+
software. Do not set this when using Oracle Instant Client as
460
+
it is unnecessary and may cause installation problems.</entry>
461
+
</row>
462
+
<row>
463
+
<entry>ORACLE_SID</entry>
464
+
<entry>Contains the name of the database on the local machine to
465
+
be connected to. There is no need to set this if you using
466
+
Oracle Instant Client, or always pass the connection parameter
467
+
to <function>oci_connect</function>.</entry>
468
+
</row>
469
+
<row>
470
+
<entry>LD_LIBRARY_PATH</entry>
471
+
<entry>Set this (or its platform equivalent, such
472
+
as <literal>LIBPATH</literal>, or <literal>SHLIB_PATH</literal>) to the
473
+
location of the Oracle libraries, for
474
+
example <filename>$ORACLE_HOME/lib</filename>
475
+
or <filename>/usr/lib/oracle/18.5/client/lib</filename>. Note with Instant
476
+
Client ZIP files on Linux it is more reliable to
477
+
use <filename>ldconfig</filename> instead, see the Instant Client
478
+
installation instructions. With Instant Client 19 (or later) RPM
479
+
files, <literal>ldconfig</literal> is automatically run for you. Some
480
+
users use
481
+
<literal>LD_PRELOAD</literal> instead
482
+
of <literal>LD_LIBRARY_PATH</literal>.</entry>
483
+
</row>
484
+
<row>
485
+
<entry>NLS_LANG</entry>
486
+
<entry>This is the primary variable for setting the character
487
+
set and globalization information used by the Oracle
488
+
libraries.</entry>
489
+
</row>
490
+
<row>
491
+
<entry>ORA_SDTZ</entry>
492
+
<entry>Sets the Oracle session timezone.</entry>
493
+
</row>
494
+
<row>
495
+
<entry>TNS_ADMIN</entry>
496
+
<entry>Contains the directory where the Oracle Net Services configuration
497
+
files such as <filename>tnsnames.ora</filename>
498
+
and <filename>sqlnet.ora</filename> are kept. Not needed if
499
+
the <function>oci_connect</function> connection string uses the Easy
500
+
Connect naming syntax such as <literal>localhost/XE</literal>. Not needed
501
+
if the network configuration files are in one of the default locations
502
+
such
503
+
as <filename>/usr/lib/oracle/VERSION/client/lib/network/admin</filename>, <filename>$ORACLE_HOME/network/admin</filename>
504
+
or <filename>/etc</filename>.</entry>
505
+
</row>
506
+
</tbody>
507
+
</tgroup>
508
+
</table>
509
+
Less frequently used Oracle environment variables include
510
+
<literal>TWO_TASK</literal>, <literal>ORA_TZFILE</literal>, and the
511
+
various Oracle globalization settings
512
+
like <literal>NLS*</literal> and the <literal>ORA_NLS_*</literal>
513
+
variables.
514
+
</para>
515
+
</section>
516
+
<section>
517
+
<title>Troubleshooting</title>
518
+
<para>
519
+
The most common problem with installing OCI8 is not having the
520
+
Oracle environment correctly set. This typically appears as a
521
+
problem using <function>oci_connect</function>
522
+
or <function>oci_pconnect</function>. The error may be a PHP error
523
+
such as <emphasis>Call to undefined function
524
+
oci_connect()</emphasis>, an Oracle error such as ORA-12705, or even
525
+
an Apache crash. Check the Apache log files for startup errors and
526
+
see the sections above to resolve this problem.
527
+
</para>
528
+
<para>
529
+
While network errors like ORA-12154 or ORA-12514 indicate an Oracle
530
+
network naming or configuration issue, the root cause may be because
531
+
the PHP environment is incorrectly set up and Oracle libraries are
532
+
unable to locate the <filename>tnsnames.ora</filename> configuration
533
+
file.
534
+
</para>
535
+
<para>
536
+
On Windows, having multiple versions of Oracle on the one machine
537
+
can easily cause library clashes unless care is taken to make sure
538
+
PHP only uses the correct version of Oracle.
539
+
</para>
540
+
<para>
541
+
A utility to examine what libraries are being looked for and loaded
542
+
can help resolve missing or clashing library issues, particularly on
543
+
Windows.
16
544
</para>
17
545
<note>
546
+
<title>If the web server doesn't start or crashes at
547
+
startup</title>
18
548
<para>
19
-
Note that in OCI8 versions before 1.1 you have to use
20
-
<option role="configure">--with-oci8-instant-client</option> to configure
21
-
PHP with Oracle Instant Client.
549
+
Check that Apache is linked with the pthread library:
550
+
</para>
551
+
<para>
552
+
<informalexample>
553
+
<screen>
554
+
<![CDATA[
555
+
# ldd /www/apache/bin/httpd
556
+
libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
557
+
libm.so.6 => /lib/libm.so.6 (0x4002f000)
558
+
libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
559
+
libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
560
+
libc.so.6 => /lib/libc.so.6 (0x4007e000)
561
+
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
562
+
]]>
563
+
</screen>
564
+
</informalexample>
565
+
</para>
566
+
<para>
567
+
If the libpthread is not listed, then reinstall Apache:
568
+
</para>
569
+
<para>
570
+
<informalexample>
571
+
<screen>
572
+
<![CDATA[
573
+
# cd /usr/src/apache_1.3.xx
574
+
# make clean
575
+
# LIBS=-lpthread ./config.status
576
+
# make
577
+
# make install
578
+
]]>
579
+
</screen>
580
+
</informalexample>
581
+
</para>
582
+
<para>
583
+
Please note that on some systems like UnixWare, it is libthread
584
+
instead of libpthread. PHP and Apache have to be configured with
585
+
EXTRA_LIBS=-lthread.
22
586
</para>
23
587
</note>
24
588
</section>
25
589

590
+

591
+
</section> <!-- oci8.installation -->
26
592
<!-- Keep this comment at the end of the file
27
593
Local variables:
28
594
mode: sgml
29
595



Tools (Brazilian Portuguese Manual)