PECL Install Prompts Explained, With Particular Reference to OCI8
By cj on Mar 19, 2009
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:
- Enter 1 to update the first (and only) setting.
- 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.
- You will get reprompted 1-1, 'all', 'abort', or Enter to continue. As it says, press Enter to continue.
- 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.
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 oci8This 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.tgzSince 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' failedBut, 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: 220060519After 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:
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.iniMy 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-20060613If 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.soYou can check that the extension is installed with:
$ php --ri oci8 oci8 OCI8 Support => enabled Version => 1.3.4 Revision => $Revision: 1.2220.127.116.11.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 => OffAlso a "pecl list" command will also show the extension:
INSTALLED PACKAGES, CHANNEL PECL.PHP.NET: ========================================= PACKAGE VERSION STATE oci8 1.3.4 stableRemember 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