Installazione

Configurazione di PHP con OCI8

Rivedere la precedente sezione Requisiti prima di configurare OCI8.

Per abilitare l'estensione OCI8, configura PHP con l'opzione --with-oci8.

Prima di avviare il server Web, OCI8 richiede in genere diverse variabili di ambiente Oracle (vedere di seguito) per individuare le librerie, puntare ai file di configurazione e impostare alcune proprietà di base come il set di caratteri utilizzato dalle librerie Oracle. Le variabili devono essere impostate prima che qualsiasi processo PHP venga avviato.

Il binario PHP deve collegarsi con la stessa versione principale o più recente delle librerie Oracle con cui è stato configurato. Ad esempio, se si effettua la build di OCI8 con le librerie Oracle 11.2, anche PHP dovrebbe essere distribuito ed eseguito con le librerie Oracle 11.2. Le applicazioni PHP possono connettersi ad altre versioni di Oracle Database, poiché Oracle ha una compatibilità tra versioni client e server.

Installazione di OCI8 come Estensione Condivisa

L'opzione di configurazione shared fa la build di OCI8 come libreria condivisa che può essere caricata dinamicamente in PHP. La creazione di un'estensione condivisa consente di aggiornare facilmente OCI8 senza influire sul resto di PHP.

Configurare OCI8 utilizzando una delle seguenti opzioni di configurazione.

  • Se si utilizzano le librerie » Oracle Instant Client gratuite, allora eseguire:

    ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
    

    Se Instant Client è installato da file ZIP, assicurarsi di creare prima il collegamento simbolico della libreria, ad esempio ln -s libclntsh.so.12.1 libclntsh.so.

    Se si utilizza un'installazione basata su RPM di Oracle Instant Client, la riga di configurazione sarà simile a questa:

    ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
    

    Per esempio, --with-oci8=shared,instantclient,/usr/lib/oracle/12.1/client/lib

    Si noti che il supporto di Oracle Instant Client è apparso per la prima volta in PHP 4.3.11 e 5.0.4 e originariamente utilizzava l'opzione --with-oci8-instant-client per configurare PHP.

  • Se si utilizza un database Oracle o l'installazione completa del client Oracle, allora eseguire:

    ./configure --with-oci8=shared,$ORACLE_HOME
    

    Assicurarsi che l'utente del server web (nobody, www) abbia accesso alle librerie, ai file di inizializzazione e a tnsnames.ora (se utilizzato) sotto la directory $ORACLE_HOME. Con Oracle 10gR2, potrebbe essere necessario eseguire l'utilità $ORACLE_HOME/install/changePerm.sh per fornire l'accesso alla directory.

Dopo la configurazione, seguire la solita procedura di build di PHP, ad es. make install. Verrà creata la libreria dell'estensione condivisa OCI8 oci8.so. Potrebbe essere necessario spostarla manualmente nella directory delle estensioni PHP, specificata dall'opzione extension_dir nel proprio file php.ini.

Per completare l'installazione di OCI8, modificare php.ini ed aggiungere la riga:

extension=oci8.so

Installazione di OCI8 come Estensione Compilata Staticamente

Configurare PHP per includere OCI8 utilizzando una delle seguenti opzioni di configurazione.

  • Se si utilizza Oracle Instant Client, allora eseguire:

    ./configure --with-oci8=instantclient,/path/to/instant/client/lib
    

  • Se si utilizza un database Oracle o l'installazione completa del client Oracle, allora eseguire:

    ./configure --with-oci8=$ORACLE_HOME
    

Dopo la configurazione, seguire la solita procedura di build di PHP, ad es. make install. Dopo che la compilazione è riuscita, non è necessario aggiungere oci8.so a php.ini. Non sono necessari passaggi di build aggiuntivi.

Installazione di OCI8 da PECL

L'estensione OCI8 può essere aggiunta a un'installazione PHP esistente automaticamente o manualmente da » PECL.

Per un'installazione automatica, seguire questi passaggi:

  • Se si è dietro un firewall, impostare il proxy di PEAR, ad esempio:

    pear config-set http_proxy http://my-proxy.example.com:80/
    

  • Eseguire

    pecl install oci8
    

    Quando richiesto, inserire il valore di $ORACLE_HOME, o instantclient,/percorso/verso/instant/client/lib.

    Nota: Non immettere la variabile $ORACLE_HOME perché non verrà espansa. Immettere invece il percorso effettivo della home directory di Oracle.

Per un'installazione manuale quando il comando pecl non è disponibile, scaricare il pacchetto PECL OCI8, ad es. oci8-1.4.10.tgz.

  • Estrarre il pacchetto:

    tar -zxf oci8-1.4.10.tgz
    cd oci8-1.4.10
    

  • Preparare il pacchetto:

    phpize
    

  • Configurare il pacchetto, utilizzando $ORACLE_HOME o Instant Client

    ./configure -with-oci8=shared,$ORACLE_HOME
    

    or

    ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
    

  • Installare il pacchetto:

    make install
    

Dopo un'installazione automatica o manuale, modificare il proprio file php.ini e aggiungere la riga:

extension=oci8.so

Assicurarsi che la direttiva extension_dir del php.ini sia impostata alla directory in cui è stato installato oci8.so.

Installazione di OCI8 su Windows

