1<?php 2 3namespace MongoDB\Operation; 4 5use MongoDB\Driver\Server; 6use MongoDB\Exception\InvalidArgumentException; 7 8/** 9 * Operation for finding a single document with the find command. 10 * 11 * @api 12 * @see MongoDB\Collection::findOne() 13 * @see http://docs.mongodb.org/manual/tutorial/query-documents/ 14 * @see http://docs.mongodb.org/manual/reference/operator/query-modifier/ 15 */ 16class FindOne implements Executable 17{ 18 private $find; 19 private $options; 20 21 /** 22 * Constructs a find command for finding a single document. 23 * 24 * Supported options: 25 * 26 * * comment (string): Attaches a comment to the query. If "$comment" also 27 * exists in the modifiers document, this option will take precedence. 28 * 29 * * maxTimeMS (integer): The maximum amount of time to allow the query to 30 * run. If "$maxTimeMS" also exists in the modifiers document, this 31 * option will take precedence. 32 * 33 * * modifiers (document): Meta-operators modifying the output or behavior 34 * of a query. 35 * 36 * * projection (document): Limits the fields to return for the matching 37 * document. 38 * 39 * * readConcern (MongoDB\Driver\ReadConcern): Read concern. 40 * 41 * For servers < 3.2, this option is ignored as read concern is not 42 * available. 43 * 44 * * readPreference (MongoDB\Driver\ReadPreference): Read preference. 45 * 46 * * skip (integer): The number of documents to skip before returning. 47 * 48 * * sort (document): The order in which to return matching documents. If 49 * "$orderby" also exists in the modifiers document, this option will 50 * take precedence. 51 * 52 * * typeMap (array): Type map for BSON deserialization. 53 * 54 * @param string $databaseName Database name 55 * @param string $collectionName Collection name 56 * @param array|object $filter Query by which to filter documents 57 * @param array $options Command options 58 * @throws InvalidArgumentException 59 */ 60 public function __construct($databaseName, $collectionName, $filter, array $options = []) 61 { 62 $this->find = new Find( 63 $databaseName, 64 $collectionName, 65 $filter, 66 ['limit' => 1] + $options 67 ); 68 69 $this->options = $options; 70 } 71 72 /** 73 * Execute the operation. 74 * 75 * @see Executable::execute() 76 * @param Server $server 77 * @return array|object|null 78 */ 79 public function execute(Server $server) 80 { 81 $cursor = $this->find->execute($server); 82 $document = current($cursor->toArray()); 83 84 return ($document === false) ? null : $document; 85 } 86} 87