Instalação do PHP e do Oracle Instant Client para Linux e Windows

A forma mais simples de configurar o PHP para ter acesso a um banco de dados remoto da Oracle é por meio de bibliotecas de Instant Client da Oracle. Neste artigo, descreveremos o modo de instalação do PHP com a extensão OCI8 e o Instant Client da Oracle no Windows e Linux. Em The Underground PHP and Oracle Manual (em inglês), de acesso gratuito, explicam-se outras opções de instalação y são oferecidos detalhes adicionais.

OCI8 é a extensão do PHP para estabelecer a conexão com o Oracle Database. A OCI8 é de código aberto e é incluída no PHP. Seu nome é formado pelas iniciais da API em C Oracle Call Interface (interface de chamada), incorporada na versão 8 do Oracle Database. A OCI8 vincula-se com as bibliotecas de cliente da Oracle, como o Oracle Instant Client.

O Oracle Instant Client é um conjunto gratuito de bibliotecas de fácil instalação que permite que os programas se conectem com instâncias do Oracle Database locais ou remotas. Para usar o Instant Client é necessário um banco de dados existente; o Instant Client não inclui banco de dados. Geralmente, o banco de dados ficará em outro equipamento. Se o banco de dados for local, em geral, o Instant Client não é necessário, embora seja conveniente e funcione, pois a OCI8 pode usar diretamente as bibliotecas do banco de dados.

Utilizando o Instant Client 11g, a OCI8 do PHP se conecta com todas as edições dos bancos de dados da Oracle 9.2, 10.x, e 11.x.

Requisitos de software

Habilitação da extensão OCI8 do PHP no Windows

Os arquivos binários do Instant Client complementam os arquivos binários para o Windows Millennium pré-integrados no PHP.

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

2. Clique duas vezes no arquivo MSI para executar o instalador.

Instale "for All Users, on Port 80" ("para todos os usuários, na porta 80"). Faça uma instalação típica na pasta de destino por default: C:\Program Files\Apache Software Foundation\Apache2.2.

3. Faça o download do componente FastCGI mod_fcgid-2.3.6-win32-x86.zip de httpd.apache.org/download.cgi#mod_fcgid

4. Descompacte na pasta onde instalou o Apache 2.2. A pasta C:\Program Files\Apache Software Foundation\Apache2.2\modules deveria conter agora os arquivos mod_fcgid.so e mod_fcgid.pdb.

5. Edite o arquivo C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf e adicione a linha:

6. Em httpd.conf, localize a seção relativa a htdocs e adicione ExecCGI em Options:

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

7. Instale o PHP baixando o pacote zip "VC9 x86 Non Thread Safe" do PHP 5.4.0, php-5.4.0-nts-Win32-VC9-x86.zip, de windows.php.net/download.

8. No Windows Explorer, crie a pasta C:\php-5.4.0 e descompacte nela o pacote do PHP.

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

10. Edite o arquivo php.ini fazendo as seguintes alterações:

o Adicione uma linha de fuso horário, como a seguinte: date.timezone = America/<Los_Angeles Use o nome de seu fuso horário local.

o Adicione a linha:

Esta é a pasta que contém as extensões do PHP.

o Apague o ponto e vírgula no início da linha:

11. Edite o arquivo C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf adicionando as seguintes linhas. Confira estar usando barras diagonais regulares "/" e não invertidas "\":

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

12. Faça o download do pacote "Instant Client Package - Basic" para Windows do site do Instant Client da rede OTN (Oracle Technology Network). Sendo o PHP uma ferramenta de 32 bits, use a versão de 32 bits do Instant Client.

Descompacte os arquivos do Instant Client em C:\instantclient_11_2

13. Edite a configuração de ambiente PATH do Windows, adicionando C:\instantclient_11_2. Por exemplo, no Windows XP, clique em Iniciar -> Painel de controle -> Sistema -> Configurações avançadas -> Variáveis de ambiente e edite PATH na lista de variáveis do sistema.

Geralmente, é necessário reinicializar o Windows para o novo ambiente se estabelecer corretamente.

Configure as variáveis de ambiente para linguagem e globalização do Oracle desejado, como NLS_LANG. Se os valores específicos não forem estabelecidos, trabalhará com um ambiente local por default. Consulte o capítulo sobre Globalização em The Underground PHP and Oracle Manual para obter mais informações.

Elimine as especificações das variáveis do Oracle, como ORACLE_HOME e ORACLE_SID, pois não são necessárias com o Instant Client.

