Habilitando Oracle como Driver en Proyectos Laravel
Es muy difícil que exista un proyecto Laravel en el cual no conectes a una base de datos. Laravel por defecto soporta una gran variedad de Bases de Datos de forma nativa. Hablemos de como extender las opciones de conexión para incluir Bases de Datos Oracle.
Una de las cualidades que hace de Laravel un framework tan especial es su versatilidad. Si analizamos cada una de las funcionalidades existentes, no daremos cuenta que cada una de ellas se ramifica en múltiples opciones. Este es el caso de las Base de Datos. Laravel, de manera nativa, dispone de drivers que nos permiten conectar a Base de Datos como MariaDB, MySQL, PostgreSQL, SQLite y SQL Server sin necesidad de instalar drivers adicionales. ¡Sweet 🍭!
Pero como no todos los proyectos son iguales, es muy seguro que existan otros casos en donde necesitemos de cualidades no existente, las cuales aunque no existen de manera nativa, podemos acceder a ellas de manera simple ya sea a través de soluciones personalizadas o a través paquetes de terceros de gran calidad. Gracias a todos esos artesanos que comparten paquetes de calidad como el que veremos el día de hoy.
Hablemos de como habilitar un driver que nos permita integrar una Base de Datos Oracle a nuestro proyecto. Para esto utilizaremos el driver desarrollado por @Arjay Angeles, el cual es una extensión de Illuminate/Database, lo que permite una integración transparente con Eloquent, requisito obligatorio para disponer de todo el poder de nuestro preciado ORM.
La siguiente guía mostrará como habilitar el driver para Base de Datos Oracle en un proyecto Laravel hospedado en un servidor Linux.
Es difícil documentar todos los posibles escenarios ya que dependerá del Sistema Operativo del servidor, Servidor Web que se esté utilizando (Apache, Caddy o nGinx) o versión y forma de instalación de PHP (Módulo o FPM). Ya que la cantidad de variantes es tan extensa, delimitaremos el siguiente tutorial a una sola variante. Utilizaremos Linux como Sistema Operativo, CentOS como distribución, nGinx como Servidor Web y PHP 8.1 como módulo para FastCGI (PHP-FPM).
Pre-requisitos
El siguiente artículo contempla que tienes conocimientos básicos de Linux, y que cuentas con un servidor funcional con Apache y PHP instalados. También será necesario disponer de un usuario con permisos root y composer en tu instalación.
php-oci8
php-oci8 es una librería nativa de PHP que puede ser añadida de manera simple en nuestros servidores locales. Para habilitar php-oci8 en nuestro equipo, procedemos a instalar con nuestro manejador de paquetes:
[root@MATRIX ~]# yum install php[xx]-oci8
Al completarse la instalación, debemos reiniciar el servicio de Apache si corres PHP como módulo del servidor web, o PHP-FPM si utilizas nGinx. En nuestro escenario reiniciaremos PHP-FPM:
[root@MATRIX ~]# systemctl restart php[xx]-fpm
Oracle Instant Client
Oracle Instant Client es un paquete que contiene las librerías y drivers requeridos para que nuestro equipo pueda interactuar con el servidor de Base de Datos. Procedemos a descargar la última versión del cliente correspondiente a nuestro Sistema Operativo desde la página oficial de Oracle Instant Client. En nuestro escenario instalaremos el paquete Básico del cliente para 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
Luego de que nuestro paquete sea descargado, procedemos con la instalación:
[root@MATRIX ~]# yum install oracle-instantclient-basic-21.9.0.0.0-1.el8.x86_64.rpm
Al completar la instalación procedemos a validar que nuestra librería se encuentra publicada correctamente en el sistema operativo. Para esto, procederemos a revisar que el siguiente archivo exista y contenga la ruta de nuestro cliente:
[root@MATRIX ~]# cat /etc/ld.so.conf.d/oracle.conf
/usr/lib/oracle/21/client64/lib
Si el comando anterior no retorna una ruta, debemos proceder a crear o modificar el archivo y añadir la ruta de lugar. Para confirmar la ruta, ejecutemos el siguiente comando que nos deberá retornar la ruta a colocar en el arhivo anterior:
libocci.so. es la librería del cliente Oracle. El número 21 corresponde al valor de la versión descargada. Asegura de reemplazar el número de versión basado en el nombre del archivo que descargaste desde la página oficial de Oracle.
[root@MATRIX ~]# find / -name libocci.so.21*
/usr/lib/oracle/21/client64/lib/libocci.so.21.1
Para añadir la ruta al archivo, podemos ejecutar el siguiente comando, el cuál intentará encontrar el archivo de librería requerido, y colocará la ruta en el archivo de configuración:
[root@MATRIX ~]# find / -name libocci.so.21* | sed 's/\(.*\)\/.*$/\1\//' > /etc/ld.so.conf.d/oracle.conf
Este comando fancy posee ejecuta un Regular Expression que toma el resultado de la búsqueda del comando find y la transforma en la ruta requerida. Thank you chap-GPT por la ayuda en el REGEX.
Luego de haber colocado la ruta de lugar, procedemos a ejecutar el siguiente comando, el cual creará los enlaces requeridos para que todas nuestras librerías se encuentren disponibles para el sistema:
[root@MATRIX ~]# ldconfig
Con esto hemos completado nuestra instalación. Si todo se encuentra correctamente instalado podremos ejecutar el siguiente comando sin recibir ningún error o advertencia de PHP:
[root@MATRIX ~]# php -v
Instalando el Driver para Oracle
Ya con las dependencias instaladas, podemos proceder a instalar la extensión que añadirá nuestro Driver de Oracle a nuestra instalación de Laravel.
Procedemos a dirigirnos a nuestro directorio del proyecto, e instalamos el paquete con composer de la siguiente forma:
[root@MATRIX /var/www/my-awesome-laravel-project]# composer require yajra/laravel-oci8:[^xx]
Luego de esto procedemos a configurar los detalles de nuestra Base de Datos en el archivo de ambiente de nuestro proyecto con el editor de tu preferencia:
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
Procedemos a guardar y validamos que la información suministrada es correcta utilizando nuestra interface de línea de comandos artisan:
[root@MATRIX ~]# php artisan db
Si accedemos al cliente de nuestro servidor de Base de Datos al ejecutar el comando anterior, significa que la información colocada en tu configuración es correcta y que puedes crear los Modelos de tu Proyecto para disponer de todo el poder de Eloquent en tu nuevo proyecto junto a Oracle.
Happy Hacking!