Merge branch 'php-standardization' into docsp-41960-tls

Author: mongoKart

snooty.toml

@@ -26,6 +26,7 @@ php-library = "MongoDB PHP Library"
 [constants]
 
 php-library = "MongoDB PHP Library"
+driver-short = "PHP library"
 mdb-server = "MongoDB Server"
-api = "https://www.mongodb.com/docs/php-library/current/reference"
 driver-short = "PHP library"
+api = "https://www.mongodb.com/docs/php-library/current/reference"

source/connect/client.txt

@@ -0,0 +1,105 @@
+.. _php-client:
+
+=======================
+Create a MongoDB Client
+=======================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, Atlas, settings
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+To connect to a MongoDB deployment, you must create the following items:
+
+- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+}
+  which MongoDB deployment to connect to.
+- **MongoDB\\Client** object, which creates the connection to the MongoDB deployment
+  and lets you perform operations on it.
+
+You can also set options within either or both of these components to
+customize the way that the {+driver-short+} behaves
+while connected to MongoDB.
+
+This guide describes the components of a connection string and shows how to
+use a ``MongoDB\Client`` object to connect to a MongoDB deployment.
+
+.. _php-connection-uri:
+
+Connection URI
+--------------
+
+A standard connection string includes the following components:
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Component
+     - Description
+
+   * - ``mongodb://``
+
+     - Required. A prefix that identifies this as a string in the
+       standard connection format.
+
+   * - ``db_username:db_password``
+
+     - Optional. Authentication credentials. If you include these, the client
+       authenticates the user against the database specified in ``authSource``.
+       For more information about the ``authSource`` connection option, see
+       :ref:`php-auth`. 
+
+   * - ``host[:port]``
+
+     - Required. The host and optional port number where MongoDB is running. If you don't
+       include the port number, the driver uses the default port, ``27017``.
+
+   * - ``/defaultauthdb``
+     
+     - Optional. The authentication database to use if the
+       connection string includes ``db_username:db_password@``
+       authentication credentials but not the ``authSource`` option. If you don't include 
+       this component, the client authenticates the user against the ``admin`` database.
+
+   * - ``?<options>``
+
+     - Optional. A query string that specifies connection-specific
+       options as ``<name>=<value>`` pairs. See
+       :ref:`php-connection-options` for a full description of
+       these options.
+
+To learn more about connection strings, see
+:manual:`Connection Strings </reference/connection-string>` in the
+Server manual.
+
+Create a MongoDB\Client
+-----------------------
+
+To create a connection to MongoDB, pass your connection string when constructing
+an instance of the ``MongoDB\Client`` class.
+
+In the following example, the library uses a sample connection URI to connect to a MongoDB 
+deployment on port ``27017`` of ``localhost``:
+
+.. literalinclude:: /includes/connect/client.php
+   :language: php
+   :copyable: true
+
+API Documentation
+-----------------
+
+To learn more about creating a ``MongoDB\Client`` object in the {+driver-short+},
+see the following API documentation:
+
+- :ref:`MongoDB\Client <php-api-mongodbclient>`

source/get-started.txt

@@ -23,6 +23,7 @@ Get Started with the PHP Library
    /get-started/download-and-install/
    /get-started/create-a-deployment/
    /get-started/create-a-connection-string/
+   /get-started/connect-to-mongodb/
    /get-started/next-steps/
 
 Overview

source/get-started/connect-to-mongodb.txt

@@ -0,0 +1,69 @@
+.. _php-connect-to-mongodb:
+
+==================
+Connect to MongoDB
+==================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: test connection, runnable, code example
+
+After retrieving the connection string for your MongoDB Atlas deployment,
+you can connect to the deployment from your PHP application and query
+the Atlas sample datasets.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Edit your PHP application file
+
+      Copy and paste the following code into the ``quickstart.php`` file, which queries
+      the ``movies`` collection in the ``sample_mflix`` database:
+
+      .. literalinclude:: /includes/get-started/quickstart.php
+         :language: php
+         :dedent:
+
+   .. step:: Assign the connection string
+
+      Replace the ``<connection string>`` placeholder with the 
+      connection string that you copied from the :ref:`php-connection-string`
+      step of this guide.
+
+   .. step:: Run your PHP application
+
+      In your project directory, run the following shell command to start the application:
+      
+      .. code-block:: bash
+
+         php quickstart.php
+
+      The command line output contains details about the retrieved movie
+      document:
+
+      .. code-block:: none
+         :copyable: false
+
+         {
+             "_id": {
+                 "$oid": "..."
+             },
+             ...
+            "rated": "R",
+            "metacritic": 80,
+            "title": "The Shawshank Redemption",
+            ...
+         }
+
+      If you encounter an error or see no output, ensure that you specified the
+      proper connection string in the ``quickstart.php`` file and that you loaded the
+      sample data.
+
+After you complete these steps, you have a PHP application that
+connects to your MongoDB deployment, runs a query on the sample
+data, and returns a matching document.
+
+.. include:: /includes/get-started/troubleshoot.rst

source/includes/connect/client.php

@@ -0,0 +1,3 @@
+<?php
+
+$client = new MongoDB\Client("mongodb://localhost:27017");

source/includes/get-started/quickstart.php

@@ -0,0 +1,17 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use MongoDB\Client;
+
+$client = new Client('<connection string>');
+$collection = $client->sample_mflix->movies;
+
+$filter = ['title' => 'The Shawshank Redemption'];
+$result = $collection->findOne($filter);
+
+if ($result) {
+    echo json_encode($result, JSON_PRETTY_PRINT);
+} else {
+    echo "Document not found";
+}

source/includes/read/limit-skip-sort.php

@@ -0,0 +1,76 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$client = new MongoDB\Client($uri);
+
+// start-db-coll
+$collection = $client->sample_restaurants->restaurants;
+// end-db-coll
+
+// Retrieves 5 documents that have a "cuisine" value of "Italian"
+// start-limit
+$cursor = $collection->find(
+    ['cuisine' => 'Italian'],
+    ['limit' => 5]
+);
+
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-limit
+
+// Retrieves documents with a "cuisine" value of "Italian" and sorts in ascending "name" order
+// start-sort
+$cursor = $collection->find(
+    ['cuisine' => 'Italian'], 
+    ['sort' => ['name' => 1]]
+);
+
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-sort
+
+// Retrieves documents with a "borough" value of "Manhattan" but skips the first 10 results
+// start-skip
+$cursor = $collection->find(
+    ['borough' => 'Manhattan'],
+    ['skip' => 10]
+);
+
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-skip
+
+// Retrieves 5 documents with a "cuisine" value of "Italian", skips the first 10 results,
+// and sorts by ascending "name" order
+// start-limit-sort-skip
+$options = [
+    'sort' => ['name' => 1],
+    'limit' => 5,
+    'skip' => 10,
+];
+
+$cursor = $collection->find(['cuisine' => 'Italian'], $options);
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-limit-sort-skip
+
+// Returns documents with a "cuisine" value of "Hawaiian" as arrays
+// start-return-type
+$options = [
+    'typeMap' => [
+        'root' => 'array', 
+        'document' => 'array'
+    ]
+];
+
+$cursor = $collection->find(['cuisine' => 'Hawaiian'], $options);
+foreach ($cursor as $doc) {
+    print_r($doc) . PHP_EOL;
+}
+// end-return-type