Сборка PHP совместно с OCI8

Перед сборкой OCI8 изучите предыдущий раздел "Требования".

Перед стартом веб-сервера, OCI8 обычно требуется несколько переменных окружения Oracle (см. ниже) для обнаружения библиотек, конфигурационных файлов и установки некоторых базовых свойств, таких как кодировка, используемая библиотеками Oracle. Эти переменные должны быть установлены перед запуском любого PHP-процесса.

Бинарный файл PHP должен использовать ту же, или более свежую основную версию библиотек Oracle, чем ту, с которой он был собран. Например, если вы собрали OCI8 с библиотеками Oracle 19, то PHP также должен работать с библиотеками Oracle 19. Приложения PHP могут подключаться к другим версиям Oracle Database, так как Oracle имеет клиент-серверную совместимость разных версий.

Установка OCI8 из PECL

Расширение OCI8 может быть включено в текущую установку PHP как автоматически, так и вручную с помощью » PECL.

• Если ваш компьютер находится за файрволлом, установите прокси для PEAR, например:

  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 или $HOME т.к. она не будет развернута. Вместо этого, введите полный путь. Например /opt/oracle/product/19c/dbhome_1 или instantclient,/Users/myname/Downloads/instantclient_19_8.

• Ошибка oci8_dtrace_gen.h: No such file or directory означает, что PHP был собран с поддержкой DTrace Dynamic Tracing. В таком случае устанавливайте так:

  $ export PHP_DTRACE=yes
  $ pecl install oci8
  

• Добавьте в php.ini следующую строку:

  extension=oci8.so
  

  Убедитесь, что oci8.so установлен в директорию, заданную в директиве extension_dir файла php.ini.

Установка OCI8 из PECL с помощью phpize

Если по каким-то причинам нет возможности воспользоваться командой pecl, можно самостоятельно загрузить пакет с сайта » PECL. Например 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
  

  or

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

• Проинсталлируйте:

  make install
  

• Ошибка oci8_dtrace_gen.h: No such file or directory означает, что PHP был собран с поддержкой DTrace Dynamic Tracing. В таком случае перезапустите configure и make, предварительно установив переменную окружения:

  $ export PHP_DTRACE=yes
  

• Добавьте в php.ini следующую строку:

  extension=oci8.so
  

  Убедитесь, что oci8.so установлен в директорию, заданную в директиве extension_dir файла php.ini.

Установка OCI8 в виде подгружаемого (shared) расширения во время сборки PHP

Указание опции конфигурации shared позволяет собрать OCI8 в виде динамически подгружаемой библиотеки. Сборка в виде подгружаемого расширения позволяет легко обновлять OCI8 без пересборки всего PHP.

Соберите OCI8 с помощью одной из следующих опций.

• При использовании бесплатных библиотек »  Oracle Instant Client:

  ./configure --with-oci8=shared,instantclient,/путь/к/instant/client/lib
  

  Если Instant Client 12.2 (или более ранний) установлен из ZIP-архива, не забудьте в первую очередь создать символическую ссылку на библиотеку, например, так: ln -s libclntsh.so.12.1 libclntsh.so.

  Если Oracle Instant Client был установлен с помощью RPM, команда конфигурации будет выглядеть так:

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

  Например, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib

  Учтите, что поддержка Oracle Instant Client появилась только начиная с версий PHP 4.3.11 и 5.0.4 и ранее использовалась с опцией --with-oci8-instant-client.

• При использовании базы данных Oracle database или полной установке Oracle Client:

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

  Убедитесь, что пользователь, под которым запущен веб-сервер, (nobody, www) имеет доступ к библиотекам, файлам инициализации и tnsnames.ora (если используется) в папке $ORACLE_HOME. При использовании Oracle 10gR2, может понадобиться запуск утилиты $ORACLE_HOME/install/changePerm.sh для получения доступа к этой папке.

После настройки следуйте обычной процедуре сборки PHP, например, make install, после чего будет создано подгружаемая библиотека oci8.so. Возможно, вам потребуется вручную перенести ее в папку расширений PHP, указанную опцией extension_dir вашего php.ini.

