DOCSP-33692: php improvements (#922)

* DOCSP-33692: php improvements

* error fixes

* test

* image width

* image width

* small fix

* vale issues

* JS PR fixes 1

* AB tech review comment

Author: rustagir

source/figures/PHP_driver_architecture.svg

@@ -37,7 +37,6 @@ Standalone Libraries
   use this standalone library or use the `Laravel <https://github.com/abellion/xenus-laravel>`__
   integration, which adds support for failed jobs, migrations, and events.
 
-
 Framework Integrations
 ----------------------
 
@@ -50,7 +49,7 @@ Framework Integrations
 
 - Laravel
 
-  - `Laravel MongoDB <https://github.com/jenssegers/laravel-mongodb>`__ is an
+  - `Laravel MongoDB <https://github.com/mongodb/laravel-mongodb>`__ is an
     Eloquent model and Query builder that supports MongoDB by using the
     original Laravel API. This library extends the original Laravel classes
     and therefore uses the same methods.
@@ -90,5 +89,4 @@ Tools and Projects
   a common way for programs to create, send, and read messages.
 
 - `XHGui <https://github.com/perftools/xhgui>`__ is a web interface for the
-  XHProf profiler, which stores profiling data in MongoDB.
-
+  XHProf profiler, which stores profiling data in MongoDB.

source/php-libraries.txt

@@ -4,8 +4,6 @@
 MongoDB PHP Driver
 ==================
 
-.. default-domain:: mongodb
-
 .. facet::
    :name: programming_language
    :values: php
@@ -28,27 +26,29 @@ MongoDB PHP Driver
    :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 two following components:
 
-- The `extension <https://github.com/mongodb/mongo-php-driver>`_, which
+- The `extension <https://github.com/mongodb/mongo-php-driver>`__, which
   provides a low-level API and mainly serves to integrate
-  `libmongoc and libbson <https://www.mongodb.com/docs/drivers/c/>`_ with
+  :ref:`libmongoc and libbson <c-language-center>` with
   PHP.
 
-- The `library <https://www.mongodb.com/docs/php-library/current>`_, which
+- The `library <https://www.mongodb.com/docs/php-library/current>`__, which
   provides a high-level API for working with MongoDB
   databases consistent with other MongoDB language drivers.
 
 While it is possible to use the extension alone, MongoDB recommends
-using both the extension and the library together. Download the
-components you need or set up a runnable project by following our
-tutorials.
+using both the extension and the library together. To learn more about
+the components of the PHP driver, see the :ref:`Driver Architecture
+<php-driver-arch>` section of this page.
+
+Navigate through the following links to learn more about the driver and access
+tutorial content on setting up a runnable project:
 
 - `Tutorials <https://www.mongodb.com/docs/php-library/current/tutorial>`__
 
@@ -72,6 +72,44 @@ tutorials.
 
   - `Extension <https://github.com/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.pecl.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 :ref:`C Driver
+<c-language-center>` documentation.
+
 Compatibility
 -------------
 
@@ -80,18 +118,17 @@ following environments:
 
 .. include:: /includes/fact-environments.rst
 
-
 Installation
 ------------
 
 First, make sure you have a recent version of PHP installed on your
 system. See the
-`official PHP manual <https://www.php.net/manual/en/install.php>`_
+`official PHP manual <https://www.php.net/manual/en/install.php>`__
 for download and installation instructions.
 
 Install the PHP MongoDB Extension before installing the PHP Library for
 MongoDB. You can install the extension using
-`PECL <https://www.php.net/manual/en/mongodb.installation.pecl.php>`_ on
+`PECL <https://www.php.net/manual/en/mongodb.installation.pecl.php>`__ on
 the command line:
 
 .. code-block:: sh
@@ -110,7 +147,7 @@ Finally, add the following line to your ``php.ini`` file:
    CLI, FPM). Make sure to enable the extension in all SAPIs that you need.
 
 The preferred method of installing the PHP library is with
-`Composer <https://getcomposer.org/>`_ by running the following from your project root:
+`Composer <https://getcomposer.org/>`__ by running the following from your project root:
 
 .. code-block:: sh
 
@@ -126,7 +163,7 @@ Composer's autoloader as in the following example:
    require_once __DIR__ . '/vendor/autoload.php';
 
 Additional installation instructions may be found in the
-`library documentation <https://www.mongodb.com/docs/php-library/current/tutorial/install-php-library/>`_.
+`library documentation <https://www.mongodb.com/docs/php-library/current/tutorial/install-php-library/>`__.
 
 .. _connect-atlas-php-driver:
 
@@ -177,7 +214,7 @@ 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>`_
+`MongoDB\\BSON\\Int64 <https://www.php.net/manual/en/class.mongodb-bson-int64.php>`__
 instance instead of a PHP integer type.
 
 MongoDB Compatibility