Retrieve Data

Sample Data

The examples in this guide use the companies collection in the sample_training database from the Atlas sample datasets. To access this collection from your PHP application, instantiate a MongoDB\Client that connects to an Atlas cluster and assign the following value to your $collection variable:

$collection = $client->sample_training->companies;

To learn how to create a free MongoDB deployment and load the sample datasets, see the MongoDB Get Started guide.

Find One Document

To find a single document in a collection, call the MongoDB\Collection::findOne() method and pass a query filter that specifies the criteria of the document you want to find.

The findOne() method returns an array, object, or null value. If the query filter matches a document, the method returns an array|object instance containing the document. The return type depends on the value of the typeMap option. If the query filter does not match any documents, the method returns null.

If the query filter matches more than one document, the findOne() method returns the first matching document from the retrieved results.

The following example uses the findOne() method to find the first document in which the name field has the value 'LinkedIn':

$document = $collection->findOne(['name' => 'LinkedIn']);
echo json_encode($document), PHP_EOL;

{"_id":{"$oid":"..."},"name":"LinkedIn","permalink":"linkedin","crunchbase_url":
"http:\/\/www.crunchbase.com\/company\/linkedin","homepage_url":"http:\/\/linkedin.com",
... }

Find Multiple Documents

To find multiple documents in a collection, pass a query filter to the MongoDB\Collection::find() method that specifies the criteria of the documents you want to retrieve.

The following example uses the find() method to find all documents in which the founded_year field has the value 1970:

$results = $collection->find(['founded_year' => 1970]);

The find() method returns an instance of MongoDB\Driver\Cursor, which you can iterate over to see the matching documents. A cursor is a mechanism that allows an application to iterate over database results while holding only a subset of them in memory at a given time. Cursors are useful when your find() method returns a large amount of documents.

You can iterate over the documents in a cursor by using a foreach loop, as shown in the following example:

foreach ($results as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":{"$oid":"..."},"name":"Mitsubishi Motors","permalink":"mitsubishi-motors",
"crunchbase_url":"http:\/\/www.crunchbase.com\/company\/mitsubishi-motors",
... }
{"_id":{"$oid":"..."},"name":"Western Digital","permalink":"western-digital",
"crunchbase_url":"http:\/\/www.crunchbase.com\/company\/western-digital",
... }
{"_id":{"$oid":"..."},"name":"Celarayn","permalink":"celarayn","crunchbase_url":
"http:\/\/www.crunchbase.com\/company\/celarayn",
... }

$cursor = $collection->find([]);

Modify Find Behavior

You can modify the behavior of the MongoDB\Collection::find() and MongoDB\Collection::findOne() methods by passing an array that specifies option values as a parameter. The following table describes some options you can set in the array:

The following example uses the find() method to find all documents in which the number_of_employees field has the value 1000. The example uses the limit option to return a maximum of 5 results:

$results = $collection->find(
    ['number_of_employees' => 1000],
    ['limit' => 5],
);
foreach ($results as $doc) {
    echo json_encode($doc), PHP_EOL;
}

For a full list of options, see the API documentation for the findOne() and find() parameters.

API Documentation

To learn more about any of the methods discussed in this guide, see the following API documentation:

• MongoDB\Collection::findOne()
• MongoDB\Collection::find()