Quando si utilizzano le librerie client Oracle 10gR2 su Windows, rimuovere il commento dalla riga extension=php_oci8.dll del file php.ini. Quando si utilizzano le librerie client Oracle 11gR2 o successive, rimuovere il commento da extension=php_oci8_11g.dll o extension=php_oci8.dll. Con le librerie Oracle 12c utilizzare extension=php_oci8_12c.dll o extension=php_oci8_11g.dll o extension=php_oci8.dll. È possibile abilitare solo una di queste DLL alla volta. Le DLL con versioni successive possono contenere più funzionalità. Non tutte le DLL potrebbero essere disponibili per tutte le versioni di PHP. Assicurarsi che extension_dir sia impostata alla directory contenente le DLL delle estensioni PHP.

Se si utilizza Instant Client, impostare la variabile di ambiente di sistema PATH alla directory della libreria Oracle.

Impostazione dell'Ambiente Oracle

Prima di utilizzare questa estensione, assicurarsi che le variabili di ambiente Oracle siano impostate correttamente per l'utente demone web. Se il server Web viene avviato automaticamente all'avvio, assicurarsi che anche l'ambiente di avvio sia configurato correttamente.

Nota:

Non impostare le variabili di ambiente Oracle utilizzando putenv() in uno script PHP perché le librerie Oracle potrebbero essere caricate e inizializzate prima che lo script venga eseguito. Le variabili impostate con putenv() possono quindi causare conflitti, arresti anomali o comportamenti imprevedibili. Alcune funzioni potrebbero funzionare, ma altre potrebbero fornire piccoli errori. Le variabili dovrebbero essere impostate prima che il server web venga avviato.

Su Red Hat Linux e varianti, esportare le variabili alla fine di /etc/sysconfig/httpd. Altri sistemi con Apache 2 possono utilizzare uno script envvars nella directory bin di Apache. Una terza opzione, la direttiva Apache SetEnv in httpd.conf, può funzionare in alcuni sistemi ma è nota per essere insufficiente in altri.

Per verificare che le variabili d'ambiente siano impostate correttamente, usare phpinfo() e controllare che la sezione Environment (non Apache Environment) contenga le variabili previste.

Le variabili che potrebbero essere necessarie sono incluse nella tabella seguente. Fare riferimento alla documentazione Oracle per ulteriori informazioni su tutte le variabili disponibili.

Variabili di Ambiente Oracle Comuni
Nome Scopo
ORACLE_HOME Contiene la directory del software Oracle Database completo. Non si deve impostare quando si utilizza Oracle Instant Client in quanto non è necessario e potrebbe causare problemi di installazione.
ORACLE_SID Contiene il nome del database sulla macchina locale a cui connettersi. Non è necessario impostarlo se si utilizza Oracle Instant Client o si passa sempre il parametro di connessione a oci_connect().
LD_LIBRARY_PATH Impostare questo (o l'equivalente della piattaforma, come DYLD_LIBRARY_PATH, LIBPATH o SHLIB_PATH) alla posizione delle librerie Oracle, ad esempio $ORACLE_HOME/lib o /usr/lib/oracle/11.1/client/lib. Questa variabile non è necessaria se le librerie sono localizzate da un meccanismo di ricerca diverso, come con ldconfig o con LD_PRELOAD.
NLS_LANG Questa è la variabile principale per l'impostazione del set di caratteri e delle informazioni di globalizzazione utilizzate dalle librerie Oracle.
ORA_SDTZ Imposta il fuso orario della sessione Oracle.
TNS_ADMIN Contiene la directory in cui vengono conservati i file di configurazione di Oracle Net Services come tnsnames.ora e sqlnet.ora. Non necessario se la stringa di connessione oci_connect() utilizza la sintassi di denominazione Easy Connect come localhost/XE. Non necessario se i file di configurazione di rete si trovano in una delle posizioni predefinite come $ORACLE_HOME/network/admin o /etc.
Le variabili di ambiente Oracle utilizzate meno di frequente includono TWO_TASK, ORA_TZFILE e le varie impostazioni di globalizzazione Oracle come le variabili NLS* e ORA_NLS_*.

Risoluzione dei problemi

Il problema più comune con l'installazione di OCI8 non è avere l'ambiente Oracle impostato correttamente. Questo in genere appare come problema usando oci_connect() o oci_pconnect(). L'errore potrebbe essere un errore PHP come Call to undefined function oci_connect(), un errore Oracle come ORA-12705 o persino un arresto anomalo di Apache. Controllare i file di log di Apache per errori di avvio e vedere le sezioni precedenti per risolvere questo problema.

Mentre errori di rete come ORA-12154 o ORA-12514 indicano un problema di configurazione o denominazione di rete Oracle, la causa principale potrebbe essere dovuta al fatto che l'ambiente PHP non è impostato correttamente e le librerie Oracle non sono in grado di individuare il file di configurazione tnsnames.ora.

Su Windows, avere più versioni di Oracle su una macchina può facilmente causare conflitti di libreria a meno che non si presti attenzione per assicurarsi che PHP utilizzi solo la versione corretta di Oracle.

Un'utilità per esaminare quali librerie vengono cercate e caricate può aiutare a risolvere problemi di libreria mancanti o contrastanti, in particolare su Windows.

Nota: Se il server web non si avvia o si arresta in modo anomalo all'avvio

Verificare che Apache sia collegato alla libreria 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)

Se libpthread non è elencato, reinstallare Apache:

# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install

Si noti che su alcuni sistemi come UnixWare, è libthread invece di libpthread. PHP e Apache devono essere configurati con EXTRA_LIBS=-lthread.