Docs Menu
Docs Home
/
Languages
/
PHP
/
PHP Library Manual
/
Read Data from MongoDB

Retrieve Data

On this page

  • Overview
  • Sample Data
  • Find Documents
  • Find One Document
  • Find Multiple Documents
  • Modify Find Behavior
  • Additional Information
  • API Documentation

Overview

In this guide, you can learn how to use the MongoDB PHP Library to retrieve data from a MongoDB collection by using read operations. You can call the MongoDB\Collection::find() or MongoDB\Collection::findOne() method on a collection to retrieve documents that match a set of criteria.

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 Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Find Documents

The MongoDB PHP Library includes two methods for retrieving documents from a collection: MongoDB\Collection::findOne() and MongoDB\Collection::find(). These methods take a query filter and return one or more matching documents. A query filter specifies the search criteria that the driver uses to retrieve documents in your query.

Tip

To learn more about query filters, see the Specify a Query 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.

Tip

To learn more about findOne() options, such as typeMap, see the Modify Find Behavior section of this guide.

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;

Tip

Sort Order

The findOne() method returns the first document in natural order on disk if no sort criteria is specified.

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;
}

Note

Find All Documents

To find all documents in a collection, pass an empty filter to the find() method:

$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:

Option
Description
batchSize
The number of documents to return per batch. The default value is 101.
Type: integer
collation
The collation to use for the operation. The default value is the collation specified for the collection.
Type: array|object
comment
The comment to attach to the operation.
Type: any BSON type
cursorType
The type of cursor to use for the operation. The default value is MongoDB\Operation\Find::NON_TAILABLE.
Type: MongoDB\Operation\Find
limit
The maximum number of documents the operation can return.
Type: integer
skip
The number of documents to skip before returning results.
Type: integer
sort
The order in which the operation returns matching documents.
Type: array|object
typeMap
The type map to apply to cursors, which determines how BSON documents are converted to PHP values. The default value is the collection's type map.
Type: 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.

Additional Information

To learn more about query filters, see the Specify a Query guide.

To view code examples of retrieving documents with the MongoDB PHP Library, see Read Data from MongoDB.

API Documentation

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

Back

Read Data from MongoDB