## Installation

## Installer l'extension de MongoDB PHP avec PIE

> Note: L'installeur d'Extensions pour PHP (PHP Installer for Extensions - PIE) est un nouvel outil qui remplacera PECL. Nous recommandons d'utiliser PIE pour installer les extensions. Plus d'informations sur » https://github.com/php/pie

Pour installer l'extension MongoDB avec PIE, exécutez la commande suivante :

    pie install mongodb/mongodb-extension

## Installer l'extension de MongoDB PHP avec PECL

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/mongodb

Linux, Unix et les utilisateurs de macOS peuvent exécuter la commande suivante pour installer l'extension :

    $ sudo pecl install mongodb

Sur les systèmes avec plusieurs versions de PHP installées (par exemple, macOS par défaut, Homebrew), chaque version de PHP aura sa propre commande pecl et fichier php.ini. De plus, chaque environnement PHP (par exemple CLI, web) peut utiliser des fichiers php.ini séparés.

Depuis la version 1.17.0 de l'extension, PECL demandera diverses options de `configure`. Pour installer l'extension avec les options par défaut dans un script non interactif, une entrée vide peut être envoyée à `pecl install` en utilisant la commande `yes` :

    $ yes '' | sudo pecl install mongodb

Une liste complète des options `configure` supportées peut être trouvée dans le fichier `package.xml` inclus dans le paquet PECL. Pour installer l'extension avec des options de `configure` spécifiques dans un script non interactif, l'option `--configureoptions` pour `pecl install` peut être utilisée :

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

Par défaut l'installation de l'extension via PECL utilisera les versions incluses de » libbson, » libmongoc, et » libmongocrypt et essayera automatiquement de configurer.

> Note: Si le processus de construction échoue à trouver une bibliothèque SSL, vérifiez que les paquets de développement (par exemple `libssl-dev`) et » pkg-config sont tous deux installés. Si cela ne résout pas le problème, envisagez d'utiliser le processus d'installation manuel.

Pour finir, ajoutez la ligne suivante au fichier php.ini pour chaque environnement qui aura besoin d'utiliser l'extension :

    extension=mongodb.so

## Installer l'extension de MongoDB PHP sur macOS avec Homebrew

» Homebrew 1.5.0 a déprécié le » tap Homebrew/php et a supprimé les formules pour les extensions PHP individuelles. À l'avenir, les utilisateurs de macOS sont invités à installer la formule » php et à suivre les instructions d'installation standard de PECL en utilisant la commande pecl fournie par l'installation PHP Homebrew.

Sinon, le » tap shivammathur/extensions fourni des formules pour les extensions PHP individuelles. Par exemple, pour installer l'extension pour PHP 8.4, exécutez :

    $ brew install shivammathur/extensions/mongodb@8.4

Il est à noter que seule la dernière version de l'extension est disponible dans brew.

> Note: Installer les dépendances requises
> Pour garantir que le support SSL peut être configuré correctement, il faut s'assurer que les formules `openssl` et `pkgconf` sont installées. Si l'un de ces paquets est manquant, l'extension sera compilée avec Secure Transport, ce qui peut entraîner des problèmes de compatibilité.

## Installer l'extension de MongoDB PHP sur Windows

Les binaires précompilés sont attachés aux » versions Github du projet. Les archives sont publiées pour diverses combinaisons de version PHP, de sécurité des threads (TS ou NTS) et d'architecture (x86 ou x64). Déterminez l'archive correcte pour l'environnement PHP et extrayez le fichier php_mongodb.dll dans le répertoire d'extension ("ext" par défaut).

Ajouter la ligne suivante au fichier php.ini pour chaque environnement qui aura besoin d'utiliser l'extension :

    extension=php_mongodb.dll

L'échec de sélection du binaire correct entraînera une erreur lors de la tentative de chargement de l'extension DLL à l'exécution :

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

Il faut s'assurer que la DLL téléchargée correspond aux propriétés d'exécution PHP suivantes :

- Version de PHP(`PHP_VERSION`)
- Sécurité des threads (`PHP_ZTS`)
- Architecture (`PHP_INT_SIZE`)

En plus des constantes mentionnées ci-dessus, ces propriétés peuvent également être déduites de phpinfo(). Si un système a plusieurs exécutions PHP installées, vérifiez que la sortie de phpinfo() est pour l'environnement correct.

> Note: Dépendances additionnelles DLL pour les utilisateurs Windows
> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : libsasl.dll

## Installation manuelle de l'extension de MongoDB PHP

Pour les développeurs et les utilisateurs intéressés par les dernières corrections de bogues, l'extension peut être compilée à partir du dernier code source sur » Github. Exécuter les commandes suivantes pour cloner et construire le projet :

    $ 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

Sur les systèmes avec plusieurs versions de PHP installées (par exemple, macOS par défaut, Homebrew), chaque version de PHP aura sa propre commande phpize et fichier php.ini. De plus, chaque environnement PHP (par exemple CLI, web) peut utiliser des fichiers php.ini séparés.

Par défaut, l'extension utilisera les versions incluses de » libbson, » libmongoc, et » libmongocrypt et essayera de configurer automatiquement. Si ces bibliothèques sont déjà installées en tant que bibliothèques système, l'extension peut les utiliser en spécifiant `--with-mongodb-system-libs=yes` comme option à `configure`.

Pour une liste complète des options `configure`, exécutez configure --help.

Lorsqu'on utilise les versions groupées de libmongoc et libmongocrypt, l'extension tentera également de sélectionner une bibliothèque SSL selon l'option `configure` `--with-mongodb-ssl`. À partir de la version 1.17.0 de l'extension, OpenSSL est toujours préféré par défaut. Auparavant, Secure Transport était le défaut sur macOS et OpenSSL était le défaut sur toutes les autres plates-formes.

> Note: Si le processus de construction échoue à trouver une bibliothèque SSL, vérifiez que les paquets de développement (par exemple `libssl-dev`) et » pkg-config sont tous deux installés. Lorsqu'on utilise Homebrew sur macOS, il est courant qu'un système ait plusieurs versions d'OpenSSL installées. Pour garantir que la version d'OpenSSL souhaitée est sélectionnée, la variable d'environnement `PKG_CONFIG_PATH` peut être utilisée pour contrôler le chemin de recherche de `pkg-config`.

La dernière étape de construction, make install, indiquera où mongodb.so a été installé, similaire à :

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

Il faut s'assurer que l'option extension_dir dans php.ini pointe vers le répertoire où mongodb.so a été installé. L'option peut être interrogée en exécutant :

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

Si les répertoires diffèrent, modifiez extension_dir dans php.ini ou déplacez manuellement mongodb.so dans le répertoire correct.

Pour finir, ajoutez la ligne suivante au fichier php.ini pour chaque environnement qui aura besoin d'utiliser l'extension :

    extension=mongodb.so

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open