Instalación de PHP y Oracle Instant Client para Linux y Windows

Por Christopher Jones
Publicado en enero 2014

Actualizado para PHP 5.4 y Oracle Database 11g Versión 2

La forma más sencilla de configurar PHP para acceder a una base de datos remota de Oracle es mediante bibliotecas de Instant Client de Oracle. En este artículo se describe cómo instalar PHP con la extensión OCI8 e Instant Client de Oracle en Windows y en Linux. En The Underground PHP and Oracle Manual (en inglés), de acceso gratuito, se explican otras opciones de instalación y se brindan detalles adicionales.

OCI8 es la extensión de PHP para establecer la conexión con Oracle Database. OCI8 es de código abierto y está incluida en PHP. Su nombre está formado por las iniciales de la API en C Oracle Call Interface (interfaz de llamada), incorporada en la versión 8 de Oracle Database. OCI8 se vincula con las librerías de cliente de Oracle, como Oracle Instant Client.

Oracle Instant Client es un conjunto gratuito de bibliotecas de fácil instalación que permiten que los programas se conecten con instancias de Oracle Database locales o remotas. Para usar Instant Client se necesita una base de datos existente; Instant Client no incluye base de datos. Por lo general la base de datos estará en otro equipo. Si la base de datos es local en general no se necesita Instant Client, aunque es conveniente y funciona, porque OCI8 puede usar directamente las bibliotecas de la base de datos.

Cuando se utiliza Instant Client 11g, OCI8 de PHP se conecta con todas las ediciones de las bases de datos de Oracle 9.2, 10.x, y 11.x.

Requisitos de software

Software

Notas

Oracle Instant Client

Descargue el paquete "Basic". Para Linux, también descargue el paquete "SDK" o "devel". Si tiene limitaciones de espacio, puede utilizar el paquete Basic Lite en lugar del Basic.

Apache HTTP Server

Versión 2.2

PHP

Versión 5.4

Habilitación de la extensión OCI8 de PHP en Windows

Los archivos binarios de Instant Client complementan los archivos binarios para Windows preintegrados en PHP.

1. Instale Apache descargando httpd-2.2.22-win32-x86-no_ssl.msi de httpd.apache.org/download.cgi

2. Haga doble clic en el archivo MSI para iniciar el asistente de instalación.

 

Instale "for All Users, on Port 80" ("para todos los usuarios, en el puerto 80"). Haga una instalación típica en la carpeta de destino predeterminada: C:\Program Files\Apache Software Foundation\Apache2.2.

3. Descargue el componente FastCGI mod_fcgid-2.3.6-win32-x86.zip de httpd.apache.org/download.cgi#mod_fcgid

4. Descomprímalo en el directorio donde está instalado Apache 2.2. El directorio C:\Program Files\Apache Software Foundation\Apache2.2\modules debería contener ahora los archivos mod_fcgid.so y mod_fcgid.pdb.

5. Edite el archivo C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf y agregue la línea:

LoadModule fcgid_module modules/mod_fcgid.so

6. En httpd.conf, localice la sección relativa a htdocs y agregue ExecCGI en Options:

<Directory "C:/Program Files/Apache Software Foundation/Apache2.2/htdocs">
...
Options Indexes FollowSymLinks ExecCGI
...
</Directory>
  
    

7. Instale PHP descargando el paquete zip "VC9 x86 Non Thread Safe" de PHP 5.4.0, php-5.4.0-nts-Win32-VC9-x86.zip, de windows.php.net/download.

8. En el Explorador de Windows, cree el directorio C:\php-5.4.0 y descomprima allí el paquete de PHP.

9. En C:\php-5.4.0, copie php.ini-development como php.ini

10. Edite el archivo php.ini y realice los siguientes cambios:

o Agregue una línea de zona horaria, como la siguiente:
date.timezone = America/<Los_Angeles
Use el nombre de su zona horaria local.

o Agregue la línea:
extension_dir = C:\php-5.4.0\ext
Este es el directorio que contiene las extensiones de PHP.

o Borre el punto y coma del principio de la línea:

