From 6456b89bc5533df613d19dcb2906b98d154eec4e Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Wed, 8 Jul 2020 22:12:36 -0400 Subject: [PATCH 1/3] PHPLIB-524 Restructure docs index This revises the intro text and links to PHPLIB and MongoDB tutorials. --- docs/index.txt | 60 +++++++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index 6c3a97406..ffdd4b16f 100644 --- 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 `_, 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 `_. 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 `_ -article in the extension documentation. `Derick Rethans -`_ has also written a series of blog posts entitled -*New MongoDB Drivers for PHP and HHVM*: +New to the PHP Library? +----------------------- -- `Part One: History `_ +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 - `_ +- :doc:`/tutorial/install-php-library` -- `Part Three: Cursor Behaviour - `_ +- :doc:`/tutorial/crud` + +- :doc:`/tutorial/commands` + +- :doc:`/tutorial/gridfs` + +- :doc:`/reference/bson` + +If you have previously worked with the +`legacy PHP driver `_ (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 ` +- :manual:`Introduction to MongoDB ` -- :manual:`What is a MongoDB document? ` +- :manual:`Databases and Collections ` -- :manual:`Dot notation for accessing document properties - ` +- :manual:`Documents ` and + :manual:`BSON Types ` -- :manual:`ObjectId: MongoDB's document identifier ` +- :manual:`MongoDB CRUD Operations ` .. class:: hidden @@ -57,5 +65,3 @@ this documentation: /tutorial /upgrade /reference - -.. /getting-started From add2c8d677e4e4ab543246661f6b2cec946417ff Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Wed, 8 Jul 2020 22:14:24 -0400 Subject: [PATCH 2/3] PHPLIB-523 Document install steps for extension This adds inline instructions for installing the extension in lieu of sending readers to PHP.net. --- docs/tutorial/install-php-library.txt | 100 +++++++++++++++++++------- 1 file changed, 74 insertions(+), 26 deletions(-) diff --git a/docs/tutorial/install-php-library.txt b/docs/tutorial/install-php-library.txt index 0c4098a0c..acaa8ed10 100644 --- 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 `_ (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 ` +(recommended) or +:php:`manually compile from source `. +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 `_ 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 ` -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 -` article. + extension=mongodb.so -Procedure ---------- +Windows users can download precompiled binaries of the extension from +`PECL `_. 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 -`_ 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 `. + +.. 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 `_ 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 -`_. +While not recommended, you may also manually install the library using a source +archive attached to the +`GitHub 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"; + `_ 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. From 8c1a8d4f4a25fd04117624028368fec737bcc334 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Wed, 8 Jul 2020 22:16:10 -0400 Subject: [PATCH 3/3] Fix doc syntax and formatting --- docs/reference/method/MongoDBCollection-createIndex.txt | 2 +- docs/reference/method/MongoDBCollection-deleteMany.txt | 2 +- docs/reference/method/MongoDBCollection-deleteOne.txt | 2 +- docs/tutorial/example-data.txt | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/method/MongoDBCollection-createIndex.txt b/docs/reference/method/MongoDBCollection-createIndex.txt index ff4150eac..4d06b1b09 100644 --- a/docs/reference/method/MongoDBCollection-createIndex.txt +++ b/docs/reference/method/MongoDBCollection-createIndex.txt @@ -82,7 +82,7 @@ exists. 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 index fb84bd99c..df1a1ac81 100644 --- 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 ` command reference in the MongoDB manual diff --git a/docs/reference/method/MongoDBCollection-deleteOne.txt b/docs/reference/method/MongoDBCollection-deleteOne.txt index 27ba5a7c3..0c31bfb5f 100644 --- 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 ` command reference in the MongoDB manual diff --git a/docs/tutorial/example-data.txt b/docs/tutorial/example-data.txt index e9370f2b1..cf3230952 100644 --- 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 `, 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