reference/oci8/configure.xml
5e41012cfdf8f2eff5fa56de446c7656afac536c
...
...
@@ -11,10 +11,6 @@
11
11
previous <link linkend="oci8.requirements">Requirements</link>
12
12
section before configuring OCI8.
13
13
</para>
14
-
<para>
15
-
To enable the OCI8 extension, configure PHP with the option
16
-
<option role="configure">--with-oci8</option>.
17
-
</para>
18
14
<para>
19
15
Before starting the web server, OCI8 typically requires several
20
16
Oracle environment variables (see below) to locate libraries, point
...
...
@@ -25,131 +21,124 @@
25
21
<para>
26
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. PHP applications can connect to other
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
30
26
versions of Oracle Database, since Oracle has client-server cross-version compatibility.
31
27
</para>
32
28
</section>
33
29
<section>
34
-
<title>Installing OCI8 as a Shared Extension</title>
35
-
<para>
36
-
The configuration <literal>shared</literal> option
37
-
builds OCI8 as a shared library that can be dynamically loaded into
38
-
PHP. Building a shared extension allows OCI8 to be upgraded easily
39
-
without impacting the rest of PHP.
40
-
</para>
41
-
<para>
42
-
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.
43
34
</para>
44
35
<para>
45
36
<itemizedlist>
46
37
<listitem>
47
38
<para>
48
-
If using the free <link xmlns="http://docbook.org/ns/docbook"
49
-
xmlns:xlink="http://www.w3.org/1999/xlink"
50
-
xlink:href="&url.oracle.instant.client;">Oracle Instant
51
-
Client</link> libraries, then do:
39
+
If you are behind a firewall, set PEAR's proxy, for example:
52
40
</para>
53
41
<para>
54
42
<informalexample>
55
43
<screen>
56
44
<![CDATA[
57
-
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
45
+
pear config-set http_proxy http://my-proxy.example.com:80/
58
46
]]>
59
47
</screen>
60
48
</informalexample>
61
49
</para>
50
+
</listitem>
51
+
<listitem>
62
52
<para>
63
-
If Instant Client is installed from ZIP files, make sure to create
64
-
the library symbolic link first, for example <literal>ln -s
65
-
libclntsh.so.12.1 libclntsh.so</literal>.
66
-
</para>
67
-
<para>
68
-
If using an RPM-based installation of Oracle Instant Client, the
69
-
configure line will look like this:
53
+
Run
70
54
</para>
71
55
<para>
72
56
<informalexample>
73
57
<screen>
74
58
<![CDATA[
75
-
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
59
+
pecl install oci8
76
60
]]>
77
61
</screen>
78
62
</informalexample>
79
63
</para>
80
64
<para>
81
-
For example, <option role="configure">--with-oci8=shared,instantclient,/usr/lib/oracle/12.1/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>.
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>
82
79
</para>
80
+
</listitem>
81
+
<listitem>
83
82
<para>
84
-
Note that Oracle Instant Client support first appeared in PHP
85
-
4.3.11 and 5.0.4 and originally used the option
86
-
<option role="configure">--with-oci8-instant-client</option> to
87
-
configure PHP.
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:
88
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>
89
98
</listitem>
90
99
<listitem>
91
100
<para>
92
-
If using an Oracle database or full Oracle Client installation then do:
101
+
Edit your &php.ini; file and add the line:
93
102
</para>
94
103
<para>
95
-
<informalexample>
96
-
<screen>
97
-
<![CDATA[
98
-
./configure --with-oci8=shared,$ORACLE_HOME
104
+
<informalexample>
105
+
<screen>
106
+
<![CDATA[
107
+
extension=oci8.so
99
108
]]>
100
-
</screen>
101
-
</informalexample>
109
+
</screen>
110
+
</informalexample>
102
111
</para>
103
112
<para>
104
-
Make sure the web server user
105
-
(<literal>nobody</literal>, <literal>www</literal>) has access to
106
-
the libraries, initialization files
107
-
and <filename>tnsnames.ora</filename> (if used) under
108
-
the <literal>$ORACLE_HOME</literal> directory. With Oracle
109
-
10<emphasis>g</emphasis>R2, you may need to run
110
-
the <filename>$ORACLE_HOME/install/changePerm.sh</filename>
111
-
utility to give directory access.
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.
112
117
</para>
113
118
</listitem>
114
119
</itemizedlist>
115
120
</para>
116
-
<para>
117
-
After configuration, follow the usual PHP building procedure,
118
-
e.g. <emphasis>make install</emphasis>. The OCI8 shared extension
119
-
<filename>oci8.so</filename> library will be created. It may need
120
-
to be manually moved to the PHP extension directory, specified by
121
-
the <link linkend="ini.extension-dir">extension_dir</link> option in
122
-
your &php.ini; file.
123
-
</para>
124
-
<para>
125
-
To complete installation of OCI8, edit &php.ini; and add the line:
126
-
</para>
127
-
<para>
128
-
<informalexample>
129
-
<screen>
130
-
<![CDATA[
131
-
extension=oci8.so
132
-
]]>
133
-
</screen>
134
-
</informalexample>
135
-
</para>
136
121
</section>
137
122
<section>
138
-
<title>Installing OCI8 as a Statically Compiled Extension</title>
139
-
<para>
140
-
Configure PHP to include 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>.
141
129
</para>
142
130
<para>
143
131
<itemizedlist>
144
132
<listitem>
145
133
<para>
146
-
If using Oracle Instant Client, then do:
134
+
Extract the package:
147
135
</para>
148
136
<para>
149
137
<informalexample>
150
138
<screen>
151
139
<![CDATA[
152
-
./configure --with-oci8=instantclient,/path/to/instant/client/lib
140
+
tar -zxf oci8-3.0.0.tgz
141
+
cd oci8-3.0.0
153
142
]]>
154
143
</screen>
155
144
</informalexample>
...
...
@@ -157,48 +146,40 @@ extension=oci8.so
157
146
</listitem>
158
147
<listitem>
159
148
<para>
160
-
If using an Oracle database or full Oracle Client installation then do:
149
+
Prepare the package:
161
150
</para>
162
151
<para>
163
152
<informalexample>
164
153
<screen>
165
154
<![CDATA[
166
-
./configure --with-oci8=$ORACLE_HOME
155
+
phpize
167
156
]]>
168
157
</screen>
169
158
</informalexample>
170
159
</para>
171
160
</listitem>
172
-
</itemizedlist>
173
-
</para>
174
-
<para>
175
-
After configuration, follow the usual PHP building procedure,
176
-
e.g. <emphasis>make install</emphasis>. After successful
177
-
compilation, you do not need to add <filename>oci8.so</filename> to
178
-
&php.ini;. No additional build steps are required.
179
-
</para>
180
-
</section>
181
-
<section>
182
-
<title>Installing OCI8 from PECL</title>
183
-
<para xmlns:xlink="http://www.w3.org/1999/xlink">
184
-
The OCI8 extension can be added to an existing PHP installation
185
-
either automatically or manually
186
-
from <link xlink:href="&url.pecl.package;oci8">PECL</link>.
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>
220
203
<para>
221
-
When prompted, enter either the value of <literal>$ORACLE_HOME</literal>, or
222
-
<literal>instantclient,/path/to/instant/client/lib</literal>.
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:
223
209
</para>
224
210
<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.
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.
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>
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>
232
251
<para>
233
-
For a manual install when the <literal>pecl</literal> command is not
234
-
available, download the PECL OCI8 package, e.g. <filename>oci8-1.4.10.tgz</filename>.
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.4.10.tgz
247
-
cd oci8-1.4.10
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,43 +377,28 @@ 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
-
When using Oracle 10<emphasis>g</emphasis>R2 client libraries on
334
-
Windows, uncomment the &php.ini;
335
-
line <literal>extension=php_oci8.dll</literal>. When using Oracle
336
-
11<emphasis>g</emphasis>R2 or later client libraries, uncomment
337
-
<literal>extension=php_oci8_11g.dll</literal>
338
-
or <literal>extension=php_oci8.dll</literal>. With Oracle
339
-
12<emphasis>c</emphasis> libraries
340
-
use <literal>extension=php_oci8_12c.dll</literal>
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>
341
396
or <literal>extension=php_oci8_11g.dll</literal>
342
-
or <literal>extension=php_oci8.dll</literal>. Only one of these DLLs
343
-
may be enabled at a time. DLLs with higher versions may contain more
344
-
functionality. Not all DLLs may be available for all versions of
345
-
PHP. Make
346
-
sure <link linkend="ini.extension-dir">extension_dir</link> is set
347
-
to the directory containing the PHP extension DLLs.
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.
348
402
</para>
349
403
<para>
350
404
If using Instant Client, set the system <envar>PATH</envar>
...
...
@@ -415,14 +469,17 @@ extension=oci8.so
415
469
<row>
416
470
<entry>LD_LIBRARY_PATH</entry>
417
471
<entry>Set this (or its platform equivalent, such
418
-
as <literal>DYLD_LIBRARY_PATH</literal>, <literal>LIBPATH</literal>,
419
-
or <literal>SHLIB_PATH</literal>) to the location of the Oracle
420
-
libraries, for example <filename>$ORACLE_HOME/lib</filename>
421
-
or <filename>/usr/lib/oracle/11.1/client/lib</filename>. This
422
-
variable is not needed if the libraries are located by a
423
-
different search mechanism, such as
424
-
with <filename>ldconfig</filename> or
425
-
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>
426
483
</row>
427
484
<row>
428
485
<entry>NLS_LANG</entry>
...
...
@@ -436,14 +493,14 @@ extension=oci8.so
436
493
</row>
437
494
<row>
438
495
<entry>TNS_ADMIN</entry>
439
-
<entry>Contains the directory where the Oracle Net Services
440
-
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>
441
498
and <filename>sqlnet.ora</filename> are kept. Not needed if
442
-
the <function>oci_connect</function> connection string uses the
443
-
Easy Connect naming syntax such
444
-
as <literal>localhost/XE</literal>. Not needed if the network
445
-
configuration files are in one of the default locations such
446
-
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>
447
504
or <filename>/etc</filename>.</entry>
448
505
</row>
449
506
</tbody>
450
507



Translation status