Skip to content

Commit 202bef6

Browse files
jmikolajmikola
committed
PHPLIB-287: Add named modifier options to Find and FindOne
Before PHPC 1.2.0, these options could only be specified as query modifiers.
1 parent d960f5f commit 202bef6

File tree

5 files changed

+172
-3
lines changed

5 files changed

+172
-3
lines changed

‎docs/includes/apiargs-MongoDBCollection-method-find-option.yaml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,39 @@ source:
106106
ref: readPreference
107107
---
108108
arg_name: option
109+
name: max
110+
type: array|object
111+
description: |
112+
The exclusive upper bound for a specific index.
113+
114+
.. versionadded:: 1.2
115+
interface: phpmethod
116+
operation: ~
117+
optional: true
118+
---
119+
arg_name: option
120+
name: maxScan
121+
type: integer
122+
description: |
123+
Maximum number of documents or index keys to scan when executing the query.
124+
125+
.. versionadded:: 1.2
126+
interface: phpmethod
127+
operation: ~
128+
optional: true
129+
---
130+
arg_name: option
131+
name: min
132+
type: array|object
133+
description: |
134+
The inclusive lower bound for a specific index.
135+
136+
.. versionadded:: 1.2
137+
interface: phpmethod
138+
operation: ~
139+
optional: true
140+
---
141+
arg_name: option
109142
name: oplogReplay
110143
type: boolean
111144
description: |
@@ -133,6 +166,41 @@ operation: ~
133166
optional: true
134167
---
135168
arg_name: option
169+
name: returnKey
170+
type: boolean
171+
description: |
172+
If true, returns only the index keys in the resulting documents.
173+
174+
.. versionadded:: 1.2
175+
interface: phpmethod
176+
operation: ~
177+
optional: true
178+
---
179+
arg_name: option
180+
name: showRecordId
181+
type: boolean
182+
description: |
183+
Determines whether to return the record identifier for each document. If true,
184+
adds a field $recordId to the returned documents.
185+
186+
.. versionadded:: 1.2
187+
interface: phpmethod
188+
operation: ~
189+
optional: true
190+
---
191+
arg_name: option
192+
name: snapshot
193+
type: boolean
194+
description: |
195+
Prevents the cursor from returning a document more than once because of an
196+
intervening write operation.
197+
198+
.. versionadded:: 1.2
199+
interface: phpmethod
200+
operation: ~
201+
optional: true
202+
---
203+
arg_name: option
136204
name: allowPartialResults
137205
type: boolean
138206
description: |

‎docs/includes/apiargs-MongoDBCollection-method-findOne-option.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,26 @@ source:
4040
post: |
4141
This will be used for the returned result document.
4242
---
43+
source:
44+
file: apiargs-MongoDBCollection-method-find-option.yaml
45+
ref: max
46+
---
47+
source:
48+
file: apiargs-MongoDBCollection-method-find-option.yaml
49+
ref: maxScan
50+
---
51+
source:
52+
file: apiargs-MongoDBCollection-method-find-option.yaml
53+
ref: min
54+
---
55+
source:
56+
file: apiargs-MongoDBCollection-method-find-option.yaml
57+
ref: returnKey
58+
---
59+
source:
60+
file: apiargs-MongoDBCollection-method-find-option.yaml
61+
ref: showRecordId
62+
---
4363
source:
4464
file: apiargs-MongoDBCollection-method-find-option.yaml
4565
ref: modifiers

