Skip to content

Commit a29ed4c

Browse files
alcaeusalcaeus
committed
PHPLIB-402: Add aggregate helper to Database class
Merged from #642. https://jira.mongodb.org/browse/PHPLIB-402 I've extracted the `is_in_transaction` helper from `MongoDB\Collection` in a separate to functions since we need it more often. I've also decided to extract the options for the aggregate helper to a common file to avoid unnecessary duplication of option descriptions.
2 parents cb6efc5 + 2844683 commit a29ed4c

8 files changed

+223
-59
lines changed

‎source/includes/apiargs-MongoDBCollection-method-aggregate-option.yaml‎

Lines changed: 25 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,32 @@
1-
arg_name: option
2-
name: allowDiskUse
3-
type: boolean
4-
description: |
5-
Enables writing to temporary files. When set to ``true``, aggregation stages
6-
can write data to the ``_tmp`` sub-directory in the ``dbPath`` directory. The
7-
default is ``false``.
8-
interface: phpmethod
9-
operation: ~
10-
optional: true
1+
source:
2+
file: apiargs-aggregate-option.yaml
3+
ref: allowDiskUse
114
---
12-
arg_name: option
13-
name: batchSize
14-
type: integer
15-
description: |
16-
Specifies the initial batch size for the cursor. A batchSize of ``0`` means an
17-
empty first batch and is useful for quickly returning a cursor or failure
18-
message without doing significant server-side work.
19-
interface: phpmethod
20-
operation: ~
21-
optional: true
5+
source:
6+
file: apiargs-aggregate-option.yaml
7+
ref: batchSize
228
---
239
source:
24-
file: apiargs-MongoDBCollection-common-option.yaml
10+
file: apiargs-aggregate-option.yaml
2511
ref: bypassDocumentValidation
26-
post: |
27-
This only applies when using the :ref:`$out <agg-out>` stage.
28-
29-
Document validation requires MongoDB 3.2 or later: if you are using an earlier
30-
version of MongoDB, this option will be ignored.
3112
---
32-
arg_name: option
33-
name: comment
34-
type: string
35-
description: |
36-
Users can specify an arbitrary string to help trace the operation through the
37-
database profiler, currentOp, and logs.
38-
13+
source:
14+
file: apiargs-aggregate-option.yaml
15+
ref: comment
16+
post: |
3917
.. versionadded:: 1.3
40-
interface: phpmethod
41-
operation: ~
42-
optional: true
4318
---
44-
arg_name: option
45-
name: explain
46-
type: boolean
47-
description: |
48-
Specifies whether or not to return the information on the processing of the
49-
pipeline.
50-
19+
source:
20+
file: apiargs-aggregate-option.yaml
21+
ref: explain
22+
post: |
5123
.. versionadded:: 1.4
52-
interface: phpmethod
53-
operation: ~
54-
optional: true
5524
---
56-
arg_name: option
57-
name: hint
58-
type: string|array|object
59-
description: |
60-
The index to use. Specify either the index name as a string or the index key
61-
pattern as a document. If specified, then the query system will only consider
62-
plans using the hinted index.
63-
25+
source:
26+
file: apiargs-aggregate-option.yaml
27+
ref: hint
28+
post: |
6429
.. versionadded:: 1.3
65-
interface: phpmethod
66-
operation: ~
67-
optional: true
6830
---
6931
source:
7032
file: apiargs-common-option.yaml
@@ -96,6 +58,12 @@ type: boolean
9658
description: |
9759
Indicates whether the command will request that the server provide results
9860
using a cursor. The default is ``true``.
61+
62+
.. note::
63+
64+
MongoDB 3.6+ no longer supports returning results without a cursor (excluding
65+
when the explain option is used) and specifying false for this option will
66+
result in a server error.
9967
interface: phpmethod
10068
operation: ~
10169
optional: true

