PECL Install Prompts Explained, With Particular Reference to OCI8

The short version of the article:

To install the PHP OCI8 extension from the PECL repository do:

$ pecl install oci8
downloading oci8-1.3.4.tgz ...
Starting to download oci8-1.3.4.tgz (134,240 bytes)
....done: 134,240 bytes
10 source files, building
running: phpize
Configuring for:
PHP Api Version:         20041225
Zend Module Api No:      20060613
Zend Extension Api No:   220060519
 1. Please provide the path to the ORACLE_HOME directory. 
      Use 'instantclient,/path/to/instant/client/lib' if you're compiling with 
      Oracle Instant Client : autodetect

1-1, 'all', 'abort', or Enter to continue:

At this stage:

  1. Enter 1 to update the first (and only) setting.
  2. Enter the full path of your ORACLE_HOME or enter the string "instantclient,/path/to/instant/client/libs" without quotes. Do not put the string $ORACLE_HOME or any other environment variable name, because the pecl installer doesn't expand variables.
  3. You will get reprompted 1-1, 'all', 'abort', or Enter to continue. As it says, press Enter to continue.
  4. Edit php.ini and add "extension=oci8.so" if not already done by the installer. Make sure extension_dir includes the directory containing oci8.so.
It's not immediately obvious from first glance that the very first prompt 1-1, 'all', 'abort', or Enter to continue isn't asking for an ORACLE_HOME value right there and then, but is letting you choose to be asked to change that value.

This is part of PEARs (the system used by PECL) methodology. Some installations might have multiple values with defaults. The installer will let you change any or all of the values, or just accept them all and continue. Versions of PEAR prior to PEAR 1.5 prompted for option values directly, which was easier. (Update: Helgi Þormar Þorbjörnsson says that PEAR 1.8 will revert to direct prompting for single option installs; this PEAR release will appear circa the PHP 5.3 time-frame).

The long version of the article:

The PECL repository hosts many PHP extensions that are easily added to PHP.

Some extensions like OCI8 are included in both the PHP distributions and available as PECL packages. Check which code base is most recent before changing. This may require examining release dates or looking at the code itself.

One example where PECL is more recent is the latest OCI8 1.3 release. This is in PHP 5.3 by default but I recommend using it with PHP 5.2. This is easily done by downloading it from PECL and following these instructions.

The fundamental installation command is:

pecl install oci8
This will pull the latest version of OCI8 from pecl.net and install it on your existing PHP.

In my case, to connect to the PECL repository, I first need to configure a proxy for the PEAR and PECL environments:

pear config-set http_proxy http://myproxy.us.oracle.com:80/
Use pear config-show to list all PEAR settings you can change.

If you have manually downloaded the OCI8 extension from http://pecl.php.net/package/oci8 you could alternatively install with:

