Databases and Collections

Overview

In this guide, you can learn how to use Laravel MongoDB to access and manage MongoDB databases and collections.

MongoDB organizes data in a hierarchical structure. A MongoDB deployment contains one or more databases, and each database contains one or more collections. In each collection, MongoDB stores data as documents that contain field-and-value pairs. In Laravel MongoDB, you can access documents through Eloquent models.

To learn more about the document data format, see Documents in the Server manual.

Specify the Database in a Connection Configuration

You can specify a database name that a connection uses in your application's config/database.php file. The connections property in this file stores all your database connection information, such as your connection string, database name, and optionally, authentication details. After you specify a database connection, you can perform database-level operations and access collections that the database contains.

If you set the database name in the database property to the name of a nonexistent database, Laravel still makes a valid connection. When you insert any data into a collection in the database, the server creates it automatically.

The following example shows how to set a default database connection and create a database connection to the animals database in the config/database.php file by setting the dsn and database properties:

'default' => 'mongodb',
'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb://localhost:27017/',
        'database' => 'animals',
    ], ...
]

When you set a default database connection, Laravel MongoDB uses that connection for operations, but you can specify multiple database connections in your config/database.php file.

The following example shows how to specify multiple database connections (mongodb and mongodb_alt) to access the animals and plants databases:

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb://localhost:27017/',
        'database' => 'animals',
    ],
    'mongodb_alt' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb://localhost:27017/',
        'database' => 'plants',
    ]
], ...

If your application contains multiple database connections and you want to store your model in a database other than the default, override the $connection property in your Model class.

The following example shows how to override the $connection property on the Flower model class to use the mongodb_alt connection. This directs Laravel MongoDB to store the model in the flowers collection of the plants database, instead of in the default database:

class Flower extends Model
{
    protected $connection = 'mongodb_alt';
}

Access a Collection

When you create model class that extends MongoDB\Laravel\Eloquent\Model, Laravel MongoDB stores the model data in a collection with a name formatted as the snake case plural form of your model class name.

For example, if you create a model class called Flower, Laravel applies the model to the flowers collection in the database.

We generally recommend that you use the Eloquent ORM to access a collection for code readability and maintainability. The following example specifies a find operation by using the Flower class, so Laravel retrieves results from the flowers collection:

Flower::where('name', 'Water Lily')->get()

If you are unable to accomplish your operation by using an Eloquent model, you can access the query builder by calling the collection() method on the DB facade. The following example shows the same query as in the preceding example, but the query is constructed by using the DB::collection() method:

DB::connection('mongodb')
    ->collection('flowers')
    ->where('name', 'Water Lily')
    ->get()

List Collections

To see information about each of the collections in a database, call the listCollections() method.

The following example accesses a database connection, then calls the listCollections() method to retrieve information about the collections in the database:

$collections = DB::connection('mongodb')->getMongoDB()->listCollections();

Create and Drop Collections

To learn how to create and drop collections, see the Perform Laravel Migrations section in the Schema Builder guide.