reference/oci8/configure.xml
5e41012cfdf8f2eff5fa56de446c7656afac536c
...
...
@@ -12,140 +12,133 @@
12
12
section before configuring OCI8.
13
13
</para>
14
14
<para>
15
-
To enable the OCI8 extension, configure PHP with the option
16
-
<option role="configure">--with-oci8</option>.
17
-
</para>
18
-
<para>
19
15
Before starting the web server, OCI8 typically requires several
20
16
Oracle environment variables (see below) to locate libraries, point
21
17
to configuration files, and set some basic properties such as the
22
-
character set used by Oracle libraries. The variables should be set
18
+
character set used by Oracle libraries. The variables must be set
23
19
<emphasis>before</emphasis> any PHP process starts.
24
20
</para>
25
21
<para>
26
-
PHP should be run with the same, or more recent, major version of
22
+
The PHP binary must link with the same, or more recent, major version of
27
23
Oracle libraries as it was configured with. For example, if you build
28
-
OCI8 with Oracle 11.2 libraries, then PHP should also be deployed
29
-
and run with Oracle 11.2 libraries.
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.
30
27
</para>
31
28
</section>
32
29
<section>
33
-
<title>Installing OCI8 as a Shared Extension</title>
34
-
<para>
35
-
The configuration <literal>shared</literal> option
36
-
builds OCI8 as a shared library that can be dynamically loaded into
37
-
PHP. Building a shared extension allows OCI8 to be upgraded easily
38
-
without impacting the rest of PHP.
39
-
</para>
40
-
<para>
41
-
Configure OCI8 using one of the following configure options.
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.
42
34
</para>
43
35
<para>
44
36
<itemizedlist>
45
37
<listitem>
46
38
<para>
47
-
If using Oracle Instant Client, then do:
39
+
If you are behind a firewall, set PEAR's proxy, for example:
48
40
</para>
49
41
<para>
50
42
<informalexample>
51
43
<screen>
52
44
<![CDATA[
53
-
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
45
+
pear config-set http_proxy http://my-proxy.example.com:80/
54
46
]]>
55
47
</screen>
56
48
</informalexample>
57
49
</para>
50
+
</listitem>
51
+
<listitem>
58
52
<para>
59
-
If Instant Client is installed from ZIP files, make sure to create
60
-
the library symbolic link, for example <literal>ln -s
61
-
libclntsh.so.11.1 libclntsh.so</literal>.
62
-
</para>
63
-
<para>
64
-
If using an RPM-based installation of Oracle Instant Client, the
65
-
configure line will look like this:
53
+
Run
66
54
</para>
67
55
<para>
68
56
<informalexample>
69
57
<screen>
70
58
<![CDATA[
71
-
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
59
+
pecl install oci8
72
60
]]>
73
61
</screen>
74
62
</informalexample>
75
63
</para>
76
64
<para>
77
-
For example, <option role="configure">--with-oci8=shared,instantclient,/usr/lib/oracle/11.2/client/lib</option>.
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>.
78
72
</para>
79
73
<para>
80
-
Note that Oracle Instant Client support first appeared in PHP
81
-
4.3.11 and 5.0.4 and originally used the option
82
-
<option role="configure">--with-oci8-instant-client</option> to
83
-
configure PHP.
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>
84
79
</para>
85
80
</listitem>
86
81
<listitem>
87
82
<para>
88
-
If using an Oracle database or full Oracle Client installation then do:
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:
89
87
</para>
90
-
<para>
91
-
<informalexample>
92
-
<screen>
88
+
<para>
89
+
<informalexample>
90
+
<screen>
93
91
<![CDATA[
94
-
./configure --with-oci8=shared,$ORACLE_HOME
92
+
$ export PHP_DTRACE=yes
93
+
$ pecl install oci8
95
94
]]>
96
-
</screen>
97
-
</informalexample>
95
+
</screen>
96
+
</informalexample>
97
+
</para>
98
+
</listitem>
99
+
<listitem>
100
+
<para>
101
+
Edit your &php.ini; file and add the line:
98
102
</para>
99
103
<para>
100
-
Make sure the web server user
101
-
(<literal>nobody</literal>, <literal>www</literal>) has access to
102
-
the libraries, initialization files
103
-
and <filename>tnsnames.ora</filename> (if used) under
104
-
the <literal>$ORACLE_HOME</literal> directory. With Oracle
105
-
10gR2, you may need to run
106
-
the <filename>$ORACLE_HOME/install/changePerm.sh</filename>
107
-
utility to give directory access.
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.
108
117
</para>
109
118
</listitem>
110
119
</itemizedlist>
111
120
</para>
112
-
<para>
113
-
After configuration, follow the usual PHP building procedure,
114
-
e.g. <emphasis>make install</emphasis>. The OCI8 shared extension
115
-
<filename>oci8.so</filename> library will be created. It may need
116
-
to be manually moved to the PHP extension directory, specified by
117
-
the <link linkend="ini.extension-dir">extension_dir</link> option in
118
-
your &php.ini; file.
119
-
</para>
120
-
<para>
121
-
To complete installation of OCI8, edit &php.ini; and add the line:
122
-
</para>
123
-
<para>
124
-
<informalexample>
125
-
<screen>
126
-
<![CDATA[
127
-
extension=oci8.so
128
-
]]>
129
-
</screen>
130
-
</informalexample>
131
-
</para>
132
121
</section>
133
122
<section>
134
-
<title>Installing OCI8 as a Statically Compiled Extension</title>
135
-
<para>
136
-
Configure OCI8 using one of the following configure options.
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>.
137
129
</para>
138
130
<para>
139
131
<itemizedlist>
140
132
<listitem>
141
133
<para>
142
-
If using Oracle Instant Client, then do:
134
+
Extract the package:
143
135
</para>
144
136
<para>
145
137
<informalexample>
146
138
<screen>
147
139
<![CDATA[
148
-
./configure --with-oci8=instantclient,/path/to/instant/client/lib
140
+
tar -zxf oci8-3.0.0.tgz
141
+
cd oci8-3.0.0
149
142
]]>
150
143
</screen>
151
144
</informalexample>
...
...
@@ -153,52 +146,40 @@ extension=oci8.so
153
146
</listitem>
154
147
<listitem>
155
148
<para>
156
-
If using an Oracle database or full Oracle Client installation then do:
149
+
Prepare the package:
157
150
</para>
158
151
<para>
159
152
<informalexample>
160
153
<screen>
161
154
<![CDATA[
162
-
./configure --with-oci8=$ORACLE_HOME
155
+
phpize
163
156
]]>
164
157
</screen>
165
158
</informalexample>
166
159
</para>
167
160
</listitem>
168
-
</itemizedlist>
169
-
</para>
170
-
<para>
171
-
After configuration, follow the usual PHP building procedure,
172
-
e.g. <emphasis>make install</emphasis>. After successful
173
-
compilation, you do not need to add <filename>oci8.so</filename> to
174
-
&php.ini;. No additional build steps are required.
175
-
</para>
176
-
</section>
177
-
<section>
178
-
<title>Installing OCI8 from PECL</title>
179
-
<para xmlns:xlink="http://www.w3.org/1999/xlink">
180
-
The OCI8 extension can be added to an existing PHP installation
181
-
either automatically or manually
182
-
from <link xlink:href="&url.pecl;">&url.pecl;</link>.
183
-