extension=php_oci8_11g.dll

    

11. Edite el archivo C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf y agregue las siguientes líneas. Asegúrese de utilizar barras diagonales regulares "/" y no invertidas "\":

FcgidInitialEnv PHPRC "c:/php-5.4.0"
AddHandler fcgid-script .php
FcgidWrapper "c:/php-5.4.0/php-cgi.exe" .php

12. Descargue el paquete "Instant Client Package - Basic" para Windows de la página de Instant Client de la red OTN (Oracle Technology Network). Como PHP es una herramienta de 32 bits, use la versión de 32 bits de Instant Client.

Descomprima los archivos de Instant Client en C:\instantclient_11_2

13. Edite la configuración de entorno PATH de Windows y agregue C:\instantclient_11_2. Por ejemplo, en Windows XP, ingrese a Inicio -> Panel de control -> Sistema -> Opciones avanzadas -> Variables de entorno y edite PATH en la lista de variables del sistema.

Por lo general es necesario reiniciar Windows para que se establezca el nuevo entorno correctamente.

Configure las variables de entorno para lenguaje y globalización de Oracle que desee, tales como NLS_LANG. Si no se establecen valores específicos, se trabajará con un entorno local predeterminado. Consulte el capítulo sobre Globalización en The Underground PHP and Oracle Manual para obtener más información.

Elimine las especificaciones de las variables de Oracle tales como ORACLE_HOME y ORACLE_SID, que no son necesarias con Instant Client.

Si usted tiene otro software de Oracle en su equipo, en lugar de modificar el entorno de Windows cree una secuencia de código que configure los valores mencionados e inicie Apache. De lo contrario, probablemente se produzcan conflictos entre símbolos de las bibliotecas debido a diferencias entre versiones.

14. Reinicie Apache desde el Apache Monitor de la bandeja del sistema o desde la opción correspondiente del menú Inicio.

Habilitación de la extensión OCI8 de PHP en Linux

En Linux, por lo general PHP se compila manualmente porque la versión en paquete no suele estar actualizada. Sin embargo, si usted no desea volver a compilar PHP, puede acceder a paquetes RPM para Oracle Linux más actualizados sin soporte en oss.oracle.com, o bien mediante actualizaciones de la red Unbreakable Linux Network. Si desea trabajar en un entorno PHP con soporte, use Zend Server. Todos ellos tienen la extensión OCI8 preintegrada.

Para generar PHP y la extensión OCI8 a partir de código fuente:

1. Instale el servidor HTTP Apache y los paquetes de desarrollo, por ejemplo, con yum install httpd httpd-devel.

2. Descargue el código fuente de PHP 5.4 e instale PHP siguiendo las instrucciones del apartado Installation on Unix systems (Instalación en sistemas Unix) del manual de PHP (en inglés).

En esta etapa, no configure la extensión OCI8.

3. Descargue los paquetes Basic y SDK Instant Client de la página de Instant Clientde la red OTN. Pueden usarse el archivo zip o los paquetes RPM.

Instale los paquetes RPM como usuario root, por ejemplo:

rpm -Uvh oracle-instantclient11.2-basic-11.2.0.3.0-1.x86_64.rpm 
rpm -Uvh oracle-instantclient11.2-devel-11.2.0.3.0-1.x86_64.rpm 

El primer paquete RPM agrega las bibliotecas de Oracle en /usr/lib/oracle/11.2/client64/lib y el segundo crea encabezados en /usr/include/oracle/11.2/client64.

Si está usando los archivos zip, deberá descomprimir el paquete SDK en el mismo directorio que el paquete Basic y crear manualmente un enlace simbólico:

ln -s libclntsh.so.11.1 libclntsh.so

4. La extensión OCI8 más nueva de PECL es siempre la versión vigente. Aunque su actualización suele estar sincronizada con la del código fuente de PHP 5.4, a veces la versión de la extensión puede ser más nueva. La extensión de producción más reciente puede descargarse y agregarse a PHP de manera automática mediante:

pecl install oci8