Se você tiver um outro software da Oracle em seu computador, em lugar de alterar o ambiente do Windows, crie uma sequência de código que configure os valores mencionados e inicialize o Apache. Caso contrário, provavelmente vão se produzir conflitos entre símbolos das bibliotecas, devido a diferenças entre versões.

14. Reinicialize o Apache a partir do Apache Monitor da bandeja do sistema ou da opção do menu Iniciar.

Habilitação da extensão OCI8 do PHP no Linux

No Linux, o PHP é geralmente compilado manualmente, pois a versão em pacote não costuma ser atualizada. No entanto, se você não quer compilar novamente o PHP, pode ter acesso a pacotes RPM para o Oracle Linux mais atualizados sem suporte em oss.oracle.com, ou com atualizações da rede Unbreakable Linux Network. Se você quer trabalhar em um ambiente PHP com suporte, use Zend Server. Todos eles têm a extensão OCI8 pré-integrada.

Para gerar o PHP e a extensão OCI8 a partir de código fonte:

1. Instale o servidor HTTP Apache e os pacotes de desenvolvimento, por exemplo, com yum install httpd httpd-devel.

2. Baixe o código fonte do PHP 5.4 e instale o PHP seguindo as instruções do capítulo Installation on Unix systems (Instalación en sistemas Unix) do manual do PHP (em inglês).

Nesta fase, não configure a extensão OCI8.

3. Baixe os pacotes Basic e SDK Instant Client do site do Instant Client da rede OTN. É possível usar o arquivo zip ou os pacotes RPM.

Execute os pacotes RPM como usuário root, por exemplo:

 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  
 O primeiro pacote RPM adiciona as bibliotecas da Oracle em 
 /usr/lib/oracle/11.2/client64/lib e o segundo cria cabeçalhos em  
 /usr/include/oracle/11.2/client64.       
 
 

Se você estiver usando os arquivos zip, deverá descompactar o pacote SDK na mesma pasta que o pacote Basic e criar manualmente um link simbólico:

4. A extensão OCI8 mais recente de PECL é sempre a versão atual. Embora sua atualização esteja frequentemente sincronizada com a do código fonte do PHP 5.4, às vezes a versão da extensão pode ser mais recente. A extensão mais recente pode ser baixada e adicionada ao PHP de forma automática usando:

pecl install oci8  
  Dando 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] :  
  Caso você conte com os RPM do Instant Client, aperte a tecla Enter e PECL 
  vai gerar e instalar automaticamente uma biblioteca compartilhada oci8.so. 
  Se você tiver os arquivos zip do Instant Client, ou quiser usar uma versão  
  particular do Instant Client, informe explicitamente o caminho apropriado 
  após "instantclient,":  instantclient,/usr/lib/oracle/11.2/client64/lib 
  Use um caminho absoluto e explícito, pois PECL não expande as variáveis de ambiente.
  Se você não tem o programa pecl, pode baixar o pacote OCI8 com seu navegador  
  e instalá-lo seguindo as instruções: 
  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 o arquivo php.ini e habilite a extensão OCI8 com a seguinte instrução:

Adicione a pasta do Instant Client em /etc/ld.so.conf, ou aloque manualmente a LD_LIBRARY_PATH o valor/usr/lib/oracle/11.2/client64/lib. É possível que você também queira configurar variáveis de ambiente para linguagem e globalização da Oracle, como TNS_ADMIN e NLS_LANG. Se NLS_LANG não for configurado, vai trabalhar com um ambiente local por default. Consulte o capítulo sobre Globalização em The Underground PHP and Oracle Manual para obter mais informações.

É importante configurar todas as variáveis de ambiente da Oracle antes de executar o Apache para que o ambiente para o processo de OCI8 seja corretamente inicializado. Configurar variáveis de ambiente em sequências de código do PHP pode provocar problemas mais ou menos evidentes. No Oracle Linux, exporte as variáveis de ambiente em /etc/sysconfig/httpd. Em computadores baseados no Debian, configure em /etc/apache2/envvars.

Reinicialize o Apache, por exemplo, com a seguinte instrução:

Verificação da instalação da extensão OCI8 do PHP

Para verificar a configuração da OCI8, crie uma sequência simples de código PHP phpinfo.php no diretório raiz de documentos do Apache:

Carregue a sequência de código em um navegador, utilizando a URL adequada, por exemplo, http://localhost/phpinfo.php. A página do navegador vai conter uma seção relativa a "oci8" com o texto "OCI8 Support enabled" e as opções da OCI8 que podem ser configuradas.

Conexão com um banco de dados da Oracle