184
-
&pecl.info;
185
-
<link xlink:href="&url.pecl.package;oci8">&url.pecl.package;oci8</link>.
186
-

187
-
</para>
188
-
<para>
189
-
For an automated install follow these steps:
190
-
</para>
191
-
<para>
192
-
<itemizedlist>
193
161
<listitem>
194
162
<para>
195
-
If you are behind a firewall, set PEAR's proxy, for example:
163
+
Configure the package, either
164
+
using <literal>$ORACLE_HOME</literal> or Instant Client
196
165
</para>
197
166
<para>
198
167
<informalexample>
199
168
<screen>
200
169
<![CDATA[
201
-
pear config-set http_proxy http://my-proxy.example.com:80/
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
202
183
]]>
203
184
</screen>
204
185
</informalexample>
...
...
@@ -206,86 +187,174 @@ pear config-set http_proxy http://my-proxy.example.com:80/
206
187
</listitem>
207
188
<listitem>
208
189
<para>
209
-
Run
190
+
Install the package:
210
191
</para>
211
192
<para>
212
193
<informalexample>
213
194
<screen>
214
195
<![CDATA[
215
-
pecl install oci8
196
+
make install
216
197
]]>
217
198
</screen>
218
199
</informalexample>
219
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>
220
210
<para>
221
-
When prompted, enter either the value of <literal>$ORACLE_HOME</literal>, or
222
-
<literal>instantclient,/path/to/instant/client/lib</literal>.
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>
223
232
</para>
224
233
<para>
225
-
Note: Do not enter the variable <literal>$ORACLE_HOME</literal>
226
-
because it will not be expanded. Instead, enter the actual path
227
-
of the Oracle home directory.
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.
228
238
</para>
229
239
</listitem>
230
240
</itemizedlist>
231
241
</para>
242
+
</section>
243
+
<section>
244
+
<title>Installing OCI8 as a Shared Extension when Building PHP</title>
232
245
<para>
233
-
For a manual install, download the PECL OCI8 package,
234
-
e.g. <filename>oci8-1.3.5.tgz</filename>.
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.
235
253
</para>
236
254
<para>
237
255
<itemizedlist>
238
256
<listitem>
239
257
<para>
240
-
Extract the package:
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:
241
262
</para>
242
263
<para>
243
264
<informalexample>
244
265
<screen>
245
266
<![CDATA[
246
-
tar -zxf oci8-1.3.5.tgz
247
-
cd oci8-1.3.5
267
+
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
248
268
]]>
249
269
</screen>
250
270
</informalexample>
251
271
</para>
252
-
</listitem>
253
-
<listitem>
254
272
<para>
255
-
Prepare the package:
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:
256
280
</para>
257
281
<para>
258
282
<informalexample>
259
283
<screen>
260
284
<![CDATA[
261
-
phpize
285
+
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
262
286
]]>
263
287
</screen>
264
288
</informalexample>
265
289
</para>
290
+
<para>
291
+
For example, <option role="configure">--with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib</option>
292
+
</para>
266
293
</listitem>
267
294
<listitem>
268
295
<para>
269
-
Configure the package, either
270
-
using <literal>$ORACLE_HOME</literal> or Instant Client
296
+
If using an Oracle database or full Oracle Client installation then do:
271
297
</para>
272
298
<para>
273
299
<informalexample>
274
300
<screen>
275
301
<![CDATA[
276
-
./configure -with-oci8=shared,$ORACLE_HOME
302
+
./configure --with-oci8=shared,$ORACLE_HOME
277
303
]]>
278
304
</screen>
279
305
</informalexample>
280
306
</para>
281
307
<para>
282
-
or
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:
283
352
</para>
284
353
<para>
285
354
<informalexample>
286
355
<screen>
287
356
<![CDATA[
288
-
./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
357
+
./configure --with-oci8=instantclient,/path/to/instant/client/lib
289
358
]]>
290
359
</screen>
291
360
</informalexample>
...
...
@@ -293,13 +362,13 @@ phpize
293
362
</listitem>
294
363
<listitem>
295
364
<para>
296
-
Install the package:
365
+
If using an Oracle database or full Oracle Client installation then do:
297
366
</para>
298
367
<para>
299
368
<informalexample>
300
369
<screen>
301
370
<![CDATA[
302
-
make install
371
+
./configure --with-oci8=$ORACLE_HOME
303
372
]]>
304
373
</screen>
305
374
</informalexample>
...
...
@@ -308,39 +377,31 @@ make install
308
377
</itemizedlist>
309
378
</para>
310
379
<para>
311
-
After either an automatic or manual install, edit your &php.ini;
312
-
file and add the line:
313
-
</para>
314
-
<para>
315
-
<informalexample>
316
-
<screen>
317
-
<![CDATA[
318
-
extension=oci8.so
319
-
]]>
320
-
</screen>
321
-
</informalexample>
322
-
</para>
323
-
<para>
324
-
Make sure the &php.ini;
325
-
directive <link linkend="ini.extension-dir">extension_dir</link> is
326
-
set to the directory that <filename>oci8.so</filename> was installed
327
-
in.
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.
328
384
</para>
329
385
</section>
330
386
<section>
331
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>
332
393
<para>
333
-
On Windows, uncomment the &php.ini;
334
-
line <literal>extension=php_oci8.dll</literal> when using Oracle
335
-
10gR2 client libraries. Uncomment
336
-
<literal>extension=php_oci8_11g.dll</literal> when using Oracle 11g
337
-
client libraries. These two DLLs contain equivalent functionality
338
-
and only one may be enabled at a time. Make
339
-
sure <link linkend="ini.extension-dir">extension_dir</link> is set
340
-
to the directory containing the PHP extension DLLs.
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.
341
402
</para>
342
403
<para>
343
-
If using Instant Client, set the system <literal>PATH</literal>
404
+
If using Instant Client, set the system <envar>PATH</envar>
344
405
environment variable to the Oracle library directory.
345
406
</para>
346
407
</section>
...
...
@@ -381,7 +442,7 @@ extension=oci8.so
381
442
<para>
382
443
The variables that might be needed are included in the following
383
444
table. Refer to the Oracle documentation for more information on
384
-
all the variables.
445
+
all the available variables.
385
446
<table>
386
447
<title>Common Oracle Environment Variables</title>
387
448
<tgroup cols="2">
...
...
@@ -408,14 +469,17 @@ extension=oci8.so
408
469
<row>
409
470
<entry>LD_LIBRARY_PATH</entry>
410
471
<entry>Set this (or its platform equivalent, such
411
-
as <literal>DYLD_LIBRARY_PATH</literal>, <literal>LIBPATH</literal>,
412
-
or <literal>SHLIB_PATH</literal>) to the location of the Oracle
413
-
libraries, for example <filename>$ORACLE_HOME/lib</filename>
414
-
or <filename>/usr/lib/oracle/11.1/client/lib</filename>. This
415
-
variable is not needed if the libraries are located by a
416
-
different search mechanism, such as
417
-
with <filename>ldconfig</filename> or
418
-
with <literal>LD_PRELOAD</literal>.</entry>
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>
419
483
</row>
420
484
<row>
421
485
<entry>NLS_LANG</entry>
...
...
@@ -429,14 +493,14 @@ extension=oci8.so
429
493
</row>
430
494
<row>
431
495
<entry>TNS_ADMIN</entry>
432
-
<entry>Contains the directory where the Oracle Net Services
433
-
configuration files such as <filename>tnsnames.ora</filename>
496
+
<entry>Contains the directory where the Oracle Net Services configuration
497
+
files such as <filename>tnsnames.ora</filename>
434
498
and <filename>sqlnet.ora</filename> are kept. Not needed if
435
-
the <function>oci_connect</function> connection string uses the
436
-
Easy Connect naming syntax such
437
-
as <literal>localhost/XE</literal>. Not needed if the network
438
-
configuration files are in one of the default locations such
439
-
as <filename>$ORACLE_HOME/network/admin</filename>
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>
440
504
or <filename>/etc</filename>.</entry>
441
505
</row>
442
506
</tbody>
443
507



Tools (Chinese (Simplified) Manual)