インストール手順

OCI8 とともに PHP を構成する

OCI8 を構成する前に前述の要件節に目を通してください。

Web サーバーを開始する前に、一般的に OCI8 はいくつかの Oracle 環境変数（下記参照）が必要です。それらはライブラリの場所を指定したり、構成ファイルを指示したり、 Oracle ライブラリで使用する文字セットのような基本的ないくつかのプロパティを設定します。あらゆる PHP プロセスが開始される前にそれらの変数を設定しなければいけません。

PHP を構成したのと同じか、またはより最新の Oracle ライブラリのメジャー・バージョンとともに PHP バイナリをリンクしなければいけません。例えば Oracle 19 ライブラリで OCI8 をビルドするなら、 PHP も Oracle 19 ライブラリとともにデプロイして実行すべきです。 PHP のアプリケーションは、それ以外のバージョンの Oracle データベースにも接続できます。 Oracle のクライアントとサーバーの間には、異なるバージョン間での互換性があるからです。

OCI8 を PECL から(pecl コマンド経由で) インストールする

OCI8 拡張機能は、 » PECL リポジトリを使えば既存の PHP のインストールに追加できます。

以下の手順で、自動インストールを行えます

ファイアウォールの後ろにいる場合、以下のようにしてプロキシを設定します:
```
pear config-set http_proxy http://my-proxy.example.com:80/
```
以下を実行します。
```
pecl install oci8
```
PHP 7 以降では、pecl install oci8-2.2.0 とします。
プロンプトが出たら、 $ORACLE_HOME または、 instantclient,/path/to/instant/client/lib を入力して下さい。

注意: $ORACLE_HOME という値を入力しないで下さい。 pecl はそれを展開しないからです。代わりに、展開済みのパスを入力するようにして下さい。たとえば、/opt/oracle/product/19c/dbhome_1 や instantclient,/Users/myname/Downloads/instantclient_19_8 のようなものです。
oci8_dtrace_gen.h: No such file or directory というエラーが発生した場合、 PHP が DTrace を有効にしてビルドされているということです。この場合、以下のようにしてインストールして下さい:
```
$ export PHP_DTRACE=yes
$ pecl install oci8
```
php.ini ファイルを編集し、以下の一行を追加して下さい。
```
extension=oci8.so
```
php.ini のディレクティブ extension_dir が oci8.so をインストールしたディレクトリを差しているかを確認して下さい。

OCI8 を PECL から(phpize 経由で) インストールする

pecl コマンドが利用できない場合に、 OCI8 を既存の PHP のインストールに追加するには、 » PECL OCI8 パッケージを手動でダウンロードして下さい。たとえば、oci8-3.0.0.tgz をダウンロードします。

パッケージを展開します:
```
tar -zxf oci8-3.0.0.tgz
cd oci8-3.0.0
```
パッケージを準備します:
```
phpize
```

$ORACLE_HOME または Instant Client を使ってパッケージを設定します。

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

または

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

パッケージをインストールします:
```
make install
```
oci8_dtrace_gen.h: No such file or directory というエラーが発生した場合、 PHP が DTrace を有効にしてビルドされているということです。この場合、以下のようにして環境変数を設定してから、 configure と make を再実行して下さい。
```
$ export PHP_DTRACE=yes
```
php.ini ファイルを編集し、以下の一行を追加して下さい。
```
extension=oci8.so
```
php.ini のディレクティブ extension_dir が oci8.so をインストールしたディレクトリを差しているかを確認して下さい。

PHP をビルドする際に、OCI8 を共有ライブラリとしてインストールする

PHP をソースコードからビルドしている場合、 OCI8 を共有ライブラリとしてビルドするために shared オプションが使えます。これを使うと、PHP に動的にライブラリを読み込ませることが出来ます。共有ライブありとしてビルドすると、 PHP の本体に影響を与えることなく、OCI8 をアップグレードできます。

以下のオプションを使って、OCI8 を設定できます。

無料の » Oracle Instant Client ライブラリを使っている場合は、以下のようにします:
```
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
```
Instant Client 12.2 (または前のバージョン) が ZIP ファイルからインストールされている場合、ライブラリへのシンボリックリンクが作られていることをまず確認して下さい。たとえば ln -s libclntsh.so.12.1 libclntsh.so のようにします。