‎src/Operation/Find.php‎

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -76,10 +76,17 @@ class Find implements Executable
7676
*
7777
* * limit (integer): The maximum number of documents to return.
7878
*
79+
* * max (document): The exclusive upper bound for a specific index.
80+
*
81+
* * maxScan (integer): Maximum number of documents or index keys to scan
82+
* when executing the query.
83+
*
7984
* * maxTimeMS (integer): The maximum amount of time to allow the query to
8085
* run. If "$maxTimeMS" also exists in the modifiers document, this
8186
* option will take precedence.
8287
*
88+
* * min (document): The inclusive upper bound for a specific index.
89+
*
8390
* * modifiers (document): Meta operators that modify the output or
8491
* behavior of a query. Use of these operators is deprecated in favor of
8592
* named options.
@@ -101,8 +108,18 @@ class Find implements Executable
101108
*
102109
* * readPreference (MongoDB\Driver\ReadPreference): Read preference.
103110
*
111+
* * returnKey (boolean): If true, returns only the index keys in the
112+
* resulting documents.
113+
*
114+
* * showRecordId (boolean): Determines whether to return the record
115+
* identifier for each document. If true, adds a field $recordId to the
116+
* returned documents.
117+
*
104118
* * skip (integer): The number of documents to skip before returning.
105119
*
120+
* * snapshot (boolean): Prevents the cursor from returning a document more
121+
* than once because of an intervening write operation.
122+
*
106123
* * sort (document): The order in which to return matching documents. If
107124
* "$orderby" also exists in the modifiers document, this option will
108125
* take precedence.
@@ -158,10 +175,22 @@ public function __construct($databaseName, $collectionName, $filter, array $opti
158175
throw InvalidArgumentException::invalidType('"limit" option', $options['limit'], 'integer');
159176
}
160177

178+
if (isset($options['max']) && ! is_array($options['max']) && ! is_object($options['max'])) {
179+
throw InvalidArgumentException::invalidType('"max" option', $options['max'], 'array or object');
180+
}
181+
182+
if (isset($options['maxScan']) && ! is_integer($options['maxScan'])) {
183+
throw InvalidArgumentException::invalidType('"maxScan" option', $options['maxScan'], 'integer');
184+
}
185+
161186
if (isset($options['maxTimeMS']) && ! is_integer($options['maxTimeMS'])) {
162187
throw InvalidArgumentException::invalidType('"maxTimeMS" option', $options['maxTimeMS'], 'integer');
163188
}
164189

190+
if (isset($options['min']) && ! is_array($options['min']) && ! is_object($options['min'])) {
191+
throw InvalidArgumentException::invalidType('"min" option', $options['min'], 'array or object');
192+
}
193+
165194
if (isset($options['modifiers']) && ! is_array($options['modifiers']) && ! is_object($options['modifiers'])) {
166195
throw InvalidArgumentException::invalidType('"modifiers" option', $options['modifiers'], 'array or object');
167196
}
@@ -186,10 +215,22 @@ public function __construct($databaseName, $collectionName, $filter, array $opti
186215
throw InvalidArgumentException::invalidType('"readPreference" option', $options['readPreference'], 'MongoDB\Driver\ReadPreference');
187216
}
188217

218+
if (isset($options['returnKey']) && ! is_bool($options['returnKey'])) {
219+
throw InvalidArgumentException::invalidType('"returnKey" option', $options['returnKey'], 'boolean');
220+
}
221+
222+
if (isset($options['showRecordId']) && ! is_bool($options['showRecordId'])) {
223+
throw InvalidArgumentException::invalidType('"showRecordId" option', $options['showRecordId'], 'boolean');
224+
}
225+
189226
if (isset($options['skip']) && ! is_integer($options['skip'])) {
190227
throw InvalidArgumentException::invalidType('"skip" option', $options['skip'], 'integer');
191228
}
192229

230+
if (isset($options['snapshot']) && ! is_bool($options['snapshot'])) {
231+
throw InvalidArgumentException::invalidType('"snapshot" option', $options['snapshot'], 'boolean');
232+
}
233+
193234
if (isset($options['sort']) && ! is_array($options['sort']) && ! is_object($options['sort'])) {
194235
throw InvalidArgumentException::invalidType('"sort" option', $options['sort'], 'array or object');
195236
}
@@ -257,14 +298,16 @@ private function createQuery()
257298
}
258299
}
259300

