Enabling Oracle as a Driver in Laravel Projects
It is doubtful that a Laravel project would not connect to a database. Laravel natively supports a wide variety of databases. Let's talk about how to extend the connection options to include Oracle databases.
One of the qualities that make Laravel such a unique framework is its versatility. If we analyze each of its existing functionalities, we will see that each one branches out into multiple options. This is the case with databases. Laravel natively allows us to connect to databases such as MariaDB, MySQL, PostgreSQL, SQLite, and SQL Server without additional drivers. Sweet 🍭!
However, since not all projects are the same, there may be cases where we need features that are not natively available, which we can access through either custom solutions or high-quality third-party packages. Thanks to all those artisans who share quality packages like the one we will see today.
Let's talk about enabling a driver that allows us to integrate an Oracle database into our project. For this, we will use the driver developed by @Arjay Angeles, which is an extension of Illuminate/Database, allowing for seamless integration with Eloquent, a mandatory requirement to take advantage of the full power of our precious ORM.
The following guide will show you how to enable the driver for Oracle databases in a Laravel project hosted on a Linux server.
It is challenging to document all possible scenarios since it will depend on the server's operating system, web server being used (Apache, Caddy, or nGinx), or PHP installation version and method (module or FPM). Since the number of variations is so extensive, we will limit this tutorial to a single take. We will use Linux as the operating system, CentOS as the distribution, nGinx as the web server, and PHP 8.1 as the module for FastCGI (PHP-FPM).
Prerequisites
This article assumes that you have basic knowledge of Linux and a functional server with Apache and PHP installed. You will also need to have a user with root permissions and
composerinstalled on your system.
php-oci8
php-oci8 is a native PHP library that can be easily added to our local servers. To enable php-oci8 on our machine, we proceed to install it using our package manager:
[root@MATRIX ~]# yum install php[xx]-oci8
Once the installation is complete, we need to restart the Apache service if you are running PHP as a web server module or PHP-FPM if you are using nginx. In our scenario, we will restart PHP-FPM:
[root@MATRIX ~]# systemctl restart php[xx]-fpm
Oracle Instant Client
Oracle Instant Client is a package that contains the libraries and drivers required for our machine to interact with the database server. We download the latest version of the client corresponding to our operating system from the official Oracle Instant Client page. In our scenario, we will install the Basic package of the client for Linux CentOS:
[root@MATRIX ~]# wget https://download.oracle.com/otn_software/linux/instantclient/219000/oracle-instantclient-basic-21.9.0.0.0-1.el8.x86_64.rpm
After the package is downloaded, we proceed with the installation:
[root@MATRIX ~]# yum install oracle-instantclient-basic-21.9.0.0.0-1.el8.x86_64.rpm
After completing the installation, we validate that our library is correctly published in the operating system. For this, we will check that the following file exists and contains the path of our client:
[root@MATRIX ~]# cat /etc/ld.so.conf.d/oracle.conf
/usr/lib/oracle/21/client64/lib
If the above command does not return a path, we must create or modify the file and add the path. To confirm the path, we execute the following command that should return the path to be placed in the previous file:
libocci.so. is the Oracle client library. The number 21 corresponds to the downloaded version value. Make sure to replace the version number based on the name of the file you downloaded from the official Oracle website.
[root@MATRIX ~]# find / -name libocci.so.21*
/usr/lib/oracle/21/client64/lib/libocci.so.21.1
To add the path to the file, we can run the following command, which will try to find the required library file and place the path in the configuration file:
[root@MATRIX ~]# find / -name libocci.so.21* | sed 's/\(.*\)\/.*$/\1\//' > /etc/ld.so.conf.d/oracle.conf
This fancy command executes a Regular Expression that takes the result of the find command search and transforms it into the required path. Thank you, chap-GPT, for the help with the REGEX.
After placing the path, we run the following command, which will create the required links so that all our libraries are available to the system:
[root@MATRIX ~]# ldconfig
With this, we have completed our installation. If everything is correctly installed, we can execute the following command without receiving any PHP errors or warnings:
[root@MATRIX ~]# php -v
Installing the Oracle Driver
With the dependencies installed, we can install the extension that will add our Oracle Driver to our Laravel installation.
We go to our project directory and install the package with composer as follows:
[root@MATRIX /var/www/my-awesome-laravel-project]# composer require yajra/laravel-oci8:[^xx]
After this, we proceed to configure the details of our Database in the environment file of our project with the editor of your preference:
DB_CONNECTION=oracle // Nuevo Driver
DB_HOST=192.168.1.50 // IP o Nombre de Dominio del Servidor
DB_SERVICE_NAME=dbgpro // Servicio Oracle
DB_DATABASE=DBNAME // Nombre del Esquema
DB_USERNAME=username // Usuario
DB_PASSWORD=$paS#AJDAD // Contraseña
We save and validate that the provided information is correct using our command line interface artisan:
[root@MATRIX ~]# php artisan db
After executing the command, you should receive client access to our database server; it means that the information entered in your configuration is correct and that you can create the Models of your Project to have all the power of Eloquent in your new project with Oracle.
Happy Hacking!