1. Context

2 extensions exist allowing access to Oracle databases from PHP:

To use these extensions, you need to have the client library available.

It exists various ways to install this library, including using RPM, but it is not possible to properly handle the dependencies of the packages providing the extensions, so installation often results in an unusable configuration.

$ php -v
PHP Warning:  PHP Startup: Unable to load dynamic library 'oci8' (tried: /usr/lib64/php/modules/oci8 (/usr/lib64/php/modules/oci8: cannot open shared object file: No such file or directory), /usr/lib64/php/modules/oci8.so (libclntsh.so.21.1: cannot open shared object file: No such file or directory)) in Unknown on line 0

2. PHP and extension installation

For proper installation of PHP, simply follow the configuration wizard instructions.

Then you can install the Oracle extension

# yum install php-oci8

3. Client version

To know which version of the library is required, see the package description

$ yum info php-oci8
...
             : The extension is linked with Oracle client libraries 21.1
             : (Oracle Instant Client).  For details, see Oracle's note
             : "Oracle Client / Server Interoperability Support" (ID 207303.1).
             :
             : You must install libclntsh.so.21.1 to use this package, provided
             : in the database installation, or in the free Oracle Instant Client
             : available from Oracle.
...

For now, you need version 21.1 which allows to connect to databases version 11.2 and later.

4. RPM usage

The simple way is to install the library RPM provided by Oracle

Download it from Oracle Instant Client Downloads

Currently, you need the oracle-instantclient-basic-21.1.0.0.0-1.x86_64.rpm package

If not already present, you also need to install the libnsl package (dependency is not handled by the package)

This is enough and you can verify using:

$ php --ri oci8

oci8

OCI8 Support => enabled
OCI8 DTrace Support => enabled
OCI8 Version => 2.2.0
Oracle Run-time Client Library Version => 21.1.0.0.0
Oracle Compile-time Instant Client Version => 21.1

5. Manual installation

In a more complex case, e.g. if another version of the server is already installed on the same computer, or if you prefer to use an already installed library, you have to configure the library search path.

Example, installation of instantclient-basic-linux.x64-21.1.0.0.0.zip in /opt

# mkdir /opt/oracle; cd /opt/oracle
# unzip /tmp/instantclient-basic-linux.x64-21.1.0.0.0.zip

5.1 Settings default path

If you have a single version of the library in the system, the simplest way is to add the directory to the linker default search path, which will be used by all users and all services

# echo "/opt/oracle/instantclient_21_1" >/etc/ld.so.conf.d/oracle.conf
# ldconfig

5.2 User specific path

If you prefer to set the path for each user (the more complex case)

In command line

$ export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_1

For web servers, httpd (if you are still using mod_php) or php-fpm, you have to change the environment of the service by overriding the unit file

# systemctl edit php-fpm

by adding the lines

[Service]
Environment=LD_LIBRARY_PATH=/opt/oracle/instantclient_21_1

You may also need to set, in FPM pool configuration:

clear_env = no

6. Other

6.1 tnsnames.ora

If you still use this file for SID configuration (optional using EasyConnect), you have to add its path to httpd or php-fpm environment

# systemctl edit php-fpm

by adding the lines

[Service]
Environment=TNS_ADMIN=/path/to/network/admin

6.2 SELinux

When database access use the network, you have to explicitly allow it

# setsebool -P httpd_can_network_connect on

6.3 Web server

As for any new extension installation, don't forget to restart the web server (httpd)  or the FPM service (php-fpm).

7. Conclusion

For memory, I start building my PHP packages more than 15 years ago especially to have these extensions.

Their installation has never been easy, particularly because of the impossibility to properly manage the dependencies or to provide my own packages because of the Oracle's Licence.

With these installations notes, I hope this will be simpler, and clearer.

During PHP update, remind to check if the required library version has not changed.