260-
foreach (['allowPartialResults', 'batchSize', 'comment', 'hint', 'limit', 'maxTimeMS', 'noCursorTimeout', 'oplogReplay', 'projection', 'readConcern', 'skip', 'sort'] as $option) {
301+
foreach (['allowPartialResults', 'batchSize', 'comment', 'hint', 'limit', 'maxScan', 'maxTimeMS', 'noCursorTimeout', 'oplogReplay', 'projection', 'readConcern', 'returnKey', 'showRecordId', 'skip', 'snapshot', 'sort'] as $option) {
261302
if (isset($this->options[$option])) {
262303
$options[$option] = $this->options[$option];
263304
}
264305
}
265306

266-
if (isset($this->options['collation'])) {
267-
$options['collation'] = (object) $this->options['collation'];
307+
foreach (['collation', 'max', 'min'] as $option) {
308+
if (isset($this->options[$option])) {
309+
$options[$option] = (object) $this->options[$option];
310+
}
268311
}
269312

270313
$modifiers = empty($this->options['modifiers']) ? [] : (array) $this->options['modifiers'];

‎src/Operation/FindOne.php‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,17 @@ class FindOne implements Executable
5252
* name as a string or the index key pattern as a document. If specified,
5353
* then the query system will only consider plans using the hinted index.
5454
*
55+
* * max (document): The exclusive upper bound for a specific index.
56+
*
57+
* * maxScan (integer): Maximum number of documents or index keys to scan
58+
* when executing the query.
59+
*
5560
* * maxTimeMS (integer): The maximum amount of time to allow the query to
5661
* run. If "$maxTimeMS" also exists in the modifiers document, this
5762
* option will take precedence.
5863
*
64+
* * min (document): The inclusive upper bound for a specific index.
65+
*
5966
* * modifiers (document): Meta-operators modifying the output or behavior
6067
* of a query.
6168
*
@@ -69,6 +76,13 @@ class FindOne implements Executable
6976
*
7077
* * readPreference (MongoDB\Driver\ReadPreference): Read preference.
7178
*
79+
* * returnKey (boolean): If true, returns only the index keys in the
80+
* resulting documents.
81+
*
82+
* * showRecordId (boolean): Determines whether to return the record
83+
* identifier for each document. If true, adds a field $recordId to the
84+
* returned documents.
85+
*
7286
* * skip (integer): The number of documents to skip before returning.
7387
*
7488
* * sort (document): The order in which to return matching documents. If

‎tests/Operation/FindTest.php‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,22 @@ public function provideInvalidConstructorOptions()
5656
$options[][] = ['limit' => $value];
5757
}
5858

59+
foreach ($this->getInvalidDocumentValues() as $value) {
60+
$options[][] = ['max' => $value];
61+
}
62+
63+
foreach ($this->getInvalidIntegerValues() as $value) {
64+
$options[][] = ['maxScan' => $value];
65+
}
66+
5967
foreach ($this->getInvalidIntegerValues() as $value) {
6068
$options[][] = ['maxTimeMS' => $value];
6169
}
6270

71+
foreach ($this->getInvalidDocumentValues() as $value) {
72+
$options[][] = ['min' => $value];
73+
}
74+
6375
foreach ($this->getInvalidDocumentValues() as $value) {
6476
$options[][] = ['modifiers' => $value];
6577
}
@@ -80,10 +92,22 @@ public function provideInvalidConstructorOptions()
8092
$options[][] = ['readPreference' => $value];
8193
}
8294

95+
foreach ($this->getInvalidBooleanValues() as $value) {
96+
$options[][] = ['returnKey' => $value];
97+
}
98+
99+
foreach ($this->getInvalidBooleanValues() as $value) {
100+
$options[][] = ['showRecordId' => $value];
101+
}
102+
83103
foreach ($this->getInvalidIntegerValues() as $value) {
84104
$options[][] = ['skip' => $value];
85105
}
86106

107+
foreach ($this->getInvalidBooleanValues() as $value) {
108+
$options[][] = ['snapshot' => $value];
109+
}
110+
87111
foreach ($this->getInvalidDocumentValues() as $value) {
88112
$options[][] = ['sort' => $value];
89113
}

0 commit comments

Comments
 (0)