Для завершения установки OCI8 добавьте следующую строку в php.ini:

extension=oci8.so

Установка OCI8 в виде статически скомпилированного расширения

Сборка PHP со статическим подключением OCI8, используя одну из следующих конфигурационных опций.

• При использовании Oracle Instant Client:

  ./configure --with-oci8=instantclient,/путь/к/instant/client/lib
  

• При использовании базы данных Oracle или полной установке Oracle Client:

  ./configure --with-oci8=$ORACLE_HOME
  

После настройки следуйте обычной процедуре установки PHP, например, make install. После успешной сборки нет необходимости добавлять oci8.so в файл php.ini. Никаких дополнительных шагов сборки больше не требуется.

Установка OCI8 в Windows

Расширение OCI8 можно добавить в PHP с помощью библиотек из репозитория » PECL или из директории ext, содержащейся в вашей инсталляции PHP.

Для библиотек Oracle 12c (и выше), раскомментируйте соответствующую строку в php.ini: extension=php_oci8_12c.dll, extension=php_oci8_11g.dll или extension=php_oci8.dll. Единовременно можно использовать только одну из этих библиотек. Более новые библиотеки могут содержать более продвинутый функционал. Состав доступных библиотек может меняться в зависимости от версии PHP. Убедитесь, что extension_dir указывает на директорию, содержащую библиотеки расширений PHP.

При использовании Instant Client, установите системную переменную окружения PATH на папку с библиотекой Oracle.

Установка окружения Oracle

Перед использованием данного расширения, убедитесь, что переменные окружения Oracle правильно настроены для пользователя, под которым работает веб-сервер. Если ваш веб-сервер автоматически стартует при загрузке, то убедитесь, что окружение при загрузке также настроено корректно.

Замечание:

Не устанавливайте переменные окружения Oracle через putenv() в PHP-скрипте, потому что библиотеки Oracle могут быть загружены и проинициализированы до запуска вашего скрипта. Переменные, установленные через putenv() могут затем вызывать конфликты, падения и прочее непредсказуемое поведение. Некоторые функции могут работать, в то время как другие давать мелкие ошибки. Необходимо устанавливать эти переменные до запуска веб-сервера.

В Red Hat Linux и его вариантах, экспортируйте переменные в конце файла /etc/sysconfig/httpd. Другие системы с Apache 2 могут использовать скрипт envvars из папки bin в дистрибутиве Apache. Третьим вариантом является директива Apache SetEnv в файле httpd.conf, на каких-то системах она может работать, однако, известно, что на некоторых ее недостаточно.

Чтобы удостовериться в корректной настройке переменных окружения, используйте функцию phpinfo() и проверьте, что раздел Environment (не Apache Environment) содержит ожидаемые переменные.

Следующая таблица содержит переменные, которые могут вам потребоваться. За подробностями обо всех доступных переменных обращайтесь к документации Oracle.

Решение проблем

Самой частой проблемой при установке OCI8 является неправильная установка окружения Oracle. Обычно это выражается в проблеме при использовании функций oci_connect() или oci_pconnect(). Ошибка может проявляться в виде ошибок PHP, например, Call to undefined function oci_connect(), ошибок Oracle, таких как ORA-12705, или даже крушения Apache. Проверьте лог-файлы Apache на наличие ошибок запуска и вышеописанные разделы для разрешения этой проблемы.

Несмотря на то, что сетевые ошибки, наподобие ORA-12154 или ORA-12514 сигнализируют об ошибке в именовании или конфигурации сети Oracle, реальной причиной может быть некорректно установленное окружение PHP, из-за чего библиотеки Oracle не могут найти конфигурационный файл tnsnames.ora.

В Windows, использование нескольких версий Oracle на одной машине может легко вызвать их конфликты, которых можно избежать при соблюдении особых мер предосторожности, предусматривающих, что PHP использует корректную версию Oracle.

Утилита, помогающая определить искомые и загруженные в итоге библиотеки, может помочь в случае проблем при отсутствующих или конфликтующих библиотеках, особенно в Windows.

Замечание: Если веб-сервер не стартует или падает при старте

Проверьте, что 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.