Instalação
Instalando OCI8 com PECL Usando o Comando pecl
A extensão OCI8 pode ser adicionada a uma instalação PHP existente usando
o repositório » PECL.
-
Se estiver por trás de um firewall, defina o proxy PEAR, por exemplo:
-
Execute
Para o PHP 7, use pecl install oci8-2.2.0
-
Quando solicitado, entre o valor de $ORACLE_HOME
ou
instantclient,/caminho/para/biblioteca/instant/client
.
Nota: Não use nomes de variáveis como $ORACLE_HOME
ou $HOME
porque o pecl
não irá
interpretá-las. Em vez disso, informa um caminho expandido, por
exemplo /opt/oracle/product/19c/dbhome_1
ou instantclient,/Users/myname/Downloads/instantclient_19_8
.
-
Se ocorrer um erro do tipo oci8_dtrace_gen.h: No such file or
directory
, significa que o PHP foi compilado com
Rastreamento Dinâmico DTrace habilitado.
Instale usando:
-
Edite o arquivo php.ini e adicione a linha:
Certifique-se que a diretiva
extension_dir do php.ini esteja
definida para o diretório onde o arquivo oci8.so tenha sido
instalado.
Instalando OCI8 com PECL Usando phpize
Para instalar o OCI8 em uma instalação PHP existente quando
o comando pecl
não estiver disponível, baixe manualmente
o pacote OCI8 » PECL,
ex.: oci8-3.0.0.tgz.
-
Extraia o pacote:
-
Prepare o pacote:
-
Configure o pacote,
usando $ORACLE_HOME
ou Instant Client
ou
-
Instale o pacote:
-
Se ocorrer um erro do tipo oci8_dtrace_gen.h: No such file or
directory
, significa que o PHP foi compilado
com Rastreamento Dinâmico DTrace habilitado.
Execute novamente os comandos configure
e make
depois de definir esta variável de ambiente:
-
Edite o arquivo php.ini e adicione a linha:
Certifique-se que a diretiva
extension_dir do php.ini esteja
definida para o diretório onde o arquivo oci8.so tenha sido
instalado.
Instalando o OCI8 como uma Extensão Compartilhada ao Compilar o PHP
Se o PHP está sendo compilado a partir do código-fonte, a opção
de configuração shared
pode ser usada para construir o OCI8 como uma biblioteca
compartilhada que pode ser carregada dinamicamente no PHP. Construir uma extensão compartilhada permite que
o OCI8 seja atualizado facilmente sem impactar o restante do PHP.
Configure o OCI8 usando uma das opções de configuração a seguir.
-
Se as bibliotecas gratuitas do » Oracle Instant
Client estiverem sendo usadas, execute:
Se a Instant Client 12.2 (ou anterior) tiver sido instalada a partir de arquivos ZIP, certifique-se de
criar as ligações simbólicas da biblioteca primeiro, por exemplo ln -s
libclntsh.so.12.1 libclntsh.so
.
Se estiver sendo usada uma instalação baseada em RPM da Oracle Instant Client, a
linha de configuração será parecida com:
Por exemplo, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib
-
Se um banco de dados Oracle ou uma instalação completa do Oracle Client estiverem sendo usados, execute:
Certifique-se que o usuário sob o qual o servidor web esteja sendo executado
(nobody
, www
) tenha acesso às
bibliotecas, arquivos de inicialização
e tnsnames.ora (se usado) no diretório
$ORACLE_HOME
. Com o Oracle
10gR2, pode ser necessário executar
o utilitário $ORACLE_HOME/install/changePerm.sh
para conceder acesso ao diretório.
Depois da configuração, siga o procedimento usual de compilação do PHP,
ex.: make install. A biblioteca da extensão
compartilhada OCI8 oci8.so será criada. Pode ser necessário
movê-la manualmente para o diretório das extensões PHP, especificado pela
opção extension_dir no
arquivo php.ini.
Para completar a instalação do OCI8, edite o php.ini e adicione a linha:
Instalando o OCI8 como um Extensão Compilada Estaticamente ao Compilar o PHP
Se o PHP estiver sendo compilado a partir do código-fonte, pode-se configurá-lo para incluir
o OCI8 como uma extensão estática usando uma das seguintes opções de configuração.
-
Se o Oracle Instant Client estiver sendo utilizado, execute:
-
Se um banco de dados Oracle ou uma instalação completa do Oracle Client estiverem sendo usados, execute:
Depois da configuração, siga o procedimento usual de compilação do PHP,
ex.: make install. Após a compilação
bem sucedida, não é necessário incluir oci8.so ao
php.ini. Nenhum passo adicional de compilação é requerido.
Instalando o OCI8 no Windows
A extensão OCI8 pode ser adicionada a uma instalação PHP existente usando as
DLLs do repositório » PECL ou
as bibliotecas no diretório ext
da instalação do PHP.
Com as bibliotecas Oracle 12c (ou mais recentes), ative uma das
linhas extension=php_oci8_12c.dll
,
extension=php_oci8_11g.dll
ou extension=php_oci8.dll
do php.ini. Apenas uma dessas DLLs pode ser
habilitada de cada vez. DLLs com versões maiores podem conter mais
funcionalidades. Pode ser que nem todas as DLLs estejas disponíveis para todas as versões do PHP.
Certifique-se que extension_dir esteja definido
para o diretório contendo as DLLs de extensões do PHP.
Se o Instant Client estiver sendo utilizado, defina a variável de ambiente do sistema PATH
para o diretório da biblioteca Oracle.
Configurando o Ambiente Oracle
Antes de usar esta extensão, certifique-se que as variáveis de ambiente
Oracle estajam adequadamente definidas para o usuário sob o qual o servidor web esteja sendo executado.
Se o servidor web estiver sendo automaticamente iniciado quando o sistema é ligado, garanta que
o ambiente em tempo de inicialização também esteja configurado corretamente.
Nota:
Não defina as variáveis de ambiente Oracle
usando putenv() em um script PHP porque as bilbiotecas
Oracle podem estar carregadas e inicializadas antes que o script
seja executado. Variáveis definidas com putenv() podem causar
conflitos, travamentos ou comportamento imprevisível. Algumas funções podem
funcionar mas outras podem dar erros sutis. As variáveis devem ser
definidas antes que o servidor web seja iniciado.
No Linux Red Hat e variantes, exporte as variáveis no final do arquivo
/etc/sysconfig/httpd. Outros sistemas com
Apache 2 pode usar um script envvars no diretório
bin do Apache. Uma terceira opção, a
diretiva SetEnv
do Apache
no arquivo httpd.conf, pode funcionar em alguns sistemas mas
é sabido que isto é insuficiente em outros.
Para verificar que as variáveis de ambiente estão definidas corretamente,
use phpinfo() e verifique se
a seção Environment (não a Apache
Environment) contém as variáveis esperadas.
As variáveis que devem ser necessárias estão incluídas na tabela
a seguir. Consulte a documentação da Oracle para mais informação sobre
todas as variáveis disponíveis.
Variáveis de Ambiente Oracle Comuns
Nome |
Propósito |
ORACLE_HOME |
Contém o diretório da instalação completa do Banco de dados
Oracle. Não defina esta variável ao usar o Oracle Instant Client pois
é desnecessário e pode causar problemas de instalação. |
ORACLE_SID |
Contém o nome do banco de dados na máquina local ao qual a
ser conectado. Não há necessidade de definir esta variável se o
Oracle Instant Client estiver sendo usado, ou passe sempre o parâmetro de conexão
para a função oci_connect(). |
LD_LIBRARY_PATH |
Defina esta variável (ou sua equivalente dependendo da plataforma, como
LIBPATH ou SHLIB_PATH ) para a
localização das bibliotecas Oracle libraries, por
exemplo $ORACLE_HOME/lib
ou /usr/lib/oracle/18.5/client/lib. Note que com arquivos ZIP
do Instant Client no Linux é mais confiável usar
ldconfig, consulte as instruções de
instalação do Instant Client. Com o Instant Client 19 (ou posterior) em arquivos
RPM, ldconfig é executado automaticamente. Alguns usuários
utilizam
LD_PRELOAD no lugar
de LD_LIBRARY_PATH . |
NLS_LANG |
Esta é a variável primária para definir o conjunto
de caracteres e informação de globalização usados pelas bibliotecas
Oracle. |
ORA_SDTZ |
Define o fuso horário da sessão Oracle. |
TNS_ADMIN |
Contém o diretório onde os arquivos de configuração do Oracle Net Services
como tnsnames.ora
e sqlnet.ora são mantidos. Não é necessária se
a string de conexão da função oci_connect() usa a sintexe de nomes
Easy Connect como localhost/XE . Não é necessária se
os arquivos de configuração de rede estiverem em uma das localizações padrões
como
/usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin
ou /etc. |
Variáveis de ambiente utilizadas com menor frequência incluem
TWO_TASK
,
ORA_TZFILE
e as
várias configuração de globalização Oracle
como as variáveis
NLS*
e
ORA_NLS_*
.
Solução de Problemas
O problema mais comum na instalação do OCI8 é não ter o
ambiente Oracle definido corretamente. Isto tipicamente aparece como um
problema ao usar oci_connect()
ou oci_pconnect(). O erro pode ser gerado pelo PHP,
como Call to undefined function
oci_connect(), ou pelo Oracle, como ORA-12705, ou até
um travamento do Apache. Verifique se os arquivos de registro do Apache contêm erros de inicialização e
consulte as seções acima para resolver este problema.
Enquanto erros de rede como ORA-12154 ou ORA-12514 indicam um problema de
nome ou configuração de rede Oracle, a causa raiz pode ser o ambiente
PHP incorretamente configurado e a incapacidade das bibliotecas Oracle
em localizar o arquivo de configuração
tnsnames.ora.
No Windows, múltiplas versões do Oracle instaladas em uma máquina
pode facilmente gerar conflitos de bilbiotecas a menos que se tenha cuidado
garantindo que o PHP usa apenas a versão correta do Oracle.
Um utilitário para examinar que bibliotecas estão sendo procuradas e carregadas
pode ajudar a resolver problemas de bibliotecas ausentes ou conflitantes, particularmente no
Windows.
Nota:
Se o servidor web não iniciar ou travar na
inicialização
Verifique que o Apache foi construído com a biblioteca pthread:
Se libpthread não estiver listada, reinstale o Apache:
Note que em alguns sistemas como UnixWare, o nome é libthread
em vez de libpthread. PHP e Apache devem ser configurados com
EXTRA_LIBS=-lthread.