array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'oci8.installation.php', 1 => 'Instalação', 2 => 'Instalação', ), 'up' => array ( 0 => 'oci8.setup.php', 1 => 'Instalação/Configuração', ), 'prev' => array ( 0 => 'oci8.requirements.php', 1 => 'Dependências', ), 'next' => array ( 0 => 'oci8.test.php', 1 => 'Testando', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'reference/oci8/configure.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

Instalação

Configurando o PHP com o OCI8

Consulte a seção anterior sobre requisitos antes de configurar o OCI8.

Antes de inicializar o servidor web, o OCI8 tipicamente requer várias variáveis de ambiente Oracle (veja abaixo) para localizar bibliotecas, apontar para arquivos de configuração e definir algumas propriedades básicas como o conjunto de caracteres utilizado pelas bibliotecas Oracle. As variáveis devem ser definidas antes que qualquer processo PHP inicie.

O binário PHP deve ter sido construído com a mesma versão principal, ou mais recente, das bilbiotecas Oracle com as quais foi configurado. Por exemplo, se o OCI8 estiver utilizando as bilbiotecas Oracle versão 19, o PHP também deve ser construído e executado com as bibliotecas Oracle 19. Aplicações PHP podem se conectar a outras versões de banco de dados Oracle, já que a Oracle tem compatibilidade cliente-servidor com versões diferentes.

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.

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.

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.

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: 

extension=oci8.so

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.

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: 

# 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 não estiver listada, reinstale o Apache: 

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

Note que em alguns sistemas como UnixWare, o nome é libthread em vez de libpthread. PHP e Apache devem ser configurados com EXTRA_LIBS=-lthread.