Lo que da lugar a:
downloading oci8-1.4.7.tgz ...
Starting to download oci8-1.4.7.tgz (Unknown size)
.....done: 168,584 bytes
10 source files, building
running: phpize
Configuring for:
PHP Api Version:         20100412
Zend Module Api No:      20100525
Zend Extension Api No:   220100525
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] : 

    

Si usted cuenta con los RPM de Instant Client, presione la tecla Enter y PECL generará e instalará automáticamente una biblioteca compartida oci8.so. Si usted tiene los archivos zip de Instant Client, o desea que se use una versión particular de Instant Client, indique explícitamente la ruta apropiada después de "instantclient,":

instantclient,/usr/lib/oracle/11.2/client64/lib

    

Utilice una ruta absoluta y explícita ya que  PECL no expande las variables de entorno.

Si usted no cuenta con el programa pecl, puede descargar el paquete OCI8 a través de un navegador y luego instalarlo con las siguientes instrucciones:

tar -xzf oci8-1.4.7.tgz
cd oci8-1.4.7
phpize
./configure --with-oci8=instantclient,/usr/lib/oracle/11.2/client64/lib
make install

5. Edite el archivo php.ini y habilite la extensión OCI8 con la siguiente instrucción:

 
extension=oci8.so

También confirme que extension_dir indique el directorio en que se instaló el archivo oci8.so.

Agregue el directorio de Instant Client en /etc/ld.so.conf, o bien asigne manualmente a LD_LIBRARY_PATH el valor/usr/lib/oracle/11.2/client64/lib. Quizá también desee configurar variables de entorno para lenguaje y globalización de Oracle, tales como TNS_ADMIN y NLS_LANG. Si no se configura NLS_LANG, se trabajará con un entorno local predeterminado. Consulte el capítulo sobre Globalización en The Underground PHP and Oracle Manual para obtener más información.

Es importante configurar todas las variables de entorno de Oracle antes de iniciar Apache para que se inicialice correctamente el entorno para el proceso de OCI8. Configurar variables de entorno en secuencias de código de PHP puede conducir a problemas más o menos evidentes. En Oracle Linux, exporte las variables de entorno en /etc/sysconfig/httpd. En máquinas basadas en Debian, configúrelas en /etc/apache2/envvars.

Reinicie Apache, por ejemplo con la siguiente instrucción:

service httpd restart

Verificación de la instalación de la extensión OCI8 de PHP

Para verificar la configuración de OCI8, cree una secuencia sencilla de código PHP phpinfo.php en el directorio raíz de documentos de Apache:

<?php
phpinfo();
?>

    

Cargue la secuencia de código en un navegador utilizando la URL adecuada, por ejemplo, http://localhost/phpinfo.php. La página del navegador contendrá una sección relativa a "oci8" con la leyenda "OCI8 Support enabled" y las opciones de OCI8 que pueden configurarse.

Conexión a una base de datos de Oracle

Para crear una conexión, el nombre de usuario y la contraseña de Oracle se pasan como dos parámetros de oci_connect(). Debe usarse como tercer parámetro un identificador de conexión con el nombre de la base de datos de Oracle porque los programas vinculados con Instant Client siempre se consideran "remotos" respecto de cualquier servidor de bases de datos y es necesario explicitar con qué instancia de base de datos establecer la conexión. Probablemente la instrucción para establecer la conexión sea conocida en el caso de bases de datos de Oracle muy utilizadas. Con los nuevos sistemas, la información es provista por el programa de instalación de Oracle cuando se crea la base de datos. El instalador habrá configurado Oracle Network y creado un nombre de servicio como orcl por usted.

Hay varias maneras de pasar la información de conexión a PHP. En este ejemplo se usa la sintaxis de Easy Connect de Oracle para establecer una conexión con el esquema HR del servicio de base de datos orcl que se ejecuta en mymachine. No se necesita el archivo tnsnames.ora ni ningún otro archivo de Oracle Network:

$conn = oci_connect('hr', 'hr_password', 'mymachine.mydomain/orcl');

     

Consulte la documentación Using the Easy Connect Naming Method (Uso del método de denominación de Easy Connect, en inglés) de Oracle para conocer la sintaxis de Easy Connect.

