=========================
Install the |php-library|
=========================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

The |php-library| is a high-level abstraction for the
`PHP driver <https://php.net/mongodb>`_ (i.e. ``mongodb`` extension). This page
will briefly explain how to install both the ``mongodb`` extension and the
|php-library|.

Installing the Extension
------------------------

Linux, Unix, and macOS users can either
:php:`install the extension with PECL <manual/en/mongodb.installation.pecl.php>`
(recommended) or
:php:`manually compile from source <manual/en/mongodb.installation.manual.php>`.
The following command may be used to install the extension with PECL:

.. code-block:: sh

   sudo pecl install mongodb

.. note::

   If the build process for either installation method fails to find a TLS
   library, check that the development packages (e.g. ``libssl-dev``) and
   `pkg-config <https://en.wikipedia.org/wiki/Pkg-config>`_ are both installed.

Once the extension is installed, add the following line to your ``php.ini``
file:

.. code-block:: ini

   extension=mongodb.so

Windows users can download precompiled binaries of the extension from
`PECL <https://pecl.php.net/package/mongodb>`_. After extracting the
``php_mongodb.dll`` file to PHP's extension directory, add the following line to
your ``php.ini`` file:

.. code-block:: ini

   extension=php_mongodb.dll

Additional considerations for Windows are discussed in the
:php:`Windows installation documentation <manual/en/mongodb.installation.windows.php>`.

Installing the Library
----------------------

Using Composer
~~~~~~~~~~~~~~

The preferred method of installing the |php-library| is with
`Composer <https://getcomposer.org/>`_ by running the following command from
your project root:

.. code-block:: sh

   composer require mongodb/mongodb

Once you have installed the library, ensure that your application includes
Composer's autoloader as in the following example:

.. code-block:: php

   <?php

   require_once __DIR__ . '/vendor/autoload.php';

Refer to Composer's `autoloading documentation
<https://getcomposer.org/doc/01-basic-usage.md#autoloading>`_ for more
information about setting up autoloading.

Manual Installation Without Composer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

While not recommended, you may also manually install the library using a source
archive attached to the
`GitHub releases <https://github.com/mongodb/mongo-php-library/releases>`_. When
installing the library without Composer, you must ensure that all library
classes *and* functions are loaded for your application:

#. If you are using a `PSR-4 <https://www.php-fig.org/psr/psr-4/>`_ autoloader,
   map the top-level ``MongoDB\`` namespace to the ``src/`` directory. If you
   are not using an autoloader, manually require _all_ class files found
   recursively within the ``src/`` directory.

#. Regardless of whether you are using an autoloader, manually require the
   ``src/functions.php`` file. This is necessary because PHP does not support
   autoloading for functions.