Para criar uma conexão, o nome de usuário e a senha da Oracle são passados como dois parâmetros de oci_connect(). É preciso usar um identificador de conexão como terceiro parâmetro com o nome do banco de dados da Oracle, pois os programas associados ao Instant Client sempre são considerados "remotos" por qualquer servidor de bancos de dados e deve se explicitar com qual instância de banco de dados estabelecer a conexão. Provavelmente, a instrução para estabelecer a conexão seja conhecida no caso de bancos de dados da Oracle muito utilizados. Com os sistemas novos, a informação é fornecida pelo programa de instalação da Oracle quando o banco de dados é criado. O instalador terá configurado o Oracle Network e criado um nome de serviço como orcl por você.

Há diversas formas de passar a informação de conexão ao PHP. Neste exemplo, é usada a sintaxe do Easy Connect da Oracle para estabelecer uma conexão com o esquema HR do serviço de banco de dados orcl executado em mymachine. Nem o arquivo tnsnames.ora, nem nenhum outro arquivo do Oracle Network, são necessários:

Consulte a documentação Using the Easy Connect Naming Method (Uso do método de denominação do Easy Connect, em inglês) da Oracle para conhecer a sintaxe do Easy Connect.

Em bancos de dados novos, será necessário desbloquear os esquemas de demonstração, como o usuário do HR, e alocar uma senha. Isto pode ser feito em SQL*Plus, acessando como usuário SYSTEM e executando a seguinte instrução:

Uso da OCI8 do PHP e Oracle

Tente com uma sequência de código simples, testoci.php. Altere as credenciais de conexão para se adequarem a seu banco de dados e carregue a sequência em um navegador. Neste exemplo, são enumeradas todas as tabelas do usuário 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"; 
   ?>    
 
 

Resolução de problemas

Verifique o arquivo de logs de erros do Apache em caso de problemas na inicialização.

Ative temporalmente a visualização de erros de código com display_error=On em php.ini. Por motivos de segurança, restabeleça o valor off (desative) quando finalizar a verificação.

No capítulo 9 do manual The Underground PHP and Oracle Manual, incluem-se informações sobre erros frequentes na conexão e descrevem-se formas alternativas de configuração de variáveis de ambiente.

Pode baixar a ferramenta para linha de comando SQL*Plus da Oracle do site do Instant Client, muito útil para resolver problemas de conexão e de ambiente. Verifique que SQL*Plus possa se conectar e depois confira que a seção sobre Environment (ambiente) –não a relativa ao Apache Environment (Ambiente do Apache)– do arquivo phpinfo.php exiba a configuração de ambiente equivalente.

Ajuda específica para o Windows

Se a sequência de código phpinfo.php não gerar uma seção relativa à "oci8" incluindo o texto "OCI8 Support enabled" (Suporte da OCI8 habilitado), confira que a linha extension=php_oci8_11g.dll não esteja marcada como comentário em php.ini.

Se a diretiva extension_dir em php.ini não incluir o diretório que contém o arquivo php_oci8_11g.dll, o Apache emitirá um alerta durante a inicialização: "PHP Startup: Unable to load dynamic library php_oci8_11g.dll." (Inicialização do PHP: não á possível carregar a biblioteca dinâmica php_oci8_11g.dll).

Caso um valor adequado não tenha sido alocado a PATH ou se não for possível encontrar as bibliotecas da Oracle, o Apache emitirá um alerta durante a inicialização: "The dynamic link library OCI.dll could not be found in the specified path." (A biblioteca de link dinâmico OCI.dll não foi achada no caminho especificado). A seção relativa a Ambiente da página phpinfo() mostrará os valores de PATH e as variáveis da Oracle utilizados efetivamente pelo PHP.

Se houver diversas versões das bibliotecas da Oracle no computador, poderá haver conflitos entre elas. Para obter informações sobre como configurar variáveis, consulte Using PHP OCI8 with 32-bit PHP on Windows 64-bit (Uso da OCI8 do PHP com o PHP de 32 bits no Windows de 64 bits, em inglês).

Ajuda específica para o Linux

Se você utilizar arquivos zip do Instant Client, descompacte os dois pacotes na mesma localização. Verifique que um link simbólico libclntsh.so leve para libclntsh.so.11.1.

Configure todas as variáveis de ambiente da Oracle necessárias no shell que inicializa o Apache.

Conclusão

Usar o Instant Client da Oracle e instalar a OCI8 do PHP a partir de PECL oferece máxima flexibilidade, permitindo a instalação e atualização de componentes de forma muito fácil.

É possível postar perguntas e sugestões nos fóruns sobre PHP ou Instant Client da rede OTN.

O PHP Developer Center (Centro para desenvolvedores do PHP) inclui links para materiais de referência muito úteis.

Postado por Christopher Jones.