‎source/includes/apiargs-MongoDBDatabase-method-aggregate-option.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
source:
2+
file: apiargs-aggregate-option.yaml
3+
ref: allowDiskUse
4+
---
5+
source:
6+
file: apiargs-aggregate-option.yaml
7+
ref: batchSize
8+
---
9+
source:
10+
file: apiargs-aggregate-option.yaml
11+
ref: bypassDocumentValidation
12+
---
13+
source:
14+
file: apiargs-aggregate-option.yaml
15+
ref: comment
16+
---
17+
source:
18+
file: apiargs-aggregate-option.yaml
19+
ref: explain
20+
---
21+
source:
22+
file: apiargs-aggregate-option.yaml
23+
ref: hint
24+
---
25+
source:
26+
file: apiargs-common-option.yaml
27+
ref: maxTimeMS
28+
---
29+
source:
30+
file: apiargs-MongoDBDatabase-common-option.yaml
31+
ref: readConcern
32+
---
33+
source:
34+
file: apiargs-MongoDBDatabase-common-option.yaml
35+
ref: readPreference
36+
post: |
37+
This option will be ignored when using the :ref:`$out <agg-out>` stage.
38+
---
39+
source:
40+
file: apiargs-common-option.yaml
41+
ref: session
42+
---
43+
source:
44+
file: apiargs-MongoDBDatabase-common-option.yaml
45+
ref: typeMap
46+
---
47+
source:
48+
file: apiargs-MongoDBDatabase-common-option.yaml
49+
ref: writeConcern
50+
post: |
51+
This only applies when the :ref:`$out <agg-out>` stage is specified.
52+
53+
This is not supported for server versions prior to 3.4 and will result in an
54+
exception at execution time if used.
55+
...

‎source/includes/apiargs-MongoDBDatabase-method-aggregate-param.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
arg_name: param
2+
name: $pipeline
3+
type: array
4+
description: |
5+
Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
6+
operation.
7+
interface: phpmethod
8+
operation: ~
9+
optional: false
10+
---
11+
source:
12+
file: apiargs-common-param.yaml
13+
ref: $options
14+
...

‎source/includes/apiargs-aggregate-option.yaml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
arg_name: option
2+
name: allowDiskUse
3+
type: boolean
4+
description: |
5+
Enables writing to temporary files. When set to ``true``, aggregation stages
6+
can write data to the ``_tmp`` sub-directory in the ``dbPath`` directory. The
7+
default is ``false``.
8+
interface: phpmethod
9+
operation: ~
10+
optional: true
11+
---
12+
arg_name: option
13+
name: batchSize
14+
type: integer
15+
description: |
16+
Specifies the initial batch size for the cursor. A batchSize of ``0`` means an
17+
empty first batch and is useful for quickly returning a cursor or failure
18+
message without doing significant server-side work.
19+
interface: phpmethod
20+
operation: ~
21+
optional: true
22+
---
23+
source:
24+
file: apiargs-MongoDBCollection-common-option.yaml
25+
ref: bypassDocumentValidation
26+
post: |
27+
This only applies when using the :ref:`$out <agg-out>` stage.
28+
29+
Document validation requires MongoDB 3.2 or later: if you are using an earlier
30+
version of MongoDB, this option will be ignored.
31+
---
32+
arg_name: option
33+
name: comment
34+
type: string
35+
description: |
36+
Users can specify an arbitrary string to help trace the operation through the
37+
database profiler, currentOp, and logs.
38+
interface: phpmethod
39+
operation: ~
40+
optional: true
41+
---
42+
arg_name: option
43+
name: explain
44+
type: boolean
45+
description: |
46+
Specifies whether or not to return the information on the processing of the
47+
pipeline.
48+
interface: phpmethod
49+
operation: ~
50+
optional: true
51+
---
52+
arg_name: option
53+
name: hint
54+
type: string|array|object
55+
description: |
56+
The index to use. Specify either the index name as a string or the index key
57+
pattern as a document. If specified, then the query system will only consider
58+
plans using the hinted index.
59+
interface: phpmethod
60+
operation: ~
61+
optional: true
62+
...

