Skip to content

Commit 6c5e9c7

Browse files
norareidynorareidy
committed
Merge remote-tracking branch 'upstream/php-standardization' into DOCSP-41970-delete
2 parents 7d0e33d + 3362eb1 commit 6c5e9c7

24 files changed

+1423
-19
lines changed

‎build.sh

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# ensures that we always use the latest version of the script
2+
if [ -f build-site.sh ]; then
3+
rm build-site.sh
4+
fi
5+
6+
7+
curl https://raw.githubusercontent.com/mongodb/docs-worker-pool/netlify-poc/scripts/build-site.sh -o build-site.sh
8+
sh build-site.sh

‎netlify.toml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[[integrations]]
2+
name = "snooty-cache-plugin"
3+
4+
# Production context: all deploys from the Production branch
5+
# set in your site’s Branches settings in the UI will inherit
6+
# these settings.
7+
[build]
8+
publish = "snooty/public"
9+
command = ". ./build.sh"

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,9 @@ toc_landing_pages = [
2424
php-library = "MongoDB PHP Library"
2525

2626
[constants]
27-
2827
php-library = "MongoDB PHP Library"
2928
driver-short = "PHP library"
29+
stable-api = "Stable API"
3030
mdb-server = "MongoDB Server"
3131
api = "https://www.mongodb.com/docs/php-library/current/reference"
32+
php-manual = "https://www.php.net/manual/en"

‎source/aggregation.txt

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.. _php-aggregation:
2+
3+
====================================
4+
Transform Your Data with Aggregation
5+
====================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, transform, computed, pipeline
13+
:description: Learn how to use the PHP library to perform aggregation operations.
14+
15+
.. contents:: On this page
16+
:local:
17+
:backlinks: none
18+
:depth: 2
19+
:class: singlecol
20+
21+
.. TODO:
22+
.. toctree::
23+
:titlesonly:
24+
:maxdepth: 1
25+
26+
/aggregation/aggregation-tutorials
27+
28+
Overview
29+
--------
30+
31+
In this guide, you can learn how to use the {+php-library+} to perform
32+
**aggregation operations**.
33+
34+
Aggregation operations process data in your MongoDB collections and
35+
return computed results. The MongoDB Aggregation framework, which is
36+
part of the Query API, is modeled on the concept of data processing
37+
pipelines. Documents enter a pipeline that contains one or more stages,
38+
and this pipeline transforms the documents into an aggregated result.
39+
40+
An aggregation operation is similar to a car factory. A car factory has
41+
an assembly line, which contains assembly stations with specialized
42+
tools to do specific jobs, like drills and welders. Raw parts enter the
43+
factory, and then the assembly line transforms and assembles them into a
44+
finished product.
45+
46+
The **aggregation pipeline** is the assembly line, **aggregation stages** are the
47+
assembly stations, and **operator expressions** are the
48+
specialized tools.
49+
50+
Aggregation Versus Find Operations
51+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52+
53+
You can use find operations to perform the following actions:
54+
55+
- Select which documents to return
56+
- Select which fields to return
57+
- Sort the results
58+
59+
You can use aggregation operations to perform the following actions:
60+
61+
- Run find operations
62+
- Rename fields
63+
- Calculate fields
64+
- Summarize data
65+
- Group values
66+
67+
Limitations
68+
~~~~~~~~~~~
69+
70+
Consider the following limitations when performing aggregation operations:
71+
72+
- Returned documents cannot violate the
73+
:manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
74+
of 16 megabytes.
75+
- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
76+
limit by creating an options array that sets the ``allowDiskUse`` option to ``true``
77+
and passing the array to the ``MongoDB\Collection::aggregate()`` method.
78+
79+
.. important:: $graphLookup Exception
80+
81+
The :manual:`$graphLookup
82+
</reference/operator/aggregation/graphLookup/>` stage has a strict
83+
memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
84+
85+
.. _php-aggregation-example:
86+
87+
Aggregation Example
88+
-------------------
89+
90+
.. note::
91+
92+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
93+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
94+
free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas
95+
</getting-started>` guide.
96+
97+
To perform an aggregation, pass an array containing the pipeline stages to
98+
the ``MongoDB\Collection::aggregate()`` method.
99+
100+
The following code example produces a count of the number of bakeries in each borough
101+
of New York. To do so, it uses an aggregation pipeline that contains the following stages:
102+
103+
- :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
104+
in which the ``cuisine`` field contains the value ``'Bakery'``
105+
106+
- :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
107+
documents by the ``borough`` field, accumulating a count of documents for each distinct
108+
value
109+
110+
.. io-code-block::
111+
:copyable:
112+
113+
.. input:: /includes/aggregation.php
114+
:start-after: start-match-group
115+
:end-before: end-match-group
116+
:language: php
117+
:dedent:
118+
119+
.. output::
120+
:visible: false
121+
122+
{"_id":"Brooklyn","count":173}
123+
{"_id":"Queens","count":204}
124+
{"_id":"Bronx","count":71}
125+
{"_id":"Staten Island","count":20}
126+
{"_id":"Missing","count":2}
127+
{"_id":"Manhattan","count":221}
128+
129+
Explain an Aggregation
130+
~~~~~~~~~~~~~~~~~~~~~~
131+
132+
To view information about how MongoDB executes your operation, you can
133+
instruct the MongoDB query planner to **explain** it. When MongoDB explains
134+
an operation, it returns **execution plans** and performance statistics.
135+
An execution plan is a potential way in which MongoDB can complete an operation.
136+
When you instruct MongoDB to explain an operation, it returns both the
137+
plan MongoDB executed and any rejected execution plans.
138+
139+
To explain an aggregation operation, construct a ``MongoDB\Operation\Aggregate`` object
140+
and pass the database, collection, and pipeline stages as parameters. Then, pass the
141+
``MongoDB\Operation\Aggregate`` object to the ``MongoDB\Collection::explain()`` method.
142+
143+
The following example instructs MongoDB to explain the aggregation operation
144+
from the preceding :ref:`php-aggregation-example`:
145+
146+
.. io-code-block::
147+
:copyable:
148+
149+
.. input:: /includes/aggregation.php
150+
:start-after: start-explain
151+
:end-before: end-explain
152+
:language: php
153+
:dedent:
154+
155+
.. output::
156+
:visible: false
157+
158+
{"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants",
159+
"indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3",
160+
"planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false,
161+
"maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{
162+
... }
163+
164+
Additional Information
165+
----------------------
166+
167+
To view a tutorial that uses the {+php-library+} to create complex aggregation
168+
pipelines, see `Complex Aggregation Pipelines with Vanilla PHP and MongoDB
169+
<https://www.mongodb.com/developer/products/mongodb/aggregations-php-mongodb/>`__
170+
in the MongoDB Developer Center.
171+
172+
MongoDB Server Manual
173+
~~~~~~~~~~~~~~~~~~~~~
174+
175+
To learn more about the topics discussed in this guide, see the following
176+
pages in the {+mdb-server+} manual:
177+
178+
- To view a full list of expression operators, see :manual:`Aggregation
179+
Operators </reference/operator/aggregation/>`.
180+
181+
- To learn about assembling an aggregation pipeline and to view examples, see
182+
:manual:`Aggregation Pipeline </core/aggregation-pipeline/>`.
183+
184+
- To learn more about creating pipeline stages, see :manual:`Aggregation
185+
Stages </reference/operator/aggregation-pipeline/>`.
186+
187+
- To learn more about explaining MongoDB operations, see
188+
:manual:`Explain Output </reference/explain-results/>` and
189+
:manual:`Query Plans </core/query-plans/>`.
190+
191+
.. TODO:
192+
Aggregation Tutorials
193+
~~~~~~~~~~~~~~~~~~~~~
194+
195+
.. To view step-by-step explanations of common aggregation tasks, see
196+
.. :ref:`php-aggregation-tutorials-landing`.
197+
198+
API Documentation
199+
~~~~~~~~~~~~~~~~~
200+
201+
To learn more about the methods discussed in this guide, see the
202+
following API documentation:
203+
204+
- `MongoDB\\Collection::aggregate() <{+api+}/method/MongoDBCollection-aggregate/>`__
205+
- `MongoDB\\Collection::explain() <{+api+}/method/MongoDBCollection-explain/>`__

‎source/connect/connection-targets.txt

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. _php-connection-targets:
2+
3+
==========================
4+
Choose a Connection Target
5+
==========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings, client, stable api
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use a connection string and ``MongoDB\Client`` object
24+
to connect to different types of MongoDB deployments.
25+
26+
.. _php-connection-atlas:
27+
28+
Atlas
29+
-----
30+
31+
To connect to a MongoDB deployment on Atlas, include the following elements
32+
in your connection string:
33+
34+
- URI of your Atlas cluster
35+
- Database username
36+
- Database user's password
37+
38+
Then, pass your connection string to the ``MongoDB\Client`` constructor.
39+
40+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
41+
breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
42+
To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page
43+
<php-stable-api>`.
44+
45+
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster.
46+
The code also uses the ``serverApi`` option to specify a {+stable-api+} version.
47+
48+
.. literalinclude:: /includes/connect/atlas.php
49+
:copyable: true
50+
:language: php
51+
52+
.. tip::
53+
54+
Follow the :ref:`php-connection-string` step of the Quick Start
55+
to retrieve your connection string.
56+
57+
.. _php-connection-local:
58+
59+
Local Deployments
60+
-----------------
61+
62+
To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
63+
default, the ``mongod`` process runs on port 27017, though you can customize this for
64+
your deployment.
65+
66+
The following code shows how to use the {+driver-short+} to connect to a local MongoDB
67+
deployment:
68+
69+
.. literalinclude:: /includes/connect/client.php
70+
:language: php
71+
:copyable: true
72+
73+
.. _php-connection-replica-set:
74+
75+
Replica Sets
76+
------------
77+
78+
To connect to a replica set, specify the hostnames (or IP addresses) and
79+
port numbers of the replica set members in your connection string.
80+
81+
If you aren't able to provide a full list of hosts in the replica set, you can
82+
specify one or more of the hosts in the replica set and instruct the {+driver-short+} to
83+
perform automatic discovery to find the others. To instruct the driver to perform
84+
automatic discovery, choose one of the following actions:
85+
86+
- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
87+
- Specify ``false`` as the value of the ``directConnection`` parameter.
88+
- Specify more than one host in the replica set.
89+
90+
In the following example, the driver uses a sample connection URI to connect to the
91+
MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different
92+
hosts, including ``host1``:
93+
94+
.. literalinclude:: /includes/connect/replica-set.php
95+
:language: php
96+
:copyable: true
97+
98+
Initialization
99+
~~~~~~~~~~~~~~
100+
101+
To initialize a replica set, you must connect directly to a single member. To do so,
102+
set the ``directConnection`` connection
103+
option to ``true`` in the connection string. The following code example shows how to
104+
set this connection option:
105+
106+
.. literalinclude:: /includes/connect/direct-connection.php
107+
:language: php
108+
:copyable: true
109+
110+
API Documentation
111+
-----------------
112+
113+
To learn more about using the ``MongoDB\Client`` class,
114+
see the following API documentation:
115+
116+
- :ref:`MongoDB\Client <php-api-mongodbclient>`

‎source/includes/aggregation.php

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
5+
$client = new MongoDB\Client($uri);
6+
7+
$collection = $client->sample_restaurants->restaurants;
8+
9+
// Retrieves documents with a cuisine value of "Bakery", groups them by "borough", and
10+
// counts each borough's matching documents
11+
// start-match-group
12+
$pipeline = [
13+
['$match' => ['cuisine' => 'Bakery']],
14+
['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]],
15+
];
16+
17+
$cursor = $collection->aggregate($pipeline);
18+
19+
foreach ($cursor as $doc) {
20+
echo json_encode($doc) , PHP_EOL;
21+
}
22+
// end-match-group
23+
24+
// Performs the same aggregation operation as above but asks MongoDB to explain it
25+
// start-explain
26+
$pipeline = [
27+
['$match' => ['cuisine' => 'Bakery']],
28+
['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]],
29+
];
30+
31+
$aggregate = new MongoDB\Operation\Aggregate(
32+
$collection->getDatabaseName(),
33+
$collection->getCollectionName(),
34+
$pipeline
35+
);
36+
37+
$result = $collection->explain($aggregate);
38+
echo json_encode($result) , PHP_EOL;
39+
// end-explain
40+

0 commit comments

Comments
 (0)