pecl install oci8-1.3.4.tgz
Since PECL packages are compressed, PHP needs to have the ZLIB extension installed (--with-zlib) otherwise installation fails with:
The extension 'zlib' couldn't be found.
Please make sure your version of PHP was built with 'zlib' support.
PHP should not have been configured with --enable-sigchild. (This option has never been needed where PHP and DB are on different machines, and I'm no longer suggesting it automatically when they are on the same machine. Use it only if you see defunct Oracle server process) With this option, pecl can receive incorrect return codes from subprocesses and install typically fails with:
ERROR: `phpize' failed
But, if all is well, pecl install downloads, does some pre-configuration checks and some setup:
10 source files, building
running: phpize
Configuring for:
PHP Api Version:         20041225
Zend Module Api No:      20060613
Zend Extension Api No:   220060519
After this PECL lets the configuration be customized:
 1. Please provide the path to the ORACLE_HOME directory. 
     Use 'instantclient,/path/to/instant/client/lib' if you're compiling with 
     Oracle Instant Client : autodetect

1-1, 'all', 'abort', or Enter to continue:
This just says that there is one option you can set, and the current value is 'autodetect'. If you want to change that option enter "1", otherwise press Enter to continue the installation.

Versions of the underlying PEAR system prior to 1.5 just prompted directly for the option value, which was easier to understand for extensions with single options. The version of PEAR included with PHP depends on the release date, not the PHP version. For example, by default PHP 5.1.6 has PEAR 1.4.9, but the more recently released PHP 4.4.9 has PEAR 1.5.

Enter 1 and the prompt will be displayed for real:

Please provide the path to the ORACLE_HOME directory. 
  Use 'instantclient,/path/to/instant/client/lib' if you're compiling with 
  Oracle Instant Client [autodetect] : 
The values you enter here are the same as used with --with-oci8 for a PHP build, see my earlier post The PHP "./configure --with-oci8" Option in Detail.

A PECL install is always built shared, even if not explicitly requested, so there are three effective choices for the pecl prompt:

  1. autodetect
  2. /path/to/oracle/home
  3. instantclient,/path/to/instant/client/lib
You do not need to type --with-oci8. Do not put the text $ORACLE_HOME or any other environment variable name because the pecl installer doesn't expand variables.

The pecl "autodetect" value is the same as doing "--with-oci8" without any arguments: OCI8 will use the value of your $ORACLE_HOME environment variable. OCI8 1.3.5 will additionally notice if ORACLE_HOME isn't set, and will look for a default Oracle Instant Client install.

For this example, I entered /usr/lib/oracle/xe/app/oracle/product/10.2.0/server, the path for the free version of the Oracle database.

The installer will re-prompt, allowing you to review your change:

 1. Please provide the path to the ORACLE_HOME directory. 
     Use 'instantclient,/path/to/instant/client/lib' if you're compiling with 
     Oracle Instant Client : /usr/lib/oracle/xe/app/oracle/product/10.2.0/server

1-1, 'all', 'abort', or Enter to continue:
Press Enter, and pecl will build the OCI8 shared library and attempt to update your php.ini. Depending on your PEAR "config-set verbose" level you, might see more or less output. With the default value of 1, I get:
building in /var/tmp/pear-build-cjones/oci8-1.3.4
running: /tmp/pear/temp/oci8/configure --with-oci8
[...]
Build process completed successfully
Installing '/home/cjones/php/lib/php/extensions/debug-non-zts-20060613/oci8.so'
install ok: channel://pecl.php.net/oci8-1.3.4
configuration option "php_ini" is not set to php.ini location
You should add "extension=oci8.so" to php.ini
My PHP is in a local directory; yours will be elsewhere.

Review php.ini and add "extension=oci8.so" if the installer hasn't done so. Make sure extension_dir includes the directory where oci8.so was installed, because the installer doesn't change this option. In my example, I need to add make sure these lines were in php.ini:

extension=oci8.so
extension_dir=/home/cjones/php/lib/php/extensions/debug-non-zts-20060613
If I was using PHP 5.3, I could have done it in one line:
extension=/home/cjones/php/lib/php/extensions/debug-non-zts-20060613/oci8.so
You can check that the extension is installed with:
$ php --ri oci8

oci8

OCI8 Support => enabled
Version => 1.3.4
Revision => $Revision: 1.269.2.16.2.38.2.20 $
Active Persistent Connections => 0
Active Connections => 0
Compile-time ORACLE_HOME =>  
Libraries Used =>  
Temporary Lob support => enabled
Collections support => enabled

Directive => Local Value => Master Value
oci8.max_persistent => -1 => -1
oci8.persistent_timeout => -1 => -1
oci8.ping_interval => 60 => 60
oci8.privileged_connect => Off => Off
oci8.statement_cache_size => 20 => 20
oci8.default_prefetch => 100 => 100
oci8.old_oci_close_semantics => Off => Off
oci8.connection_class => no value => no value
oci8.events => Off => Off
Also a "pecl list" command will also show the extension:
INSTALLED PACKAGES, CHANNEL PECL.PHP.NET:
=========================================
PACKAGE VERSION STATE
oci8    1.3.4   stable
Remember to set LD_LIBRARY_PATH and ORACLE_HOME (if not using Oracle Instant Client) before running PHP or restarting your web server. See installation hints in the Underground PHP and Oracle Manual.

To uninstall, simply revert your changes from php.ini, and do:

pecl uninstall oci8
Comments:

Post a Comment:
Comments are closed for this entry.
About

Tourists looking out over an Opal mine
I'm a Product Manager in Server Technologies, working on scripting languages and developer-access.
Email: christopher.jones@oracle.com
Twitter: http://twitter.com/ghrd
Book: Free PHP Oracle book
Download: PHP Linux RPMs with the OCI8 extension
Links: OTN PHP Developer Center

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today