Skip to content

Commit 2948915

Browse files
mongoKartmongoKart
authored
Merge branch 'php-standardization' into docsp-41957-mongo-client
2 parents 915d272 + 474fc1f commit 2948915

16 files changed

+1468
-103
lines changed

‎snooty.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ toc_landing_pages = [
1717
"/reference/class/MongoDBModelCollectionInfo",
1818
"/reference/class/MongoDBModelDatabaseInfo",
1919
"/reference/class/MongoDBModelIndexInfo",
20+
"/get-started",
2021
]
2122

2223
[substitutions]
@@ -25,3 +26,5 @@ php-library = "MongoDB PHP Library"
2526
[constants]
2627
php-library = "MongoDB PHP Library"
2728
driver-short = "PHP library"
29+
mdb-server = "MongoDB Server"
30+
api = "https://www.mongodb.com/docs/php-library/current/reference"

‎source/get-started.txt

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,34 @@ Get Started with the PHP Library
1313
.. facet::
1414
:name: genre
1515
:values: tutorial
16-
16+
1717
.. meta::
1818
:description: Learn how to create an app to connect to MongoDB deployment by using the PHP library.
1919
:keywords: quick start, tutorial, basics
2020

2121
.. toctree::
2222

23+
/get-started/download-and-install/
2324
/get-started/create-a-deployment/
2425
/get-started/create-a-connection-string/
25-
/get-started/next-steps/
26+
/get-started/connect-to-mongodb/
27+
/get-started/next-steps/
28+
29+
Overview
30+
--------
31+
32+
The {+php-library+} is a high-level abstraction for the MongoDB PHP extension, which
33+
you can use to connect to MongoDB and interact with data stored in your deployment.
34+
This guide shows you how to create an application that uses the {+php-library+} to
35+
connect to a MongoDB cluster hosted on MongoDB Atlas and query data in your cluster.
36+
37+
.. tip::
38+
39+
MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
40+
deployments. You can create your own free (no credit card required) MongoDB Atlas
41+
deployment by following the steps in this guide.
42+
43+
Follow this guide to connect a sample PHP application to a MongoDB Atlas
44+
deployment. If you prefer to connect to MongoDB using a different driver or
45+
programming language, see our :driver:`list of official drivers <>`.
46+

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

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
.. _php-connect-to-mongodb:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: test connection, runnable, code example
13+
14+
After retrieving the connection string for your MongoDB Atlas deployment,
15+
you can connect to the deployment from your PHP application and query
16+
the Atlas sample datasets.
17+
18+
.. procedure::
19+
:style: connected
20+
21+
.. step:: Edit your PHP application file
22+
23+
Copy and paste the following code into the ``quickstart.php`` file, which queries
24+
the ``movies`` collection in the ``sample_mflix`` database:
25+
26+
.. literalinclude:: /includes/get-started/quickstart.php
27+
:language: php
28+
:dedent:
29+
30+
.. step:: Assign the connection string
31+
32+
Replace the ``<connection string>`` placeholder with the
33+
connection string that you copied from the :ref:`php-connection-string`
34+
step of this guide.
35+
36+
.. step:: Run your PHP application
37+
38+
In your project directory, run the following shell command to start the application:
39+
40+
.. code-block:: bash
41+
42+
php quickstart.php
43+
44+
The command line output contains details about the retrieved movie
45+
document:
46+
47+
.. code-block:: none
48+
:copyable: false
49+
50+
{
51+
"_id": {
52+
"$oid": "..."
53+
},
54+
...
55+
"rated": "R",
56+
"metacritic": 80,
57+
"title": "The Shawshank Redemption",
58+
...
59+
}
60+
61+
If you encounter an error or see no output, ensure that you specified the
62+
proper connection string in the ``quickstart.php`` file and that you loaded the
63+
sample data.
64+
65+
After you complete these steps, you have a PHP application that
66+
connects to your MongoDB deployment, runs a query on the sample
67+
data, and returns a matching document.
68+
69+
.. include:: /includes/get-started/troubleshoot.rst

‎source/get-started/download-and-install.txt

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
.. _php-download-and-install:
2+
3+
====================
4+
Download and Install
5+
====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: setup, composer, installation, code example
13+
14+
.. procedure::
15+
:style: connected
16+
17+
.. step:: Install dependencies
18+
19+
Before you begin developing, ensure that you have the following
20+
dependencies installed on your local machine:
21+
22+
- `PHP <https://www.php.net/manual/en/install.php>`__ version 7.4 or later
23+
- `Composer <https://getcomposer.org/download/>`__ version 2.0 or later
24+
25+
.. step:: Install the MongoDB PHP extension
26+
27+
Run the following command to install the ``mongodb`` PHP extension:
28+
29+
.. code-block:: bash
30+
31+
sudo pecl install mongodb
32+
33+
.. step:: Update your PHP configuration file
34+
35+
To enable the ``mongodb`` extension in your PHP configuration file, add the
36+
following line to the top of your ``php.ini`` file:
37+
38+
.. code-block:: none
39+
40+
extension=mongodb.so
41+
42+
.. tip::
43+
44+
You can locate your ``php.ini`` file by running the following command
45+
in your shell:
46+
47+
.. code-block:: bash
48+
49+
php --ini
50+
51+
.. step:: Create a project directory
52+
53+
From your root directory, run the following command in your shell to create
54+
a directory called ``php-quickstart`` for this project:
55+
56+
.. code-block:: bash
57+
58+
mkdir php-quickstart
59+
60+
Select the tab corresponding to your operating system and run the following commands
61+
to create a ``quickstart.php`` application file in the ``php-quickstart`` directory:
62+
63+
.. tabs::
64+
65+
.. tab:: macOS / Linux
66+
:tabid: create-file-mac-linux
67+
68+
.. code-block:: bash
69+
70+
cd php-quickstart
71+
touch quickstart.php
72+
73+
.. tab:: Windows
74+
:tabid: create-file-windows
75+
76+
.. code-block:: bash
77+
78+
cd php-quickstart
79+
type nul > quickstart.php
80+
81+
.. step:: Install the {+php-library+}
82+
83+
To install the {+php-library+}, run the following command in your ``php-quickstart``
84+
directory:
85+
86+
.. code-block:: bash
87+
88+
composer require mongodb/mongodb
89+
90+
After installing the library, include Composer's ``autoload.php`` file by adding the
91+
following code to the top of your ``quickstart.php`` file:
92+
93+
.. code-block:: php
94+
95+
<?php
96+
97+
require_once __DIR__ . '/vendor/autoload.php';
98+
99+
After you complete these steps, you have a new project directory, a
100+
new application file, and the library dependencies installed.
101+
102+
.. include:: /includes/get-started/troubleshoot.rst

