php-drivers.txt

.. _php-language-center:

==================
MongoDB PHP Driver
==================

.. facet::
   :name: programming_language
   :values: php

.. facet::
   :name: genre
   :values: tutorial

.. meta:: 
   :description: Use the PHP driver and libraries to connect to MongoDB Atlas, Enterprise, and Community database deployments.
   :keywords: code example

.. toctree::
   :titlesonly:

   Laravel MongoDB <https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current>
   Symfony Integration </php-frameworks/symfony>
   Drupal Integration </php-frameworks/drupal>
   Libraries, Frameworks, & Tools </php-libraries>

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: twocols

Introduction
------------

Welcome to the documentation site for the official MongoDB PHP driver.
You can add the driver to your application to work with MongoDB in PHP.
The MongoDB PHP Driver consists of the following components:

- `Extension <https://php.net/mongodb>`__:
  Provides a low-level API and mainly serves to integrate
  the `libmongoc <https://mongoc.org/libmongoc/current/>`__ and
  `libbson <https://mongoc.org/libbson/current/>`__ libraries with PHP.

- `Library <https://www.mongodb.com/docs/php-library/current>`__:
  Provides a high-level API for working with MongoDB
  databases consistent with other MongoDB language drivers.

While it is possible to use only the extension, we recommend
using the extension and the library together. To learn more about
the components of the PHP driver, see the :ref:`php-driver-arch` section
of this page.

View the following guides to learn more about the driver and access
tutorial content on setting up a runnable project:

- `Get Started with the PHP Library <https://www.mongodb.com/docs/php-library/current/get-started/>`__
- `Connect to MongoDB <https://www.mongodb.com/docs/php-library/current/connect/>`__

Reference
~~~~~~~~~

- :github:`Release Notes <mongodb/mongo-php-driver/releases>`
- :github:`Driver Source Code <mongodb/mongo-php-driver>`

.. _php-driver-arch:

Driver Architecture
-------------------

This section describes how the components of the PHP driver work together.
These components fit into the following general categories:

- High-Level API, which includes the library and other integrations 
- Extension, which includes the extension that integrates the system libraries
- System, which includes the C Driver, BSON library, and encryption library

The following diagram illustrates the architecture of the PHP driver
components:

.. figure:: /figures/PHP_driver_architecture.svg
   :alt: PHP driver component architecture
   :figwidth: 600px
   
The PHP library provides an API that is consistent with the other
MongoDB drivers. The library is continually updated to meet cross-driver
specifications. You must add the library as a dependency to access
MongoDB in most PHP applications.

The extension is distributed by using `PECL
<https://www.php.net/manual/en/mongodb.installation.php>`__, and
connects PHP to the system libraries. The extension's public API
provides the following functionality:

- Connection management
- BSON encoding and decoding
- Object document serialization
- Command execution
- Cursor management

To learn more about the system libraries, see the `C Driver
<https://www.mongodb.com/docs/languages/c/c-driver/current/>`__ documentation.

Connect to a Compatible MongoDB Deployment
------------------------------------------

You can use the PHP driver to connect to deployments hosted in the
following environments:

.. include:: /includes/fact-environments.rst

Installation
------------

Make sure you have a recent version of PHP installed on your
system. See the `PHP manual <https://www.php.net/manual/en/install.php>`__
for download and installation instructions.

Install the PHP MongoDB Extension before you install the MongoDB PHP
Library. You can install the extension by using :github:`pie
</php/pie>` on the command line:

.. code-block:: sh

   pie install mongodb/mongodb-extension

Then, install the PHP library by using `Composer
<https://getcomposer.org/>`__. Run the following command from your
project directory:

.. code-block:: sh

   composer require mongodb/mongodb

After installation completes, ensure that your application includes
Composer's autoloader as shown in the following example:

.. code-block:: php

   <?php

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

The `PHP Library documentation
<https://www.mongodb.com/docs/php-library/current>`__ contains reference
materials and tutorials that demonstrate how to interact with your
MongoDB data.

Compatibility
-------------

Due to potential problems representing 64-bit integers on 32-bit platforms,
users are advised to use 64-bit environments. When using a 32-bit platform, be
aware that any 64-bit integer read from the database will be returned as a
`MongoDB\\BSON\\Int64 <https://www.php.net/manual/en/class.mongodb-bson-int64.php>`__
instance instead of a PHP integer type.

MongoDB Compatibility
~~~~~~~~~~~~~~~~~~~~~

The following compatibility table specifies the recommended version or versions
of the PHP driver for use with a specific version of MongoDB.

The first column lists the driver version.

.. sharedinclude:: dbx/lifecycle-schedule-callout.rst

.. sharedinclude:: dbx/mongodb-compatibility-table-php.rst

Language Compatibility
~~~~~~~~~~~~~~~~~~~~~~

The following compatibility table specifies the recommended version or versions
of the PHP driver for use with a specific version of PHP.

The first column lists the driver versions.

.. sharedinclude:: dbx/language-compatibility-table-php.rst

.. include:: /includes/about-driver-compatibility.rst

.. include:: /includes/help-links-php.rst