‎source/reference/class/MongoDBDatabase.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ Methods
4545

4646
/reference/method/MongoDBDatabase__construct
4747
/reference/method/MongoDBDatabase__get
48+
/reference/method/MongoDBDatabase-aggregate
4849
/reference/method/MongoDBDatabase-command
4950
/reference/method/MongoDBDatabase-createCollection
5051
/reference/method/MongoDBDatabase-drop

‎source/reference/method/MongoDBCollection-aggregate.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ Errors/Exceptions
4545
.. include:: /includes/extracts/error-invalidargumentexception.rst
4646
.. include:: /includes/extracts/error-driver-runtimeexception.rst
4747

48-
.. _php-agg-method-behavior:
48+
.. _php-coll-agg-method-behavior:
4949

5050
Behavior
5151
--------
@@ -63,6 +63,7 @@ value will be :php:`Traversable <traversable>`.
6363
See Also
6464
--------
6565

66+
- :phpmethod:`MongoDB\\Database::aggregate()`
6667
- :manual:`aggregate </reference/command/aggregate>` command reference in the
6768
MongoDB manual
6869
- :manual:`Aggregation Pipeline </core/aggregation-pipeline>` documentation in

‎source/reference/method/MongoDBDatabase-aggregate.txt‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
==============================
2+
MongoDB\\Database::aggregate()
3+
==============================
4+
5+
.. versionadded:: 1.5
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. phpmethod:: MongoDB\\Database::aggregate()
19+
20+
Runs a specified :manual:`admin/diagnostic pipeline
21+
</reference/operator/aggregation-pipeline/#db-aggregate-stages>` which does
22+
not require an underlying collection. For aggregations on collection data,
23+
see :phpmethod:`MongoDB\\Collection::aggregate()`.
24+
25+
.. code-block:: php
26+
27+
function aggregate(array $pipeline, array $options = []): Traversable
28+
29+
This method has the following parameters:
30+
31+
.. include:: /includes/apiargs/MongoDBDatabase-method-aggregate-param.rst
32+
33+
The ``$options`` parameter supports the following options:
34+
35+
.. include:: /includes/apiargs/MongoDBDatabase-method-aggregate-option.rst
36+
37+
Return Values
38+
-------------
39+
40+
A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` or
41+
:php:`ArrayIterator <arrayiterator>` object. In both cases, the return value
42+
will be :php:`Traversable <traversable>`.
43+
44+
Errors/Exceptions
45+
-----------------
46+
47+
.. include:: /includes/extracts/error-unexpectedvalueexception.rst
48+
.. include:: /includes/extracts/error-unsupportedexception.rst
49+
.. include:: /includes/extracts/error-invalidargumentexception.rst
50+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
51+
52+
.. _php-db-agg-method-behavior:
53+
54+
.. todo: add examples
55+
56+
See Also
57+
--------
58+
59+
- :phpmethod:`MongoDB\\Collection::aggregate()`
60+
- :manual:`aggregate </reference/command/aggregate>` command reference in the
61+
MongoDB manual
62+
- :manual:`Aggregation Pipeline </core/aggregation-pipeline>` documentation in
63+
the MongoDB Manual

‎source/tutorial/crud.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -401,7 +401,7 @@ The |php-library|\'s :phpmethod:`MongoDB\\Collection::aggregate()` method
401401
returns a :php:`Traversable <traversable>` object, which you can iterate upon to
402402
access the results of the aggregation operation. Refer to the
403403
:phpmethod:`MongoDB\\Collection::aggregate()` method's :ref:`behavior
404-
reference <php-agg-method-behavior>` for more about the method's output.
404+
reference <php-coll-agg-method-behavior>` for more about the method's output.
405405

406406
The following example lists the 5 US states with the most zip codes associated
407407
with them:

0 commit comments

Comments
 (0)