‎source/includes/get-started/quickstart.php

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
require __DIR__ . '/../vendor/autoload.php';
4+
5+
use MongoDB\Client;
6+
7+
$client = new Client('<connection string>');
8+
$collection = $client->sample_mflix->movies;
9+
10+
$filter = ['title' => 'The Shawshank Redemption'];
11+
$result = $collection->findOne($filter);
12+
13+
if ($result) {
14+
echo json_encode($result, JSON_PRETTY_PRINT);
15+
} else {
16+
echo "Document not found";
17+
}

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
6+
$client = new MongoDB\Client($uri);
7+
8+
// start-db-coll
9+
$collection = $client->sample_restaurants->restaurants;
10+
// end-db-coll
11+
12+
// Retrieves 5 documents that have a "cuisine" value of "Italian"
13+
// start-limit
14+
$cursor = $collection->find(
15+
['cuisine' => 'Italian'],
16+
['limit' => 5]
17+
);
18+
19+
foreach ($cursor as $doc) {
20+
echo json_encode($doc) . PHP_EOL;
21+
}
22+
// end-limit
23+
24+
// Retrieves documents with a "cuisine" value of "Italian" and sorts in ascending "name" order
25+
// start-sort
26+
$cursor = $collection->find(
27+
['cuisine' => 'Italian'],
28+
['sort' => ['name' => 1]]
29+
);
30+
31+
foreach ($cursor as $doc) {
32+
echo json_encode($doc) . PHP_EOL;
33+
}
34+
// end-sort
35+
36+
// Retrieves documents with a "borough" value of "Manhattan" but skips the first 10 results
37+
// start-skip
38+
$cursor = $collection->find(
39+
['borough' => 'Manhattan'],
40+
['skip' => 10]
41+
);
42+
43+
foreach ($cursor as $doc) {
44+
echo json_encode($doc) . PHP_EOL;
45+
}
46+
// end-skip
47+
48+
// Retrieves 5 documents with a "cuisine" value of "Italian", skips the first 10 results,
49+
// and sorts by ascending "name" order
50+
// start-limit-sort-skip
51+
$options = [
52+
'sort' => ['name' => 1],
53+
'limit' => 5,
54+
'skip' => 10,
55+
];
56+
57+
$cursor = $collection->find(['cuisine' => 'Italian'], $options);
58+
foreach ($cursor as $doc) {
59+
echo json_encode($doc) . PHP_EOL;
60+
}
61+
// end-limit-sort-skip
62+
63+
// Returns documents with a "cuisine" value of "Hawaiian" as arrays
64+
// start-return-type
65+
$options = [
66+
'typeMap' => [
67+
'root' => 'array',
68+
'document' => 'array'
69+
]
70+
];
71+
72+
$cursor = $collection->find(['cuisine' => 'Hawaiian'], $options);
73+
foreach ($cursor as $doc) {
74+
print_r($doc) . PHP_EOL;
75+
}
76+
// end-return-type

‎source/includes/read/project.php

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
6+
$client = new MongoDB\Client($uri);
7+
8+
// start-db-coll
9+
$collection = $client->sample_restaurants->restaurants;
10+
// end-db-coll
11+
12+
// Retrieves documents matching the "name" field query and projects their "name", "cuisine", and "borough" values
13+
// start-project-include
14+
$options = [
15+
'projection' => [
16+
'name' => 1,
17+
'cuisine' => 1,
18+
'borough' => 1,
19+
],
20+
];
21+
22+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
23+
foreach ($cursor as $doc) {
24+
echo json_encode($doc) . PHP_EOL;
25+
}
26+
// end-project-include
27+
28+
// Retrieves documents matching the "name" field query
29+
// and projects their "name", "cuisine", and "borough" values while excluding the "_id" values
30+
// start-project-include-without-id
31+
$options = [
32+
'projection' => [
33+
'_id' => 0,
34+
'name' => 1,
35+
'cuisine' => 1,
36+
'borough' => 1,
37+
],
38+
];
39+
40+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
41+
foreach ($cursor as $doc) {
42+
echo json_encode($doc) . PHP_EOL;
43+
}
44+
// end-project-include-without-id
45+
46+
// Retrieves documents matching the "name" field query and excludes their "grades" and "address" values when printing
47+
// start-project-exclude
48+
$options = [
49+
'projection' => [
50+
'grades' => 0,
51+
'address' => 0,
52+
],
53+
];
54+
55+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
56+
foreach ($cursor as $doc) {
57+
echo json_encode($doc) . PHP_EOL;
58+
}
59+
// end-project-exclude

0 commit comments

Comments
 (0)