Skip to content

Commit 24681d6

Browse files
norareidynorareidy
committed
Merge remote-tracking branch 'upstream/php-standardization' into DOCSP-41971-bulk
2 parents d0a12bd + f7d2584 commit 24681d6

File tree

14 files changed

+728
-19
lines changed

14 files changed

+728
-19
lines changed

‎snooty.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,9 +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"
3029
stable-api = "Stable API"
3130
mdb-server = "MongoDB Server"
3231
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/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+

‎source/includes/read/cursor.php

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
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+
// start-db-coll
8+
$collection = $client->sample_restaurants->restaurants;
9+
// end-db-coll
10+
11+
// Iterates over and prints all documents that have a "name" value of "Dunkin' Donuts"
12+
// start-cursor-iterate
13+
$cursor = $collection->find(['name' => 'Dunkin\' Donuts']);
14+
foreach ($cursor as $doc) {
15+
echo json_encode($doc) . PHP_EOL;
16+
}
17+
// end-cursor-iterate
18+
19+
// Retrieves and prints the first document stored in the cursor
20+
// start-cursor-first
21+
$cursor = $collection->find(['name' => 'Dunkin\' Donuts']);
22+
$cursor->rewind();
23+
echo json_encode($cursor->current());
24+
// end-cursor-first
25+
26+
// Converts the documents stored in a cursor to an array
27+
// start-cursor-array
28+
$cursor = $collection->find(['name' => 'Dunkin\' Donuts']);
29+
$array_results = $cursor->toArray();
30+
// end-cursor-array
31+
32+
// Creates a collection with a maximum size and inserts documents representing vegetables
33+
// start-capped-coll
34+
$db = $client->db;
35+
$create_coll = $db->createCollection(
36+
'vegetables',
37+
['capped' => true, 'size' => 1024 * 1024]
38+
);
39+
40+
$vegetables = [
41+
['name' => 'cauliflower'],
42+
['name' => 'zucchini']
43+
];
44+
45+
$collection = $db->vegetables;
46+
$result = $collection->insertMany($vegetables);
47+
// end-capped-coll
48+
49+
// Iterates over the initial query results and continues iterating until three documents are stored in the cursor
50+
// by using a tailable cursor
51+
// start-tailable
52+
$cursor = $collection->find([], ['cursorType' => MongoDB\Operation\Find::TAILABLE]);
53+
$cursor->rewind();
54+
55+
$docs_found = 0;
56+
while ($docs_found < 3) {
57+
if ($cursor->valid()) {
58+
$doc = $cursor->current();
59+
echo json_encode($doc) . PHP_EOL;
60+
$docs_found++;
61+
}
62+
$cursor->next();
63+
}
64+
// end-tailable

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
);
1818

1919
foreach ($cursor as $doc) {
20-
echo json_encode($doc) . PHP_EOL;
20+
echo json_encode($doc) , PHP_EOL;
2121
}
2222
// end-limit
2323

@@ -29,7 +29,7 @@
2929
);
3030

3131
foreach ($cursor as $doc) {
32-
echo json_encode($doc) . PHP_EOL;
32+
echo json_encode($doc) , PHP_EOL;
3333
}
3434
// end-sort
3535

@@ -41,7 +41,7 @@
4141
);
4242

4343
foreach ($cursor as $doc) {
44-
echo json_encode($doc) . PHP_EOL;
44+
echo json_encode($doc) , PHP_EOL;
4545
}
4646
// end-skip
4747

@@ -56,7 +56,7 @@
5656

5757
$cursor = $collection->find(['cuisine' => 'Italian'], $options);
5858
foreach ($cursor as $doc) {
59-
echo json_encode($doc) . PHP_EOL;
59+
echo json_encode($doc) , PHP_EOL;
6060
}
6161
// end-limit-sort-skip
6262

‎source/includes/read/project.php

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121

2222
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
2323
foreach ($cursor as $doc) {
24-
echo json_encode($doc) . PHP_EOL;
24+
echo json_encode($doc) , PHP_EOL;
2525
}
2626
// end-project-include
2727

@@ -39,7 +39,7 @@
3939

4040
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
4141
foreach ($cursor as $doc) {
42-
echo json_encode($doc) . PHP_EOL;
42+
echo json_encode($doc) , PHP_EOL;
4343
}
4444
// end-project-include-without-id
4545

@@ -54,6 +54,6 @@
5454

5555
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
5656
foreach ($cursor as $doc) {
57-
echo json_encode($doc) . PHP_EOL;
57+
echo json_encode($doc) , PHP_EOL;
5858
}
5959
// end-project-exclude

0 commit comments

Comments
 (0)