En bases de datos nuevas, será necesario desbloquear los esquemas de demostración, tales como el usuario de HR, y asignarles una contraseña. Esto puede hacerse en SQL*Plus conectándose como usuario SYSTEM y ejecutando la siguiente instrucción:

ALTER USER nombre_de_usuario IDENTIFIED BY nueva_contraseña ACCOUNT UNLOCK;

Uso de OCI8 de PHP y Oracle

Pruebe una secuencia de código sencilla, testoci.php. Modifique las credenciales de conexión para que se adecuen a su base de datos y cargue la secuencia en un navegador. En este ejemplo se enumeran todas las tablas que pertenecen al usuario HR:

<?php

$conn = oci_connect('hr', 'hr_password', 'mymachine.mydomain/orcl');

$stid = oci_parse($conn, 'select table_name from user_tables');
oci_execute($stid);

echo "<table>\n";
while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
    echo "<tr>\n";
    foreach ($row as $item) {
        echo "  <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : " ")."</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>

Resolución de problemas

Revise el archivo de registro de errores de Apache en caso de problemas en el inicio.

Active temporalmente la visualización de errores de código mediante display_error=On en php.ini. Por razones de seguridad, restablezca el valor off (desactívelo) cuando termine la verificación.

En el capítulo 9 del manual The Underground PHP and Oracle Manual se incluye información sobre errores comunes en la conexión y se describen formas alternativas para configurar variables de entorno.

Puede descargar la herramienta para línea de comando SQL*Plus de Oracle de la página de Instant Client, muy útil para resolver problemas de conexión y de entorno. Verifique que SQL*Plus pueda conectarse y luego asegúrese de que la sección sobre Environment (entorno) –no la relativa a Apache Environment (Entorno de Apache)– del archivo phpinfo.php muestre la configuración de entorno equivalente.

Ayuda específica para Windows

Si la secuencia de código phpinfo.php no genera una sección relativa a "oci8" que incluya la leyenda "OCI8 Support enabled" (Soporte de OCI8 habilitado), verifique que la línea extension=php_oci8_11g.dll no esté marcada como comentario en php.ini.

Si la directiva extension_dir en php.ini no incluye el directorio que aloja el archivo php_oci8_11g.dll, al iniciarse Apache se emitirá una alerta: "PHP Startup: Unable to load dynamic library php_oci8_11g.dll." (Inicio de PHP: no se puede cargar la biblioteca dinámica php_oci8_11g.dll).

Si no se ha asignado un valor adecuado a PATH o si no es posible encontrar las bibliotecas de Oracle, al iniciarse Apache se emitirá una alerta: "The dynamic link library OCI.dll could not be found in the specified path." (No se encontró la biblioteca de enlace dinámico OCI.dll en la ruta especificada). La sección relativa a Entorno de la página phpinfo() mostrará los valores de PATH y las variables de Oracle que utiliza PHP efectivamente.

Si hay diversas versiones de las bibliotecas de Oracle en el equipo, es probable que se produzcan conflictos entre ellas. Para obtener información sobre cómo configurar variables, consulte Using PHP OCI8 with 32-bit PHP on Windows 64-bit (Uso de OCI8 de PHP con PHP de 32 bits en Windows de 64 bits, en inglés).

Ayuda específica para Linux

Si utiliza archivos zip de Instant Client, asegúrese de descomprimir los dos paquetes en la misma ubicación. Asegúrese de que un enlace simbólico libclntsh.so lleve a libclntsh.so.11.1.

Configure todas las variables de entorno de Oracle necesarias en el shell que inicia Apache.

Conclusión

Usar Instant Client de Oracle e instalar OCI8 de PHP desde PECL brinda máxima flexibilidad, lo que permite instalar y actualizar componentes de manera muy fácil.

Pueden publicarse preguntas y sugerencias en los foros sobre PHP o Instant Client de la red OTN.

El PHP Developer Center (Centro para desarrolladores de PHP) incluye enlaces a material de referencia muy útil.

 


Publicado por Christopher Jones.