Merge branch 'v1.4' into v1.5

jmikola · jmikola · commit a5be07f40249 · 2020-07-09T07:57:16.000-04:00
diff --git a/docs/index.txt b/docs/index.txt
@@ -8,45 +8,53 @@ The |php-library| provides a high-level abstraction around the lower-level
 `PHP driver <https://php.net/mongodb>`_, also known as the ``mongodb``
 extension.
 
-While the ``mongodb`` extension provides a limited API for executing commands,
-queries, and write operations, the |php-library| implements an API similar to
-that of the `legacy PHP driver <http://php.net/manual/en/book.mongo.php>`_. The
-library contains abstractions for client, database, and collection objects, and
-provides methods for CRUD operations and common commands such as index and
-collection management.
+The ``mongodb`` extension provides a limited API to connect to the database and
+execute generic commands, queries, and write operations. In contrast, the
+|php-library| provides a full-featured API and models client, database, and
+collection objects. Each of those classes provide various helper methods for
+performing operations in context. For example, :phpclass:`MongoDB\\Collection`
+implements methods for executing CRUD operations and managing indexes on the
+collection, among other things.
 
 If you are developing a PHP application with MongoDB, you should consider using
-this library, or another high-level abstraction, instead of the extension alone.
+the |php-library| instead of the extension alone.
 
-For additional information about this library and the ``mongodb`` extension, see
-the `Architecture Overview <http://php.net/manual/en/mongodb.overview.php>`_
-article in the extension documentation. `Derick Rethans
-<http://derickrethans.nl/>`_ has also written a series of blog posts entitled
-*New MongoDB Drivers for PHP and HHVM*:
+New to the PHP Library?
+-----------------------
 
-- `Part One: History <https://derickrethans.nl/new-drivers.html>`_
+If you have some experience with MongoDB but are new to the PHP library, the
+following pages should help you get started:
 
-- `Part Two: Architecture
-  <https://derickrethans.nl/new-drivers-part2.html>`_
+- :doc:`/tutorial/install-php-library`
 
-- `Part Three: Cursor Behaviour
-  <https://derickrethans.nl/new-drivers-part3-cursor.html>`_
+- :doc:`/tutorial/crud`
+
+- :doc:`/tutorial/commands`
+
+- :doc:`/tutorial/gridfs`
+
+- :doc:`/reference/bson`
+
+If you have previously worked with the
+`legacy PHP driver <http://php.net/manual/en/book.mongo.php>`_ (i.e. ``mongo``
+extension), it will be helpful to review the :doc:`/upgrade` for a summary of
+API changes between the old driver and this library.
 
 New to MongoDB?
 ---------------
 
-If you are a new MongoDB user, these links should help you become more familiar
-with MongoDB and introduce some of the concepts and terms you will encounter in
-this documentation:
+If you are a new MongoDB user, the following links should help you become more
+familiar with MongoDB and introduce some of the concepts and terms you will
+encounter in the library documentation:
 
-- :manual:`Introduction to CRUD operations in MongoDB </core/crud>`
+- :manual:`Introduction to MongoDB </introduction>`
 
-- :manual:`What is a MongoDB document? </core/document>`
+- :manual:`Databases and Collections </core/databases-and-collections>`
 
-- :manual:`Dot notation for accessing document properties
-  </core/document/#dot-notation>`
+- :manual:`Documents </core/document>` and
+  :manual:`BSON Types </reference/bson-types>`
 
-- :manual:`ObjectId: MongoDB's document identifier </reference/object-id/>`
+- :manual:`MongoDB CRUD Operations </crud>`
 
 .. class:: hidden
 
@@ -57,5 +65,3 @@ this documentation:
       /tutorial
       /upgrade
       /reference
-
-.. /getting-started
diff --git a/docs/reference/method/MongoDBCollection-createIndex.txt b/docs/reference/method/MongoDBCollection-createIndex.txt
@@ -82,7 +82,7 @@ exists.
 
    <?php
 
