reference/oci8/configure.xml
5e41012cfdf8f2eff5fa56de446c7656afac536c
...
...
@@ -12,10 +12,6 @@
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
...
...
@@ -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



Tools (French Manual)