Установка PHP-модуля MongoDB через пакетный менеджер PIE

Замечание: Установщик PHP-модулей (англ. PHP Installer for Extensions, PIE) — новый инструмент, который заменит репозиторий PECL после устаревания. Рекомендуем устанавливать модули через PIE. Дополнительная информация доступна на странице » https://github.com/php/pie.

Для установки модуля MongoDB через PIE запускают следующую команду:

pie install mongodb/mongodb-extension

Установка PHP-модуля MongoDB через репозиторий PECL

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/mongodb

Пользователи Linux, Unix и macOS запускают следующую команду для установки модуля:

$ sudo pecl install mongodb

На системах с несколькими установленными версиями PHP, например на macOC — встроенная и Homebrew-версия PHP, — каждая версия получит свою команду pecl и файлы php.ini, при этом для каждого PHP-окружения — CLI, web или другое — предусмотрены отдельные файлы php.ini.

Начиная с версии модуля 1.17.0 PECL будет запрашивать разные настройки configure. Чтобы установить модуль с параметрами по умолчанию в неинтерактивном скрипте, команду yes с вводом пустой строки присоединяют через символ вертикальной черты к команде pecl install:

$ yes '' | sudo pecl install mongodb

Полный список поддерживаемых параметров configure доступен в файле package.xml, который включили в пакет PECL. Чтобы установить модуль со специфичными параметрами configure в неинтерактивном сценарии, указывают параметр --configureoptions для команды pecl install:

$ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb

По умолчанию установка модуля через PECL работает со встроенными версиями библиотек: » libbson, » libmongoc, » libmongocrypt и попытается сконфигурировать их автоматически.

Замечание: Когда процесс установки не находит библиотеку SSL, проверяют, что установили пакеты для разработки наподобие libssl-dev и пакет » pkg-config. Проводят ручную установку, если это не помогает.

И наконец, добавляют следующую строку в файл php.ini для каждого окружения, в котором будет работать модуль:

extension=mongodb.so

Установка PHP-модуля MongoDB в операционную систему macOS через менеджер пакетов Homebrew

Начиная с » Homebrew 1.5.0 репозиторий » Homebrew/php tap объявили устаревшим, а формулы для отдельных модулей PHP удалили. Пользователям macOS рекомендуют устанавливать формулу » php и запускать команду pecl из Homebrew-версии PHP, как рассказывает стандартная инструкция по установке из репозитория PECL.

Альтернативно в репозитории » shivammathur/extensions tap доступны формулы для отдельных PHP-модулей. Например, для установки модуля для PHP 8.4 выполняют команду:

$ brew install shivammathur/extensions/mongodb@8.4

Замечание: Установка обязательных зависимостей
Для правильной настройки сборки и поддержки модулем протокола SSL потребуется установить формулы openssl и pkgconf, иначе модуль скомпилируется с Apple-библиотекой Secure Transport, которая часто вызывает проблемы совместимости.

Установка PHP-модуля MongoDB в ОС Windows

Предварительно скомпилированные исполняемые файлы прикрепляются к » выпускам проекта на GitHub. Архивы публикуются для разных комбинаций версии PHP, потоковой безопасности (TS или NTS) и архитектуры (x86 или x64). Определите правильный архив для PHP-окружения и извлеките файл php_mongodb.dll в директорию с модулями (по умолчанию "ext").

Добавьте следующую строку в файл php.ini для каждого окружения, в котором будет работать модуль:

extension=php_mongodb.dll

Неправильный выбор двоичного файла вызовет ошибку при попытке загрузить DLL-модуль во время выполнения:

PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Убедитесь, что загруженный DLL-файл соответствует следующим свойствам среды выполнения PHP:

• Версия PHP (PHP_VERSION)
• Потоковая безопасность (PHP_ZTS)
• Архитектура (PHP_INT_SIZE)

Просмотр этих свойств, кроме констант, доступен также в выводе функции phpinfo(). Дважды проверьте, что вывод функции phpinfo() соответствует окружению, если в систему установили несколько версий PHP.

Замечание: Дополнительные DLL-зависимости для пользователей Windows
Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: libsasl.dll

Сборка PHP-драйвера MongoDB из исходного кода

Разработчики и пользователи, которые заинтересованы в последних исправлениях ошибок, компилируют модуль из последнего исходного кода » на сайте GitHub. Запустите следующие команды, чтобы клонировать и собрать проект:

$ git clone https://github.com/mongodb/mongo-php-driver.git
$ cd mongo-php-driver
$ git submodule update --init
$ phpize
$ ./configure
$ make all
$ sudo make install

На системах с несколькими установленными версиями PHP, например на macOC — встроенная и Homebrew-версия PHP, — каждая версия получит свою команду phpize и файлы php.ini, при этом для каждого PHP-окружения — CLI, web или другое — предусмотрены отдельные файлы php.ini.

По умолчанию модуль работает со встроенными версиями библиотек » libbson, » libmongoc и » libmongocrypt и попытается настроить библиотеки автоматически. Библиотеки доступны модулю через передачу параметра --with-mongodb-system-libs=yes команде configure, если эти библиотеки уже установили в систему.

Полный список параметров команды configure получают через запуск команды: configure --help.

При работе со встроенными версиями библиотек libmongoc и libmongocrypt, модуль также попытается выбрать SSL-библиотеку в соответствии с параметром --with-mongodb-ssl команды configure. Начиная с версии модуля 1.17.0 по умолчанию предпочтение отдаётся библиотеке OpenSSL. Предыдущие версии драйвера на системах с macOS по умолчанию выбирали Secure Transport, а на остальных платформах — OpenSSL.

Замечание: Потребуется проверить, установили ли пакеты для разработки наподобие libssl-dev и пакет » pkg-config, если процесс установки не найдёт SSL-библиотеку. Система часто содержит набор версий библиотеки OpenSSL, когда пакетами на macOS управляют через утилиту Homebrew. Дополнительный путь, по которому программа pkg-config будет искать файлы, указывают в переменной среды PKG_CONFIG_PATH, чтобы выбрать правильную версию библиотеки OpenSSL.

На последнем, финальном шаге, команда make install выведет путь, по которому собрали модуль mongodb.so. Например, вот так:

Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/

Убедитесь, что директива extension_dir файла php.ini указывает на каталог, в котором лежит модуль mongodb.so. Значение директивы проверяют вот так:

$ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                   /usr/lib/php/extensions/debug-non-zts-20220829

Значение директивы extension_dir изменяют в файле php.ini или просто перемещают файл mongodb.so в правильную директорию, если директории отличаются.

И наконец, добавьте следующую строку в файл php.ini для каждого окружения, в котором планируется использовать модуль:

extension=mongodb.so