-   $collection = (new MongoDB\Client)->selectCollection('test, 'restaurants');
+   $collection = (new MongoDB\Client)->selectCollection('test', 'restaurants');
 
    $indexName = $collection->createIndex(
       ['borough' => 1],
diff --git a/docs/reference/method/MongoDBCollection-deleteMany.txt b/docs/reference/method/MongoDBCollection-deleteMany.txt
@@ -78,5 +78,5 @@ See Also
 - :phpmethod:`MongoDB\\Collection::deleteOne()`
 - :phpmethod:`MongoDB\\Collection::bulkWrite()`
 - :doc:`/tutorial/crud`
-- :manual:`delete </reference/command/delete` command reference in the MongoDB
+- :manual:`delete </reference/command/delete>` command reference in the MongoDB
   manual
diff --git a/docs/reference/method/MongoDBCollection-deleteOne.txt b/docs/reference/method/MongoDBCollection-deleteOne.txt
@@ -80,5 +80,5 @@ See Also
 - :phpmethod:`MongoDB\\Collection::deleteMany()`
 - :phpmethod:`MongoDB\\Collection::bulkWrite()`
 - :doc:`/tutorial/crud`
-- :manual:`delete </reference/command/delete` command reference  in the MongoDB
+- :manual:`delete </reference/command/delete>` command reference  in the MongoDB
   manual
diff --git a/docs/tutorial/example-data.txt b/docs/tutorial/example-data.txt
@@ -39,7 +39,7 @@ The output would then resemble::
 You may also import the datasets using :manual:`mongoimport
 </reference/program/mongoimport>`, which is included with MongoDB:
 
-.. code-block:: none
+.. code-block:: sh
 
-   $ mongoimport --db test --collection zips --file zips.json --drop
-   $ mongoimport --db test --collection restaurants --file primer-dataset.json --drop
+   mongoimport --db test --collection zips --file zips.json --drop
+   mongoimport --db test --collection restaurants --file primer-dataset.json --drop
diff --git a/docs/tutorial/install-php-library.txt b/docs/tutorial/install-php-library.txt
@@ -4,55 +4,103 @@ Install the |php-library|
 
 .. default-domain:: mongodb
 
-Prerequisites
--------------
+.. 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:
 
-The |php-library| is a high-level abstraction for the MongoDB PHP driver. As
-such, you must install the `mongodb` extension to use the library.
+.. 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
 
-:php:`Installing the MongoDB PHP Driver <manual/en/mongodb.installation.php>`
-describes how to install the `mongodb` extension for PHP. Instructions for
-installing the driver for HHVM may be found in the :php:`Installation with HHVM
-<manual/en/mongodb.installation.hhvm>` article.
+   extension=mongodb.so
 
-Procedure
----------
+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:
 
-Install the Library
-~~~~~~~~~~~~~~~~~~~
+.. code-block:: ini
 
-The preferred method of installing |php-library| is with `Composer
-<https://getcomposer.org/>`_ by running the following from your project
-root:
+   extension=php_mongodb.dll
+
+Windows binaries are available for various combinations of PHP version,
+thread-safety, and architecture. Failure to select the correct binary will
+result in an error attempting to load the extension DLL at runtime. Additional
+considerations for Windows are discussed in the
+:php:`Windows installation documentation <manual/en/mongodb.installation.windows.php>`.
+
+.. note::
+
+   If your system has multiple versions of PHP installed, each version will have
+   its own ``pecl`` command and ``php.ini`` file. Additionally, PHP may also use
+   separate ``php.ini`` files for its web and CLI environments. If the extension
+   has been installed but is not available at runtime, double-check that you
+   have used the correct ``pecl`` command (or binary in the case of Windows) and
+   have modified the appropriate ``php.ini`` file(s).
+
+Installing the Library
+----------------------
+
+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
 
-While not recommended, you may also manually install the package via
-the source tarballs attached to the `GitHub releases
-<https://github.com/mongodb/mongo-php-library/releases>`_.
+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>`_.
 
 Configure Autoloading
 ~~~~~~~~~~~~~~~~~~~~~
 
-Once you have installed the library, ensure that your application
-includes Composer's autoloader. The ``require_once``
-statement should point to Composer's autoloader, as in the following example:
+Once you have installed the library, ensure that your application includes
+Composer's autoloader as in the following example:
 
 .. code-block:: php
 
-   require_once __DIR__ . "/vendor/autoload.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.
 
-If you installed the library manually from a source tarball, you
-will also need to manually configure autoloading:
+If you installed the library manually from a source archive, you will need to
+manually configure autoloading:
 
 #. Map the top-level ``MongoDB\`` namespace to the ``src/`` directory
    using your preferred autoloader implementation.
 
-#. Manually require the ``src/functions.php`` file, since PHP does not
-   yet support function autoloading.
+#. Manually require the ``src/functions.php`` file. This is necessary because
+   PHP does not support autoloading for functions.