RPM を使って Oracle Instant Client をインストールしている場合、 configure コマンドは、以下のようになるでしょう:
```
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
```
--with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib のようにして、オプションを指定します。

注意すべきなのは、PHP ではじめて Oracle Instant Client がサポートされたのは PHP 4.3.11 と 5.0.4 で、その時は --with-oci8-instant-client というオプションが使われていたということです。
Oracle Database を使っているか、 Oracle Client が完全にインストールされている場合は、以下のようにします:
```
./configure --with-oci8=shared,$ORACLE_HOME
```
Webサーバのユーザ (nobody, www) が、ライブラリへのアクセス権を持っていることを確認して下さい。 $ORACLE_HOME 内にある初期化ファイルと (もし使っていれば) tnsnames.ora です。 Oracle 10gR2 を使っている場合、ディレクトリアクセスを与えるために $ORACLE_HOME/install/changePerm.sh を実行する必要があるかもしれません。

設定が終わった後は、いつもの PHP のビルドの手続きに従って下さい。たとえば make install コマンドの実行です。 OCI8 の共有ライブラリ oci8.so が作成されます。このファイルは、PHP の extension ディレクトリに手動で移動する必要があるかもしれません。このディレクトリは、php.ini の extension_dir で指定します。

OCI8 のインストールを完了するには、 php.ini を編集し、以下の一行を追加します。

extension=oci8.so

PHP をビルドする際、OCI8 を静的リンクしてインストールする

PHP をソースコードからビルドしている場合、以下の configure オプションを使って、 OCI8 を静的ライブラリとして PHP に含めることが出来ます。

Oracle Instant Client を使っている場合、以下のようにします:
```
./configure --with-oci8=instantclient,/path/to/instant/client/lib
```
Oracle Database を使っているか、 Oracle Client が完全にインストールされている場合は、以下のようにします:
```
./configure --with-oci8=$ORACLE_HOME
```

設定が終わった後は、いつもの PHP のビルドの手続きに従って下さい。たとえば make install コマンドの実行です。コンパイルが終わった後は、 oci8.so を php.ini に追加する必要はありません。追加のビルドステップも不要です。

Windows で OCI8 をインストールする

OCI8 拡張機能は、 » PECL リポジトリのDLLや、インストールされた PHP の ext ディレクトリにあるライブラリを使うことで追加出来ます。

Oracle 12c (以降) のライブラリを使う場合、 php.ini の extension=php_oci8_12c.dll, extension=php_oci8_11g.dll, extension=php_oci8.dll のいずれかをコメントアウトして下さい。これらの DLL のうち、ひとつだけを1度に有効にできます。バージョンが上のDLLには、より多くの機能が含まれています。必ずしも全てのDLLが、全てのバージョンのPHPで利用できるとは限りません。 extension_dir が、PHP の拡張機能の DLL を含んだディレクトリを指していることを確認して下さい。

もし Instant Client を使用する場合、システムの PATH 環境変数を Oracle ライブラリ・ディレクトリに設定します。

Oracle の実行環境を設定する

このエクステンションを使用する前に、 Web デーモンのユーザーのために Oracle の環境変数が適切に設定されたか確認してください。もし Web サーバーがブート時に自動起動される場合は、ブート時の環境も正しく設定されていることを確認してください。

注意:
PHP スクリプトで putenv() を使って Oracle の環境変数を設定しないでください。それは、スクリプトが実行される前に Oracle のライブラリがロードされて初期化されるかもしれないからです。 putenv() で変数を設定すると、コンフリクト、クラッシュ、または予測出来ない動作の原因となるかもしれません。ある関数は動作し、他の関数は捉えがたいエラーを示すかもしれません。 Web サーバー開始前に変数を設定するべきです。

Red Hat Linux と変種では、 /etc/sysconfig/httpd の最後で変数を export してください。 Apache 2 を伴う他のシステムでは Apache bin ディレクトリーで envvars スクリプトを使用するかもしれません。３番目のオプション、 httpd.conf の Apache SetEnv ディレクティブは、一部のシステムでは動作するかもしれませんが、他のシステムでは不適切であることが知られています。

