Revise la sección previa Requerimientos antes de configurar OCI8.
Para habilitar la extensión OCI8 se ha de configurar PHP con la opción --with-oci8 .
Antes de iniciar el servidor web, OCI8 normalmente necesita diversas variables de entorno de Oracle (véase abajo) para localizar bibliotecas, apuntar a ficheros de configuración, y establecer algunas propiedades básicas como el conjunto de caracteres usado por las bibliotecas de Oracle. Las variables deben ser establecidas antes de que se inicie cualquier proceso de PHP.
El binario de PHP debe vincularse con la misma, o más reciente, versión mayor de las bibliotecas de Oracle con las que se configuró. Por ejemplo, si se construyó OCI8 con las bibliotecas de Oracle 11.2, entonces PHP debería también PHP usarse y ejecutarse con la bibliotecas de Oracle 11.2. Las aplicaciones de PHP pueden conectarse a otras versiones Oracle Database, ya que Oracle posee compatibilidad cliente-servidor entre versiones.
La opciones de configuración shared construye OCI8 como una biblioteca compartida que puede ser cargada dinámicamente en PHP. La construcción de una extensión compartida permite que OCI8 sea actualizada fácilmente sin que tenga impacto sobre el resto de PHP.
Se ha de configurar OCI8 usando una de las siguientes opciones de configuración:
Si se usan las bibliotecas » Oracle Instant Client gratuitas, se ha de hacer lo siguiente:
./configure --with-oci8=shared,instantclient,/ruta/a/instant/client/lib
Si Instant Client está instalado desde ficheros ZIP, asegúrese de crear el enlace simbólico de la biblioteca primero, por ejemplo ln -s libclntsh.so.12.1 libclntsh.so.
Si se usa una instalación de Oracle Instant Client basada en RPM, la línea de confiugraicón se parecerá a esta:
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
Por ejemplo, --with-oci8=shared,instantclient,/usr/lib/oracle/12.1/client/lib
Nótese que el soporte para Oracle Instant Client apareció primero en PHP 4.3.11 y 5.0.4 y que originalmente se utilizaba la opción --with-oci8-instant-client para configurar PHP.
Si se usa una base de datos de Oracle o una instalación completa de Oracle Client, la línea ha de ser:
./configure --with-oci8=shared,$ORACLE_HOME
Asegúrese de que el usuario del servidor web (nobody, www) tiene acceso a las biblitecas, a los ficheros de inicialización y a tnsnames.ora (si se utiliza) bajo el directorio $ORACLE_HOME. Con Oracle 10gR2 podría ser necesario ejecutar la utilidad $ORACLE_HOME/install/changePerm.sh para proporcionar acceso al directorio.
Después de la configuración, siga los procedimientos habituales de construcción de PHP, p.ej., make install. Se creará la extensión compartida oci8.so. Podría ser necesario moverla manualmente al directorio de extensiones de PHP, especificado por la opción extension_dir del fichero php.ini.
Para completar la instalación de OCI8, edite php.ini y añada la línea:
extension=oci8.so
Se ha de configurar PHP para incluir OCI8 usando una de las siguientes opciones de configuración:
Si se usa Oracle Instant Client, se ha de utilizar lo siguiente:
./configure --with-oci8=instantclient,/path/to/instant/client/lib
Si se usa una base de datos de Oracle o una instalación completa de Oracle Client, la línea ha de ser:
./configure --with-oci8=$ORACLE_HOME
Después de la configuración, siga los procedimientos habituales de construcción de PHP, p.ej., make install. Después de una compilación satisfactoria no es necesario añadir oci8.so a php.ini. No se requieren pasos adicionales para la construcción.
La extensión OCI8 se puede añadir a una instalación de PHP existente, automática o manualmente, desde » PECL.
Para una instalación automática, siga estos pasos:
Si está detrás de un cortafuegos, establezca el proxy de PEAR, por ejemplo:
pear config-set http_proxy http://mi-proxy.example.com:80/
Ejecute
pecl install oci8
Cuando se le pregunte, introduzca el valor de $ORACLE_HOME, o instantclient,/path/to/instant/client/lib.
Nota: No introduzca la variable $ORACLE_HOME ya que no será expandida. En su lugar, introduzca la ruta real del directorio inicial de Oracle.
Para una instalación manual cuando el comando pecl no esté disponible, descargue el paquete OCI8 de PECL, p.ej. oci8-1.4.10.tgz.
Extraiga el paquete:
tar -zxf oci8-1.4.10.tgz cd oci8-1.4.10
Prepare el paquete:
phpize
Configure el paquete, usando $ORACLE_HOME o Instant Client
./configure -with-oci8=shared,$ORACLE_HOME
o
./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
Instale el paquete:
make install
Después de la instalación manual o automática, edite el fichero php.ini y añada la línea:
extension=oci8.so
Asegúrese de que la directiva de php.ini extension_dir está establecida al directorio donde oci8.so fue instalado.
Al usar las bibiotecas cliente de Oracle 10gR2 en Windows, descomente la línea del php.ini extension=php_oci8.dll. Al usar las bibliotecas cliente de Oracle 11gR2 o posterior, descomente extension=php_oci8_11g.dll o extension=php_oci8.dll. Con las bibliotecas de Oracle 12c use extension=php_oci8_12c.dll o extension=php_oci8_11g.dll o extension=php_oci8.dll. Solamente puede estar habilitada una de estas DLLs al mismo tiempo. Las DLLs de versiones posteriores pueden contener más funcionalidad. No todas las DLLs pueden estar disponibles para todas las versiones PHP. Asegúrese de que extension_dir está establecido al directorio que contiene las DDLs de extensiones de PHP.
Si usa Instant Client, establezca la variable de entorno de sistema PATH al directorio de la biblioteca de Oracle.
Antes de usar esta extensión, asegúrese de que las variables de entorno de Oracle están establecidas apropiadamente para el usuario del demonio web. Si el servidor web se inicia automáticamente durante el arranque, asegúrese de que el entorno de tiempo de arranque está también configurado correctamente.
Nota:
No establezca las variables de entorno de Oracle usando putenv() en un script de PHP, ya que la bibliotecas de Oracle podrían ser cargadas e inicializadas antes de que el script se ejecute. Las variables establecidas con putenv() podrían ocasionar conflictos, fallas, o comportamientos impredecibles. Algunas funciones podrían funcionar, mientras que otras darían errores imperceptibles. Las variables deberían estar configuradas antes de que se inicie el servidor web.
En Red Hat Linux y sus variantes, exporte las variables al final de /etc/sysconfig/httpd. Otros sistemas con Apache 2 podrían usar un script envvars en el directorio bin de Apache. Una tercera opción, la directiva SetEnv de Apache en httpd.conf, podría funcionar en algunos sistemas, pero se sabe que es insuficiente en otros.
Para verificar que las variables de entorno están establecidas correctamente, use phpinfo() y compruebe la sección Environment (no la de Apache) que contiene las variables requeridas.
Las variables que podrían ser necesarias están incluidas en la siguiente tabla. Consulte la documentación de Oracle para más información sobre todas las variables disponibles.
| Nombre | Propósito |
|---|---|
| ORACLE_HOME | Contiene el directorio del software completo de Oracle Database. No la establezca cuando use Oracle Instant Client ya que no es necesaria y podría causar problemas de instalación. |
| ORACLE_SID | Contiene el nombre de la base de datos de la máquina local a la que conectarse. Na hay necesidad de establecerla si se usa Oracle Instant Client, o si siempre se proporciona el parámetro de conexión a oci_connect(). |
| LD_LIBRARY_PATH | Establézcala (o su equivalente de plataforma, como DYLD_LIBRARY_PATH, LIBPATH, o SHLIB_PATH) a la ubicación de las bibliotecas de Oracle, por ejemplo, $ORACLE_HOME/lib o /usr/lib/oracle/11.1/client/lib. Esta variable no es necesaria si las bibliotecas está localizadas mediante un mecanismo de búsqueda diferente, como con ldconfig o LD_PRELOAD. |
| NLS_LANG | Esta es la variable principal para configurar el conjunto de caracteres y la información de globalización usados por las bibliotecas de Oracle. |
| ORA_SDTZ | Establece la zona horaria de la sesión de Oracle. |
| TNS_ADMIN | Contiene el directorio donde residen los ficheros de configuración de Oracle Net Services, tales como tnsnames.ora y sqlnet.ora. No es necesaria si la cadena de conexión oci_connect() utiliza la sintaxis de nombramiento sencillo de conexiones, como localhost/XE. No es necesaria si los ficheros de configuración de red está en las ubicaciones predeterminadas, como $ORACLE_HOME/network/admin o /etc. |
El problema más común al instalar OCI8 es no tener el entorno de Oracle correctamente establecido. Esto, normalmente, aparece como un problema al utilizar oci_connect() o oci_pconnect(). El error podría ser un error de PHP tal como Call to undefined function oci_connect(), un error de Oracle como ORA-12705, o incluso que Apache falle. Compruebe los ficheros de registro de Apache para los errores de arranque y lea las secciones sobre la resolución de este problema.
Mientras que los errores de red como ORA-12154 u ORA-12514 indican un problema con el nombramiento de redes o de configuraicón de Oracle, la raíz de la causa podría ser debida a que el entorno de PHP no esté correctamente configurado, y por lo tanto, las bibliotecas de Oracle no son capaces de localizar el fichero de configuración tnsnames.ora.
En Windows, el tener múltiples versiones de Oracle en la misma máquina puede ocasionar fácilmente que las bibliotecas fallen, a menos que se asegure de que PHP utilice solamente la versión correcta de Oracle.
Una utilidad para examinar las bibliotecas que están siendo buscadas y cargadas puede ayudar a resolver problemas de bibliotecas ausentes o que fallen, particularmente en Windows.
Nota: Si el servidor web no se inicia o falla durante el arranque
Compruebe que Apache está vinculado con la biblioteca pthread:
# ldd /www/apache/bin/httpd libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000) libm.so.6 => /lib/libm.so.6 (0x4002f000) libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000) libdl.so.2 => /lib/libdl.so.2 (0x4007a000) libc.so.6 => /lib/libc.so.6 (0x4007e000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)Si libpthread no se muestra, reinstale Apache:
# cd /usr/src/apache_1.3.xx # make clean # LIBS=-lpthread ./config.status # make # make installPor favor, observe que en algunos sistemas como UnixWare, es libthread en lugar de libpthread. PHP y Apache tienen que estar configurados con EXTRA_LIBS=-lthread.