See Release Notes
Long Term Support Release
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401]
1 <?php 2 /* 3 * Copyright 2015-present 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 * https://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\Operation; 19 20 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException; 21 use MongoDB\Driver\Server; 22 use MongoDB\Exception\InvalidArgumentException; 23 use MongoDB\Exception\UnsupportedException; 24 25 use function current; 26 27 /** 28 * Operation for finding a single document with the find command. 29 * 30 * @api 31 * @see \MongoDB\Collection::findOne() 32 * @see https://mongodb.com/docs/manual/tutorial/query-documents/ 33 * @see https://mongodb.com/docs/manual/reference/operator/query-modifier/ 34 */ 35 class FindOne implements Executable, Explainable 36 { 37 /** @var Find */ 38 private $find; 39 40 /** 41 * Constructs a find command for finding a single document. 42 * 43 * Supported options: 44 * 45 * * collation (document): Collation specification. 46 * 47 * * comment (mixed): BSON value to attach as a comment to this command. 48 * 49 * Only string values are supported for server versions < 4.4. 50 * 51 * * hint (string|document): The index to use. Specify either the index 52 * name as a string or the index key pattern as a document. If specified, 53 * then the query system will only consider plans using the hinted index. 54 * 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 * 60 * This option has been deprecated since version 1.4. 61 * 62 * * maxTimeMS (integer): The maximum amount of time to allow the query to 63 * run. If "$maxTimeMS" also exists in the modifiers document, this 64 * option will take precedence. 65 * 66 * * min (document): The inclusive upper bound for a specific index. 67 * 68 * * modifiers (document): Meta-operators modifying the output or behavior 69 * of a query. 70 * 71 * * projection (document): Limits the fields to return for the matching 72 * document. 73 * 74 * * readConcern (MongoDB\Driver\ReadConcern): Read concern. 75 * 76 * * readPreference (MongoDB\Driver\ReadPreference): Read preference. 77 * 78 * * returnKey (boolean): If true, returns only the index keys in the 79 * resulting documents. 80 * 81 * * session (MongoDB\Driver\Session): Client session. 82 * 83 * * showRecordId (boolean): Determines whether to return the record 84 * identifier for each document. If true, adds a field $recordId to the 85 * returned documents. 86 * 87 * * skip (integer): The number of documents to skip before returning. 88 * 89 * * sort (document): The order in which to return matching documents. If 90 * "$orderby" also exists in the modifiers document, this option will 91 * take precedence. 92 * 93 * * let (document): Map of parameter names and values. Values must be 94 * constant or closed expressions that do not reference document fields. 95 * Parameters can then be accessed as variables in an aggregate 96 * expression context (e.g. "$$var"). 97 * 98 * * typeMap (array): Type map for BSON deserialization. 99 * 100 * @param string $databaseName Database name 101 * @param string $collectionName Collection name 102 * @param array|object $filter Query by which to filter documents 103 * @param array $options Command options 104 * @throws InvalidArgumentException for parameter/option parsing errors 105 */ 106 public function __construct(string $databaseName, string $collectionName, $filter, array $options = []) 107 { 108 $this->find = new Find( 109 $databaseName, 110 $collectionName, 111 $filter, 112 ['limit' => 1] + $options 113 ); 114 } 115 116 /** 117 * Execute the operation. 118 * 119 * @see Executable::execute() 120 * @return array|object|null 121 * @throws UnsupportedException if collation or read concern is used and unsupported 122 * @throws DriverRuntimeException for other driver errors (e.g. connection errors) 123 */ 124 public function execute(Server $server) 125 { 126 $cursor = $this->find->execute($server); 127 $document = current($cursor->toArray()); 128 129 return $document === false ? null : $document; 130 } 131 132 /** 133 * Returns the command document for this operation. 134 * 135 * @see Explainable::getCommandDocument() 136 * @return array 137 */ 138 public function getCommandDocument(Server $server) 139 { 140 return $this->find->getCommandDocument($server); 141 } 142 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body