環境変数が正しく設定されたかチェックするには、 phpinfo() を使って Environment セクション (Apache Environment ではありません) に期待される変数が含まれるかどうかチェックしてください。

必要かもしれない変数が下記の表に含まれます。どんな変数が使えるのかについての詳細は Oracle ドキュメントを参照してください。

**一般的な Oracle 環境変数**
名前	目的
ORACLE_HOME	フルの Oracle データベース・ソフトウェアのディレクトリを含みます。 Oracle Instant Client を使用する際は、これを設定しないでください。設定することは余計なことで、インストール時に問題を引き起こすかもしれませんので。
ORACLE_SID	ローカルマシン上の、接続されるデータベース名を含みます。 Oracle Instant Client を使用するか、または oci_connect() に常に接続パラメータを渡す場合は、この設定は不要です。
LD_LIBRARY_PATH	この値(プラットフォームによっては、 `LIBPATH` や `SHLIB_PATH` の場合があります) を Oracle ライブラリが入っている場所に設定します。たとえば `$ORACLE_HOME/lib` や `/usr/lib/oracle/18.5/client/lib` などです。 Linux 用の Instant Client 19 の ZIP ファイルについては、 `ldconfig` を代わりに使うことで、さらに信頼性があがるよになっています。詳細は Instant Client のインストール手順書を参照して下さい。 Instant Client 19 (またはそれ以降) の RPM ファイルでは、 `ldconfig` が自動で実行されるようになっています。ユーザーによっては、`LD_LIBRARY_PATH` のかわりに `LD_PRELOAD` を使うかもしれません。
NLS_LANG	これは Oracle ライブラリで使用される文字セットや国際化情報を設定するためのプライマリ変数です。
ORA_SDTZ	Oracle セッションのタイムゾーンを設定します。
TNS_ADMIN	`tnsnames.ora` や `sqlnet.ora` のような Oracle Net Service の設定ファイルが置かれたディレクトリを指定します。 oci_connect() に指定する接続文字列が、 `localhost/XE` のような簡易接続の名前付けの文法を使っている場合、この設定は不要です。また、ネットワーク設定ファイルがデフォルトの位置に置かれている場合も不要です。たとえば、 `/usr/lib/oracle/VERSION/client/lib/network/admin`, `$ORACLE_HOME/network/admin`, または `/etc` に置かれている場合です。

頻度は高くありませんが、 TWO_TASK 、 ORA_TZFILE 、及び NLS* や ORA_NLS_* 変数のような様々な Oracle 国際化設定値を含む Oracle 環境変数が使用されます。

トラブルシューティング

OCI8 をインストールする際に最も一般的な問題は、 Oracle 環境が正しく設定されないことです。通常、これは oci_connect() や oci_pconnect() 使用上の問題として現れます。このエラーは Call to undefined function oci_connect() のような PHP エラーや、 ORA-12705 のような Oracle エラー、さらには Apache のクラッシュになるかもしれません。この問題を解決するために、起動時のエラーについて Apache のログファイルをチェックして、上記のセクションをご覧下さい。

ORA-12154 または ORA-12514 のようなネットワークエラーは Oracle のネットワーク・ネーミングまたは構成の問題を示唆する反面、根本の原因は、 PHP 環境が誤って設定されたことや、 Oracle ライブラリが tnsnames.ora 構成ファイルの場所を指定できないためかもしれません。

Windows では、一つのマシン上に Oracle の複数のバージョンを持つと、 PHP が Oracle の正しいバージョンだけを使用することを確認するために注意を払わない限り、すぐにライブラリのクラッシュを引き起こします。

特に Windows 上では、どのライブラリが検索されてロードされるか調べるユーティリティは、欠けていたりクラッシュしているライブラリの問題の解決に役立ちます。

注意: Web サーバーが開始しないか、または起動時にクラッシュする場合

Apache が 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)
libpthread が一覧に表示されなければ、 Apache を再インストールします。
# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install
UnixWare のような一部のシステムでは、それは libpthread の代わりに libthread であることに注意してください。 PHP 及び Apache を EXTRA_LIBS=-lthread とともに構成しなければいけません。