Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 3.9.x will end* 10 May 2021 (12 months).
- Bug fixes for security issues in 3.9.x will end* 8 May 2023 (36 months).
- PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
/cache/stores/mongodb/MongoDB/ -> Collection.php (source)
Differences Between: [Versions 39 and 311] [Versions 39 and 400] [Versions 39 and 401]
1 <?php 2 /* 3 * Copyright 2015-2017 MongoDB, Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 namespace MongoDB; 19 20 use MongoDB\BSON\JavascriptInterface; 21 use MongoDB\Driver\Cursor; 22 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException; 23 use MongoDB\Driver\Manager; 24 use MongoDB\Driver\ReadConcern; 25 use MongoDB\Driver\ReadPreference; 26 use MongoDB\Driver\WriteConcern; 27 use MongoDB\Exception\InvalidArgumentException; 28 use MongoDB\Exception\UnexpectedValueException; 29 use MongoDB\Exception\UnsupportedException; 30 use MongoDB\Model\BSONArray; 31 use MongoDB\Model\BSONDocument; 32 use MongoDB\Model\IndexInfo; 33 use MongoDB\Model\IndexInfoIterator; 34 use MongoDB\Operation\Aggregate; 35 use MongoDB\Operation\BulkWrite; 36 use MongoDB\Operation\Count; 37 use MongoDB\Operation\CountDocuments; 38 use MongoDB\Operation\CreateIndexes; 39 use MongoDB\Operation\DeleteMany; 40 use MongoDB\Operation\DeleteOne; 41 use MongoDB\Operation\Distinct; 42 use MongoDB\Operation\DropCollection; 43 use MongoDB\Operation\DropIndexes; 44 use MongoDB\Operation\EstimatedDocumentCount; 45 use MongoDB\Operation\Explain; 46 use MongoDB\Operation\Explainable; 47 use MongoDB\Operation\Find; 48 use MongoDB\Operation\FindOne; 49 use MongoDB\Operation\FindOneAndDelete; 50 use MongoDB\Operation\FindOneAndReplace; 51 use MongoDB\Operation\FindOneAndUpdate; 52 use MongoDB\Operation\InsertMany; 53 use MongoDB\Operation\InsertOne; 54 use MongoDB\Operation\ListIndexes; 55 use MongoDB\Operation\MapReduce; 56 use MongoDB\Operation\ReplaceOne; 57 use MongoDB\Operation\UpdateMany; 58 use MongoDB\Operation\UpdateOne; 59 use MongoDB\Operation\Watch; 60 use Traversable; 61 use function array_diff_key; 62 use function array_intersect_key; 63 use function current; 64 use function is_array; 65 use function strlen; 66 67 class Collection 68 { 69 /** @var array */ 70 private static $defaultTypeMap = [ 71 'array' => BSONArray::class, 72 'document' => BSONDocument::class, 73 'root' => BSONDocument::class, 74 ]; 75 76 /** @var integer */ 77 private static $wireVersionForFindAndModifyWriteConcern = 4; 78 79 /** @var integer */ 80 private static $wireVersionForReadConcern = 4; 81 82 /** @var integer */ 83 private static $wireVersionForWritableCommandWriteConcern = 5; 84 85 /** @var integer */ 86 private static $wireVersionForReadConcernWithWriteStage = 8; 87 88 /** @var string */ 89 private $collectionName; 90 91 /** @var string */ 92 private $databaseName; 93 94 /** @var Manager */ 95 private $manager; 96 97 /** @var ReadConcern */ 98 private $readConcern; 99 100 /** @var ReadPreference */ 101 private $readPreference; 102 103 /** @var array */ 104 private $typeMap; 105 106 /** @var WriteConcern */ 107 private $writeConcern; 108 109 /** 110 * Constructs new Collection instance. 111 * 112 * This class provides methods for collection-specific operations, such as 113 * CRUD (i.e. create, read, update, and delete) and index management. 114 * 115 * Supported options: 116 * 117 * * readConcern (MongoDB\Driver\ReadConcern): The default read concern to 118 * use for collection operations. Defaults to the Manager's read concern. 119 * 120 * * readPreference (MongoDB\Driver\ReadPreference): The default read 121 * preference to use for collection operations. Defaults to the Manager's 122 * read preference. 123 * 124 * * typeMap (array): Default type map for cursors and BSON documents. 125 * 126 * * writeConcern (MongoDB\Driver\WriteConcern): The default write concern 127 * to use for collection operations. Defaults to the Manager's write 128 * concern. 129 * 130 * @param Manager $manager Manager instance from the driver 131 * @param string $databaseName Database name 132 * @param string $collectionName Collection name 133 * @param array $options Collection options 134 * @throws InvalidArgumentException for parameter/option parsing errors 135 */ 136 public function __construct(Manager $manager, $databaseName, $collectionName, array $options = []) 137 { 138 if (strlen($databaseName) < 1) { 139 throw new InvalidArgumentException('$databaseName is invalid: ' . $databaseName); 140 } 141 142 if (strlen($collectionName) < 1) { 143 throw new InvalidArgumentException('$collectionName is invalid: ' . $collectionName); 144 } 145 146 if (isset($options['readConcern']) && ! $options['readConcern'] instanceof ReadConcern) { 147 throw InvalidArgumentException::invalidType('"readConcern" option', $options['readConcern'], ReadConcern::class); 148 } 149 150 if (isset($options['readPreference']) && ! $options['readPreference'] instanceof ReadPreference) { 151 throw InvalidArgumentException::invalidType('"readPreference" option', $options['readPreference'], ReadPreference::class); 152 } 153 154 if (isset($options['typeMap']) && ! is_array($options['typeMap'])) { 155 throw InvalidArgumentException::invalidType('"typeMap" option', $options['typeMap'], 'array'); 156 } 157 158 if (isset($options['writeConcern']) && ! $options['writeConcern'] instanceof WriteConcern) { 159 throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], WriteConcern::class); 160 } 161 162 $this->manager = $manager; 163 $this->databaseName = (string) $databaseName; 164 $this->collectionName = (string) $collectionName; 165 $this->readConcern = isset($options['readConcern']) ? $options['readConcern'] : $this->manager->getReadConcern(); 166 $this->readPreference = isset($options['readPreference']) ? $options['readPreference'] : $this->manager->getReadPreference(); 167 $this->typeMap = isset($options['typeMap']) ? $options['typeMap'] : self::$defaultTypeMap; 168 $this->writeConcern = isset($options['writeConcern']) ? $options['writeConcern'] : $this->manager->getWriteConcern(); 169 } 170 171 /** 172 * Return internal properties for debugging purposes. 173 * 174 * @see http://php.net/manual/en/language.oop5.magic.php#language.oop5.magic.debuginfo 175 * @return array 176 */ 177 public function __debugInfo() 178 { 179 return [ 180 'collectionName' => $this->collectionName, 181 'databaseName' => $this->databaseName, 182 'manager' => $this->manager, 183 'readConcern' => $this->readConcern, 184 'readPreference' => $this->readPreference, 185 'typeMap' => $this->typeMap, 186 'writeConcern' => $this->writeConcern, 187 ]; 188 } 189 190 /** 191 * Return the collection namespace (e.g. "db.collection"). 192 * 193 * @see https://docs.mongodb.org/manual/faq/developers/#faq-dev-namespace 194 * @return string 195 */ 196 public function __toString() 197 { 198 return $this->databaseName . '.' . $this->collectionName; 199 } 200 201 /** 202 * Executes an aggregation framework pipeline on the collection. 203 * 204 * Note: this method's return value depends on the MongoDB server version 205 * and the "useCursor" option. If "useCursor" is true, a Cursor will be 206 * returned; otherwise, an ArrayIterator is returned, which wraps the 207 * "result" array from the command response document. 208 * 209 * @see Aggregate::__construct() for supported options 210 * @param array $pipeline List of pipeline operations 211 * @param array $options Command options 212 * @return Traversable 213 * @throws UnexpectedValueException if the command response was malformed 214 * @throws UnsupportedException if options are not supported by the selected server 215 * @throws InvalidArgumentException for parameter/option parsing errors 216 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 217 */ 218 public function aggregate(array $pipeline, array $options = []) 219 { 220 $hasWriteStage = is_last_pipeline_operator_write($pipeline); 221 222 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 223 $options['readPreference'] = $this->readPreference; 224 } 225 226 if ($hasWriteStage) { 227 $options['readPreference'] = new ReadPreference(ReadPreference::RP_PRIMARY); 228 } 229 230 $server = select_server($this->manager, $options); 231 232 /* MongoDB 4.2 and later supports a read concern when an $out stage is 233 * being used, but earlier versions do not. 234 * 235 * A read concern is also not compatible with transactions. 236 */ 237 if (! isset($options['readConcern']) && 238 server_supports_feature($server, self::$wireVersionForReadConcern) && 239 ! is_in_transaction($options) && 240 ( ! $hasWriteStage || server_supports_feature($server, self::$wireVersionForReadConcernWithWriteStage)) 241 ) { 242 $options['readConcern'] = $this->readConcern; 243 } 244 245 if (! isset($options['typeMap'])) { 246 $options['typeMap'] = $this->typeMap; 247 } 248 249 if ($hasWriteStage && 250 ! isset($options['writeConcern']) && 251 server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && 252 ! is_in_transaction($options)) { 253 $options['writeConcern'] = $this->writeConcern; 254 } 255 256 $operation = new Aggregate($this->databaseName, $this->collectionName, $pipeline, $options); 257 258 return $operation->execute($server); 259 } 260 261 /** 262 * Executes multiple write operations. 263 * 264 * @see BulkWrite::__construct() for supported options 265 * @param array[] $operations List of write operations 266 * @param array $options Command options 267 * @return BulkWriteResult 268 * @throws UnsupportedException if options are not supported by the selected server 269 * @throws InvalidArgumentException for parameter/option parsing errors 270 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 271 */ 272 public function bulkWrite(array $operations, array $options = []) 273 { 274 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 275 $options['writeConcern'] = $this->writeConcern; 276 } 277 278 $operation = new BulkWrite($this->databaseName, $this->collectionName, $operations, $options); 279 $server = select_server($this->manager, $options); 280 281 return $operation->execute($server); 282 } 283 284 /** 285 * Gets the number of documents matching the filter. 286 * 287 * @see Count::__construct() for supported options 288 * @param array|object $filter Query by which to filter documents 289 * @param array $options Command options 290 * @return integer 291 * @throws UnexpectedValueException if the command response was malformed 292 * @throws UnsupportedException if options are not supported by the selected server 293 * @throws InvalidArgumentException for parameter/option parsing errors 294 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 295 * 296 * @deprecated 1.4 297 */ 298 public function count($filter = [], array $options = []) 299 { 300 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 301 $options['readPreference'] = $this->readPreference; 302 } 303 304 $server = select_server($this->manager, $options); 305 306 if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 307 $options['readConcern'] = $this->readConcern; 308 } 309 310 $operation = new Count($this->databaseName, $this->collectionName, $filter, $options); 311 312 return $operation->execute($server); 313 } 314 315 /** 316 * Gets the number of documents matching the filter. 317 * 318 * @see CountDocuments::__construct() for supported options 319 * @param array|object $filter Query by which to filter documents 320 * @param array $options Command options 321 * @return integer 322 * @throws UnexpectedValueException if the command response was malformed 323 * @throws UnsupportedException if options are not supported by the selected server 324 * @throws InvalidArgumentException for parameter/option parsing errors 325 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 326 */ 327 public function countDocuments($filter = [], array $options = []) 328 { 329 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 330 $options['readPreference'] = $this->readPreference; 331 } 332 333 $server = select_server($this->manager, $options); 334 335 if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 336 $options['readConcern'] = $this->readConcern; 337 } 338 339 $operation = new CountDocuments($this->databaseName, $this->collectionName, $filter, $options); 340 341 return $operation->execute($server); 342 } 343 344 /** 345 * Create a single index for the collection. 346 * 347 * @see Collection::createIndexes() 348 * @see CreateIndexes::__construct() for supported command options 349 * @param array|object $key Document containing fields mapped to values, 350 * which denote order or an index type 351 * @param array $options Index and command options 352 * @return string The name of the created index 353 * @throws UnsupportedException if options are not supported by the selected server 354 * @throws InvalidArgumentException for parameter/option parsing errors 355 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 356 */ 357 public function createIndex($key, array $options = []) 358 { 359 $commandOptionKeys = ['maxTimeMS' => 1, 'session' => 1, 'writeConcern' => 1]; 360 $indexOptions = array_diff_key($options, $commandOptionKeys); 361 $commandOptions = array_intersect_key($options, $commandOptionKeys); 362 363 return current($this->createIndexes([['key' => $key] + $indexOptions], $commandOptions)); 364 } 365 366 /** 367 * Create one or more indexes for the collection. 368 * 369 * Each element in the $indexes array must have a "key" document, which 370 * contains fields mapped to an order or type. Other options may follow. 371 * For example: 372 * 373 * $indexes = [ 374 * // Create a unique index on the "username" field 375 * [ 'key' => [ 'username' => 1 ], 'unique' => true ], 376 * // Create a 2dsphere index on the "loc" field with a custom name 377 * [ 'key' => [ 'loc' => '2dsphere' ], 'name' => 'geo' ], 378 * ]; 379 * 380 * If the "name" option is unspecified, a name will be generated from the 381 * "key" document. 382 * 383 * @see http://docs.mongodb.org/manual/reference/command/createIndexes/ 384 * @see http://docs.mongodb.org/manual/reference/method/db.collection.createIndex/ 385 * @see CreateIndexes::__construct() for supported command options 386 * @param array[] $indexes List of index specifications 387 * @param array $options Command options 388 * @return string[] The names of the created indexes 389 * @throws UnsupportedException if options are not supported by the selected server 390 * @throws InvalidArgumentException for parameter/option parsing errors 391 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 392 */ 393 public function createIndexes(array $indexes, array $options = []) 394 { 395 $server = select_server($this->manager, $options); 396 397 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) { 398 $options['writeConcern'] = $this->writeConcern; 399 } 400 401 $operation = new CreateIndexes($this->databaseName, $this->collectionName, $indexes, $options); 402 403 return $operation->execute($server); 404 } 405 406 /** 407 * Deletes all documents matching the filter. 408 * 409 * @see DeleteMany::__construct() for supported options 410 * @see http://docs.mongodb.org/manual/reference/command/delete/ 411 * @param array|object $filter Query by which to delete documents 412 * @param array $options Command options 413 * @return DeleteResult 414 * @throws UnsupportedException if options are not supported by the selected server 415 * @throws InvalidArgumentException for parameter/option parsing errors 416 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 417 */ 418 public function deleteMany($filter, array $options = []) 419 { 420 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 421 $options['writeConcern'] = $this->writeConcern; 422 } 423 424 $operation = new DeleteMany($this->databaseName, $this->collectionName, $filter, $options); 425 $server = select_server($this->manager, $options); 426 427 return $operation->execute($server); 428 } 429 430 /** 431 * Deletes at most one document matching the filter. 432 * 433 * @see DeleteOne::__construct() for supported options 434 * @see http://docs.mongodb.org/manual/reference/command/delete/ 435 * @param array|object $filter Query by which to delete documents 436 * @param array $options Command options 437 * @return DeleteResult 438 * @throws UnsupportedException if options are not supported by the selected server 439 * @throws InvalidArgumentException for parameter/option parsing errors 440 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 441 */ 442 public function deleteOne($filter, array $options = []) 443 { 444 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 445 $options['writeConcern'] = $this->writeConcern; 446 } 447 448 $operation = new DeleteOne($this->databaseName, $this->collectionName, $filter, $options); 449 $server = select_server($this->manager, $options); 450 451 return $operation->execute($server); 452 } 453 454 /** 455 * Finds the distinct values for a specified field across the collection. 456 * 457 * @see Distinct::__construct() for supported options 458 * @param string $fieldName Field for which to return distinct values 459 * @param array|object $filter Query by which to filter documents 460 * @param array $options Command options 461 * @return mixed[] 462 * @throws UnexpectedValueException if the command response was malformed 463 * @throws UnsupportedException if options are not supported by the selected server 464 * @throws InvalidArgumentException for parameter/option parsing errors 465 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 466 */ 467 public function distinct($fieldName, $filter = [], array $options = []) 468 { 469 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 470 $options['readPreference'] = $this->readPreference; 471 } 472 473 if (! isset($options['typeMap'])) { 474 $options['typeMap'] = $this->typeMap; 475 } 476 477 $server = select_server($this->manager, $options); 478 479 if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 480 $options['readConcern'] = $this->readConcern; 481 } 482 483 $operation = new Distinct($this->databaseName, $this->collectionName, $fieldName, $filter, $options); 484 485 return $operation->execute($server); 486 } 487 488 /** 489 * Drop this collection. 490 * 491 * @see DropCollection::__construct() for supported options 492 * @param array $options Additional options 493 * @return array|object Command result document 494 * @throws UnsupportedException if options are not supported by the selected server 495 * @throws InvalidArgumentException for parameter/option parsing errors 496 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 497 */ 498 public function drop(array $options = []) 499 { 500 if (! isset($options['typeMap'])) { 501 $options['typeMap'] = $this->typeMap; 502 } 503 504 $server = select_server($this->manager, $options); 505 506 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) { 507 $options['writeConcern'] = $this->writeConcern; 508 } 509 510 $operation = new DropCollection($this->databaseName, $this->collectionName, $options); 511 512 return $operation->execute($server); 513 } 514 515 /** 516 * Drop a single index in the collection. 517 * 518 * @see DropIndexes::__construct() for supported options 519 * @param string|IndexInfo $indexName Index name or model object 520 * @param array $options Additional options 521 * @return array|object Command result document 522 * @throws UnsupportedException if options are not supported by the selected server 523 * @throws InvalidArgumentException for parameter/option parsing errors 524 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 525 */ 526 public function dropIndex($indexName, array $options = []) 527 { 528 $indexName = (string) $indexName; 529 530 if ($indexName === '*') { 531 throw new InvalidArgumentException('dropIndexes() must be used to drop multiple indexes'); 532 } 533 534 if (! isset($options['typeMap'])) { 535 $options['typeMap'] = $this->typeMap; 536 } 537 538 $server = select_server($this->manager, $options); 539 540 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) { 541 $options['writeConcern'] = $this->writeConcern; 542 } 543 544 $operation = new DropIndexes($this->databaseName, $this->collectionName, $indexName, $options); 545 546 return $operation->execute($server); 547 } 548 549 /** 550 * Drop all indexes in the collection. 551 * 552 * @see DropIndexes::__construct() for supported options 553 * @param array $options Additional options 554 * @return array|object Command result document 555 * @throws UnsupportedException if options are not supported by the selected server 556 * @throws InvalidArgumentException for parameter/option parsing errors 557 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 558 */ 559 public function dropIndexes(array $options = []) 560 { 561 if (! isset($options['typeMap'])) { 562 $options['typeMap'] = $this->typeMap; 563 } 564 565 $server = select_server($this->manager, $options); 566 567 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) { 568 $options['writeConcern'] = $this->writeConcern; 569 } 570 571 $operation = new DropIndexes($this->databaseName, $this->collectionName, '*', $options); 572 573 return $operation->execute($server); 574 } 575 576 /** 577 * Gets an estimated number of documents in the collection using the collection metadata. 578 * 579 * @see EstimatedDocumentCount::__construct() for supported options 580 * @param array $options Command options 581 * @return integer 582 * @throws UnexpectedValueException if the command response was malformed 583 * @throws UnsupportedException if options are not supported by the selected server 584 * @throws InvalidArgumentException for parameter/option parsing errors 585 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 586 */ 587 public function estimatedDocumentCount(array $options = []) 588 { 589 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 590 $options['readPreference'] = $this->readPreference; 591 } 592 593 $server = select_server($this->manager, $options); 594 595 if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 596 $options['readConcern'] = $this->readConcern; 597 } 598 599 $operation = new EstimatedDocumentCount($this->databaseName, $this->collectionName, $options); 600 601 return $operation->execute($server); 602 } 603 604 /** 605 * Explains explainable commands. 606 * 607 * @see Explain::__construct() for supported options 608 * @see http://docs.mongodb.org/manual/reference/command/explain/ 609 * @param Explainable $explainable Command on which to run explain 610 * @param array $options Additional options 611 * @return array|object 612 * @throws UnsupportedException if explainable or options are not supported by the selected server 613 * @throws InvalidArgumentException for parameter/option parsing errors 614 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 615 */ 616 public function explain(Explainable $explainable, array $options = []) 617 { 618 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 619 $options['readPreference'] = $this->readPreference; 620 } 621 622 if (! isset($options['typeMap'])) { 623 $options['typeMap'] = $this->typeMap; 624 } 625 626 $server = select_server($this->manager, $options); 627 628 $operation = new Explain($this->databaseName, $explainable, $options); 629 630 return $operation->execute($server); 631 } 632 633 /** 634 * Finds documents matching the query. 635 * 636 * @see Find::__construct() for supported options 637 * @see http://docs.mongodb.org/manual/core/read-operations-introduction/ 638 * @param array|object $filter Query by which to filter documents 639 * @param array $options Additional options 640 * @return Cursor 641 * @throws UnsupportedException if options are not supported by the selected server 642 * @throws InvalidArgumentException for parameter/option parsing errors 643 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 644 */ 645 public function find($filter = [], array $options = []) 646 { 647 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 648 $options['readPreference'] = $this->readPreference; 649 } 650 651 $server = select_server($this->manager, $options); 652 653 if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 654 $options['readConcern'] = $this->readConcern; 655 } 656 657 if (! isset($options['typeMap'])) { 658 $options['typeMap'] = $this->typeMap; 659 } 660 661 $operation = new Find($this->databaseName, $this->collectionName, $filter, $options); 662 663 return $operation->execute($server); 664 } 665 666 /** 667 * Finds a single document matching the query. 668 * 669 * @see FindOne::__construct() for supported options 670 * @see http://docs.mongodb.org/manual/core/read-operations-introduction/ 671 * @param array|object $filter Query by which to filter documents 672 * @param array $options Additional options 673 * @return array|object|null 674 * @throws UnsupportedException if options are not supported by the selected server 675 * @throws InvalidArgumentException for parameter/option parsing errors 676 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 677 */ 678 public function findOne($filter = [], array $options = []) 679 { 680 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 681 $options['readPreference'] = $this->readPreference; 682 } 683 684 $server = select_server($this->manager, $options); 685 686 if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 687 $options['readConcern'] = $this->readConcern; 688 } 689 690 if (! isset($options['typeMap'])) { 691 $options['typeMap'] = $this->typeMap; 692 } 693 694 $operation = new FindOne($this->databaseName, $this->collectionName, $filter, $options); 695 696 return $operation->execute($server); 697 } 698 699 /** 700 * Finds a single document and deletes it, returning the original. 701 * 702 * The document to return may be null if no document matched the filter. 703 * 704 * @see FindOneAndDelete::__construct() for supported options 705 * @see http://docs.mongodb.org/manual/reference/command/findAndModify/ 706 * @param array|object $filter Query by which to filter documents 707 * @param array $options Command options 708 * @return array|object|null 709 * @throws UnexpectedValueException if the command response was malformed 710 * @throws UnsupportedException if options are not supported by the selected server 711 * @throws InvalidArgumentException for parameter/option parsing errors 712 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 713 */ 714 public function findOneAndDelete($filter, array $options = []) 715 { 716 $server = select_server($this->manager, $options); 717 718 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForFindAndModifyWriteConcern) && ! is_in_transaction($options)) { 719 $options['writeConcern'] = $this->writeConcern; 720 } 721 722 if (! isset($options['typeMap'])) { 723 $options['typeMap'] = $this->typeMap; 724 } 725 726 $operation = new FindOneAndDelete($this->databaseName, $this->collectionName, $filter, $options); 727 728 return $operation->execute($server); 729 } 730 731 /** 732 * Finds a single document and replaces it, returning either the original or 733 * the replaced document. 734 * 735 * The document to return may be null if no document matched the filter. By 736 * default, the original document is returned. Specify 737 * FindOneAndReplace::RETURN_DOCUMENT_AFTER for the "returnDocument" option 738 * to return the updated document. 739 * 740 * @see FindOneAndReplace::__construct() for supported options 741 * @see http://docs.mongodb.org/manual/reference/command/findAndModify/ 742 * @param array|object $filter Query by which to filter documents 743 * @param array|object $replacement Replacement document 744 * @param array $options Command options 745 * @return array|object|null 746 * @throws UnexpectedValueException if the command response was malformed 747 * @throws UnsupportedException if options are not supported by the selected server 748 * @throws InvalidArgumentException for parameter/option parsing errors 749 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 750 */ 751 public function findOneAndReplace($filter, $replacement, array $options = []) 752 { 753 $server = select_server($this->manager, $options); 754 755 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForFindAndModifyWriteConcern) && ! is_in_transaction($options)) { 756 $options['writeConcern'] = $this->writeConcern; 757 } 758 759 if (! isset($options['typeMap'])) { 760 $options['typeMap'] = $this->typeMap; 761 } 762 763 $operation = new FindOneAndReplace($this->databaseName, $this->collectionName, $filter, $replacement, $options); 764 765 return $operation->execute($server); 766 } 767 768 /** 769 * Finds a single document and updates it, returning either the original or 770 * the updated document. 771 * 772 * The document to return may be null if no document matched the filter. By 773 * default, the original document is returned. Specify 774 * FindOneAndUpdate::RETURN_DOCUMENT_AFTER for the "returnDocument" option 775 * to return the updated document. 776 * 777 * @see FindOneAndReplace::__construct() for supported options 778 * @see http://docs.mongodb.org/manual/reference/command/findAndModify/ 779 * @param array|object $filter Query by which to filter documents 780 * @param array|object $update Update to apply to the matched document 781 * @param array $options Command options 782 * @return array|object|null 783 * @throws UnexpectedValueException if the command response was malformed 784 * @throws UnsupportedException if options are not supported by the selected server 785 * @throws InvalidArgumentException for parameter/option parsing errors 786 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 787 */ 788 public function findOneAndUpdate($filter, $update, array $options = []) 789 { 790 $server = select_server($this->manager, $options); 791 792 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForFindAndModifyWriteConcern) && ! is_in_transaction($options)) { 793 $options['writeConcern'] = $this->writeConcern; 794 } 795 796 if (! isset($options['typeMap'])) { 797 $options['typeMap'] = $this->typeMap; 798 } 799 800 $operation = new FindOneAndUpdate($this->databaseName, $this->collectionName, $filter, $update, $options); 801 802 return $operation->execute($server); 803 } 804 805 /** 806 * Return the collection name. 807 * 808 * @return string 809 */ 810 public function getCollectionName() 811 { 812 return $this->collectionName; 813 } 814 815 /** 816 * Return the database name. 817 * 818 * @return string 819 */ 820 public function getDatabaseName() 821 { 822 return $this->databaseName; 823 } 824 825 /** 826 * Return the Manager. 827 * 828 * @return Manager 829 */ 830 public function getManager() 831 { 832 return $this->manager; 833 } 834 835 /** 836 * Return the collection namespace. 837 * 838 * @see https://docs.mongodb.org/manual/reference/glossary/#term-namespace 839 * @return string 840 */ 841 public function getNamespace() 842 { 843 return $this->databaseName . '.' . $this->collectionName; 844 } 845 846 /** 847 * Return the read concern for this collection. 848 * 849 * @see http://php.net/manual/en/mongodb-driver-readconcern.isdefault.php 850 * @return ReadConcern 851 */ 852 public function getReadConcern() 853 { 854 return $this->readConcern; 855 } 856 857 /** 858 * Return the read preference for this collection. 859 * 860 * @return ReadPreference 861 */ 862 public function getReadPreference() 863 { 864 return $this->readPreference; 865 } 866 867 /** 868 * Return the type map for this collection. 869 * 870 * @return array 871 */ 872 public function getTypeMap() 873 { 874 return $this->typeMap; 875 } 876 877 /** 878 * Return the write concern for this collection. 879 * 880 * @see http://php.net/manual/en/mongodb-driver-writeconcern.isdefault.php 881 * @return WriteConcern 882 */ 883 public function getWriteConcern() 884 { 885 return $this->writeConcern; 886 } 887 888 /** 889 * Inserts multiple documents. 890 * 891 * @see InsertMany::__construct() for supported options 892 * @see http://docs.mongodb.org/manual/reference/command/insert/ 893 * @param array[]|object[] $documents The documents to insert 894 * @param array $options Command options 895 * @return InsertManyResult 896 * @throws InvalidArgumentException for parameter/option parsing errors 897 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 898 */ 899 public function insertMany(array $documents, array $options = []) 900 { 901 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 902 $options['writeConcern'] = $this->writeConcern; 903 } 904 905 $operation = new InsertMany($this->databaseName, $this->collectionName, $documents, $options); 906 $server = select_server($this->manager, $options); 907 908 return $operation->execute($server); 909 } 910 911 /** 912 * Inserts one document. 913 * 914 * @see InsertOne::__construct() for supported options 915 * @see http://docs.mongodb.org/manual/reference/command/insert/ 916 * @param array|object $document The document to insert 917 * @param array $options Command options 918 * @return InsertOneResult 919 * @throws InvalidArgumentException for parameter/option parsing errors 920 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 921 */ 922 public function insertOne($document, array $options = []) 923 { 924 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 925 $options['writeConcern'] = $this->writeConcern; 926 } 927 928 $operation = new InsertOne($this->databaseName, $this->collectionName, $document, $options); 929 $server = select_server($this->manager, $options); 930 931 return $operation->execute($server); 932 } 933 934 /** 935 * Returns information for all indexes for the collection. 936 * 937 * @see ListIndexes::__construct() for supported options 938 * @param array $options 939 * @return IndexInfoIterator 940 * @throws InvalidArgumentException for parameter/option parsing errors 941 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 942 */ 943 public function listIndexes(array $options = []) 944 { 945 $operation = new ListIndexes($this->databaseName, $this->collectionName, $options); 946 $server = select_server($this->manager, $options); 947 948 return $operation->execute($server); 949 } 950 951 /** 952 * Executes a map-reduce aggregation on the collection. 953 * 954 * @see MapReduce::__construct() for supported options 955 * @see http://docs.mongodb.org/manual/reference/command/mapReduce/ 956 * @param JavascriptInterface $map Map function 957 * @param JavascriptInterface $reduce Reduce function 958 * @param string|array|object $out Output specification 959 * @param array $options Command options 960 * @return MapReduceResult 961 * @throws UnsupportedException if options are not supported by the selected server 962 * @throws InvalidArgumentException for parameter/option parsing errors 963 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 964 * @throws UnexpectedValueException if the command response was malformed 965 */ 966 public function mapReduce(JavascriptInterface $map, JavascriptInterface $reduce, $out, array $options = []) 967 { 968 $hasOutputCollection = ! is_mapreduce_output_inline($out); 969 970 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 971 $options['readPreference'] = $this->readPreference; 972 } 973 974 // Check if the out option is inline because we will want to coerce a primary read preference if not 975 if ($hasOutputCollection) { 976 $options['readPreference'] = new ReadPreference(ReadPreference::RP_PRIMARY); 977 } 978 979 $server = select_server($this->manager, $options); 980 981 /* A "majority" read concern is not compatible with inline output, so 982 * avoid providing the Collection's read concern if it would conflict. 983 * 984 * A read concern is also not compatible with transactions. 985 */ 986 if (! isset($options['readConcern']) && ! ($hasOutputCollection && $this->readConcern->getLevel() === ReadConcern::MAJORITY) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 987 $options['readConcern'] = $this->readConcern; 988 } 989 990 if (! isset($options['typeMap'])) { 991 $options['typeMap'] = $this->typeMap; 992 } 993 994 if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) { 995 $options['writeConcern'] = $this->writeConcern; 996 } 997 998 $operation = new MapReduce($this->databaseName, $this->collectionName, $map, $reduce, $out, $options); 999 1000 return $operation->execute($server); 1001 } 1002 1003 /** 1004 * Replaces at most one document matching the filter. 1005 * 1006 * @see ReplaceOne::__construct() for supported options 1007 * @see http://docs.mongodb.org/manual/reference/command/update/ 1008 * @param array|object $filter Query by which to filter documents 1009 * @param array|object $replacement Replacement document 1010 * @param array $options Command options 1011 * @return UpdateResult 1012 * @throws UnsupportedException if options are not supported by the selected server 1013 * @throws InvalidArgumentException for parameter/option parsing errors 1014 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 1015 */ 1016 public function replaceOne($filter, $replacement, array $options = []) 1017 { 1018 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 1019 $options['writeConcern'] = $this->writeConcern; 1020 } 1021 1022 $operation = new ReplaceOne($this->databaseName, $this->collectionName, $filter, $replacement, $options); 1023 $server = select_server($this->manager, $options); 1024 1025 return $operation->execute($server); 1026 } 1027 1028 /** 1029 * Updates all documents matching the filter. 1030 * 1031 * @see UpdateMany::__construct() for supported options 1032 * @see http://docs.mongodb.org/manual/reference/command/update/ 1033 * @param array|object $filter Query by which to filter documents 1034 * @param array|object $update Update to apply to the matched documents 1035 * @param array $options Command options 1036 * @return UpdateResult 1037 * @throws UnsupportedException if options are not supported by the selected server 1038 * @throws InvalidArgumentException for parameter/option parsing errors 1039 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 1040 */ 1041 public function updateMany($filter, $update, array $options = []) 1042 { 1043 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 1044 $options['writeConcern'] = $this->writeConcern; 1045 } 1046 1047 $operation = new UpdateMany($this->databaseName, $this->collectionName, $filter, $update, $options); 1048 $server = select_server($this->manager, $options); 1049 1050 return $operation->execute($server); 1051 } 1052 1053 /** 1054 * Updates at most one document matching the filter. 1055 * 1056 * @see UpdateOne::__construct() for supported options 1057 * @see http://docs.mongodb.org/manual/reference/command/update/ 1058 * @param array|object $filter Query by which to filter documents 1059 * @param array|object $update Update to apply to the matched document 1060 * @param array $options Command options 1061 * @return UpdateResult 1062 * @throws UnsupportedException if options are not supported by the selected server 1063 * @throws InvalidArgumentException for parameter/option parsing errors 1064 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 1065 */ 1066 public function updateOne($filter, $update, array $options = []) 1067 { 1068 if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { 1069 $options['writeConcern'] = $this->writeConcern; 1070 } 1071 1072 $operation = new UpdateOne($this->databaseName, $this->collectionName, $filter, $update, $options); 1073 $server = select_server($this->manager, $options); 1074 1075 return $operation->execute($server); 1076 } 1077 1078 /** 1079 * Create a change stream for watching changes to the collection. 1080 * 1081 * @see Watch::__construct() for supported options 1082 * @param array $pipeline List of pipeline operations 1083 * @param array $options Command options 1084 * @return ChangeStream 1085 * @throws InvalidArgumentException for parameter/option parsing errors 1086 */ 1087 public function watch(array $pipeline = [], array $options = []) 1088 { 1089 if (! isset($options['readPreference']) && ! is_in_transaction($options)) { 1090 $options['readPreference'] = $this->readPreference; 1091 } 1092 1093 $server = select_server($this->manager, $options); 1094 1095 /* Although change streams require a newer version of the server than 1096 * read concerns, perform the usual wire version check before inheriting 1097 * the collection's read concern. In the event that the server is too 1098 * old, this makes it more likely that users will encounter an error 1099 * related to change streams being unsupported instead of an 1100 * UnsupportedException regarding use of the "readConcern" option from 1101 * the Aggregate operation class. */ 1102 if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) { 1103 $options['readConcern'] = $this->readConcern; 1104 } 1105 1106 if (! isset($options['typeMap'])) { 1107 $options['typeMap'] = $this->typeMap; 1108 } 1109 1110 $operation = new Watch($this->manager, $this->databaseName, $this->collectionName, $pipeline, $options); 1111 1112 return $operation->execute($server); 1113 } 1114 1115 /** 1116 * Get a clone of this collection with different options. 1117 * 1118 * @see Collection::__construct() for supported options 1119 * @param array $options Collection constructor options 1120 * @return Collection 1121 * @throws InvalidArgumentException for parameter/option parsing errors 1122 */ 1123 public function withOptions(array $options = []) 1124 { 1125 $options += [ 1126 'readConcern' => $this->readConcern, 1127 'readPreference' => $this->readPreference, 1128 'typeMap' => $this->typeMap, 1129 'writeConcern' => $this->writeConcern, 1130 ]; 1131 1132 return new Collection($this->manager, $this->databaseName, $this->collectionName, $options); 1133 } 1134 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
