Установка

Установка 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 (например для macOS: установка по умолчанию, Homebrew и » XAMPP) у каждой версии 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 и запускать предоставленную PHP, установленным через менеджер пакетов Homebrew, команду pecl, как рассказывает стандартная инструкция по установке из репозитория PECL.

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

$ brew install shivammathur/extensions/mongodb@8.4

Обратите внимание, что в brew доступна только последняя версия модуля.

Замечание: Установите необходимые зависимости

Чтобы обеспечить правильную настройку поддержки SSL, убедитесь, что установлены формулы openssl и pkgconf. Если один из этих пакетов отсутствует, модуль будет скомпилирован с Secure Transport, что может привести к проблемам совместимости.

Установка PHP-модуля MongoDB в операционную систему Windows

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

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

extension=php_mongo.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 (например, macOS: установка по умолчанию, Homebrew, » XAMPP) у каждой версии 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