@@ -83,9 +112,9 @@ In this new major release which supports the new MongoDB PHP extension, we also
Please change all `Jenssegers\Mongodb\Model` references to `Jenssegers\Mongodb\Eloquent\Model` either at the top of your model files, or your registered alias.
```php
useJenssegers\Mongodb\Eloquent\ModelasEloquent;
useJenssegers\Mongodb\Eloquent\Model;
classUserextendsEloquent
classUserextendsModel
{
//
}
...
...
@@ -98,7 +127,7 @@ Instead use the new `Jenssegers\Mongodb\Eloquent\HybridRelations` trait. This sh
```php
useJenssegers\Mongodb\Eloquent\HybridRelations;
classUserextendsEloquent
classUserextendsModel
{
useHybridRelations;
...
...
@@ -169,7 +198,7 @@ If you wish to use a connection string instead of a full key-value params, you c
Eloquent
--------
### Basic Usage
### Extending the base model
This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections.
```php
...
...
@@ -218,3 +247,860 @@ class Book extends Model
protected$connection='mongodb';
}
```
### Soft Deletes
When soft deleting a model, it is not actually removed from your database. Instead, a deleted_at timestamp is set on the record.
To enable soft deletes for a model, apply the `Jenssegers\Mongodb\Eloquent\SoftDeletes` Trait to the model:
```php
useJenssegers\Mongodb\Eloquent\SoftDeletes;
classUserextendsModel
{
useSoftDeletes;
protected$dates=['deleted_at'];
}
```
For more information check [Laravel Docs about Soft Deleting](http://laravel.com/docs/eloquent#soft-deleting).
### Dates
Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database.
```php
useJenssegers\Mongodb\Eloquent\Model;
classUserextendsModel
{
protected$dates=['birthday'];
}
```
This allows you to execute queries like this:
```php
$users=User::where(
'birthday','>',
newDateTime('-18 years')
)->get();
```
### Basic Usage
**Retrieving all models**
```php
$users=User::all();
```
**Retrieving a record by primary key**
```php
$user=User::find('517c43667db388101e00000f');
```
**Where**
```php
$users=
User::where('age','>',18)
->take(10)
->get();
```
**OR Statements**
```php
$posts=
Post::where('votes','>',0)
->orWhere('is_approved',true)
->get();
```
**AND statements**
```php
$users=
User::where('age','>',18)
->where('name','!=','John')
->get();
```
**whereIn**
```php
$users=User::whereIn('age',[16,18,20])->get();
```
When using `whereNotIn` objects will be returned if the field is non existent. Combine with `whereNotNull('age')` to leave out those documents.
**NOTE:** you can also use the Laravel regexp operations. These are a bit more flexible and will automatically convert your regular expression string to a `MongoDB\BSON\Regex` object.
Selects documents if a field is of the specified type. For more information check: http://docs.mongodb.org/manual/reference/operator/query/type/#op._S_type
```php
User::where('age','type',2)->get();
```
**Mod**
Performs a modulo operation on the value of a field and selects documents with a specified result.
```php
User::where('age','mod',[10,0])->get();
```
### MongoDB-specific Geo operations
**Near**
```php
$bars=Bar::where('location','near',[
'$geometry'=>[
'type'=>'Point',
'coordinates'=>[
-0.1367563,// longitude
51.5100913,// latitude
],
],
'$maxDistance'=>50,
])->get();
```
**GeoWithin**
```php
$bars=Bar::where('location','geoWithin',[
'$geometry'=>[
'type'=>'Polygon',
'coordinates'=>[
[
[-0.1450383,51.5069158],
[-0.1367563,51.5100913],
[-0.1270247,51.5013233],
[-0.1450383,51.5069158],
],
],
],
])->get();
```
**GeoIntersects**
```php
$bars=Bar::where('location','geoIntersects',[
'$geometry'=>[
'type'=>'LineString',
'coordinates'=>[
[-0.144044,51.515215],
[-0.129545,51.507864],
],
],
])->get();
```
### Inserts, updates and deletes
Inserting, updating and deleting records works just like the original Eloquent. Please check [Laravel Docs' Eloquent section](https://laravel.com/docs/6.x/eloquent).
Here, only the MongoDB-specific operations are specified.
### MongoDB specific operations
**Raw Expressions**
These expressions will be injected directly into the query.
```php
User::whereRaw([
'age'=>['$gt'=>30,'$lt'=>40],
])->get();
```
You can also perform raw expressions on the internal MongoCollection object. If this is executed on the model class, it will return a collection of models.
If this is executed on the query builder, it will return the original response.
**Cursor timeout**
To prevent `MongoCursorTimeout` exceptions, you can manually set a timeout value that will be applied to the cursor:
```php
DB::collection('users')->timeout(-1)->get();
```
**Upsert**
Update or insert a document. Additional options for the update method are passed directly to the native update method.
```php
// Query Builder
DB::collection('users')
->where('name','John')
->update($data,['upsert'=>true]);
// Eloquent
$user->update($data,['upsert'=>true]);
```
**Projections**
You can apply projections to your queries using the `project` method.
```php
DB::collection('items')
->project(['tags'=>['$slice'=>1]])
->get();
DB::collection('items')
->project(['tags'=>['$slice'=>[3,7]]])
->get();
```
**Projections with Pagination**
```php
$limit=25;
$projections=['id','name'];
DB::collection('items')
->paginate($limit,$projections);
```
**Push**
Add items to an array.
```php
DB::collection('users')
->where('name','John')
->push('items','boots');
$user->push('items','boots');
```
```php
DB::collection('users')
->where('name','John')
->push('messages',[
'from'=>'Jane Doe',
'message'=>'Hi John',
]);
$user->push('messages',[
'from'=>'Jane Doe',
'message'=>'Hi John',
]);
```
If you **DON'T** want duplicate items, set the third parameter to `true`:
```php
DB::collection('users')
->where('name','John')
->push('items','boots',true);
$user->push('items','boots',true);
```
**Pull**
Remove an item from an array.
```php
DB::collection('users')
->where('name','John')
->pull('items','boots');
$user->pull('items','boots');
```
```php
DB::collection('users')
->where('name','John')
->pull('messages',[
'from'=>'Jane Doe',
'message'=>'Hi John',
]);
$user->pull('messages',[
'from'=>'Jane Doe',
'message'=>'Hi John',
]);
```
**Unset**
Remove one or more fields from a document.
```php
DB::collection('users')
->where('name','John')
->unset('note');
$user->unset('note');
```
### Relationships
The only available relationships are:
- hasOne
- hasMany
- belongsTo
- belongsToMany
The MongoDB-specific relationships are:
- embedsOne
- embedsMany
Here is a small example:
```php
useJenssegers\Mongodb\Eloquent\Model;
classUserextendsModel
{
publicfunctionitems()
{
return$this->hasMany(Item::class);
}
}
```
The inverse relation of `hasMany` is `belongsTo`:
```php
useJenssegers\Mongodb\Eloquent\Model;
classItemextendsModel
{
publicfunctionuser()
{
return$this->belongsTo(User::class);
}
}
```
### belongsToMany and pivots
The belongsToMany relation will not use a pivot "table", but will push id's to a __related_ids__ attribute instead. This makes the second parameter for the belongsToMany method useless.
If you want to define custom keys for your relation, set it to `null`:
```php
useJenssegers\Mongodb\Eloquent\Mode;
classUserextendsModel
{
publicfunctiongroups()
{
return$this->belongsToMany(
Group::class,null,'user_ids','group_ids'
);
}
}
```
### EmbedsMany Relationship
If you want to embed models, rather than referencing them, you can use the `embedsMany` relation. This relation is similar to the `hasMany` relation, but embeds the models inside the parent object.
**REMEMBER**: These relations return Eloquent collections, they don't return query builder objects!
```php
useJenssegers\Mongodb\Eloquent\Model;
classUserextendsModel
{
publicfunctionbooks()
{
return$this->embedsMany(Book::class);
}
}
```
You can access the embedded models through the dynamic property:
```php
$user=User::first();
foreach($user->booksas$book){
//
}
```
The inverse relation is auto*magically* available. You don't need to define this reverse relation.
```php
$book=Book::first();
$user=$book->user;
```
Inserting and updating embedded models works similar to the `hasMany` relation:
```php
$book=$user->books()->save(
newBook(['title'=>'A Game of Thrones'])
);
// or
$book=
$user->books()
->create(['title'=>'A Game of Thrones']);
```
You can update embedded models using their `save` method (available since release 2.0.0):
```php
$book=$user->books()->first();
$book->title='A Game of Thrones';
$book->save();
```
You can remove an embedded model by using the `destroy` method on the relation, or the `delete` method on the model (available since release 2.0.0):
```php
$book->delete();
// Similar operation
$user->books()->destroy($book);
```
If you want to add or remove an embedded model, without touching the database, you can use the `associate` and `dissociate` methods.
To eventually write the changes to the database, save the parent object:
```php
$user->books()->associate($book);
$user->save();
```
Like other relations, embedsMany assumes the local key of the relationship based on the model name. You can override the default local key by passing a second argument to the embedsMany method:
```php
useJenssegers\Mongodb\Eloquent\Model;
classUserextendsModel
{
publicfunctionbooks()
{
return$this->embedsMany(Book::class,'local_key');
}
}
```
Embedded relations will return a Collection of embedded items instead of a query builder. Check out the available operations here: https://laravel.com/docs/master/collections
### EmbedsOne Relations
The embedsOne relation is similar to the embedsMany relation, but only embeds a single model.
```php
useJenssegers\Mongodb\Eloquent\Model;
classBookextendsModel
{
publicfunctionauthor()
{
return$this->embedsOne(Author::class);
}
}
```
You can access the embedded models through the dynamic property:
```php
$book=Book::first();
$author=$book->author;
```
Inserting and updating embedded models works similar to the `hasOne` relation:
```php
$author=$book->author()->save(
newAuthor(['name'=>'John Doe'])
);
// Similar
$author=
$book->author()
->create(['name'=>'John Doe']);
```
You can update the embedded model using the `save` method (available since release 2.0.0):
```php
$author=$book->author;
$author->name='Jane Doe';
$author->save();
```
You can replace the embedded model with a new model like this:
```php
$newAuthor=newAuthor(['name'=>'Jane Doe']);
$book->author()->save($newAuthor);
```
Query Builder
-------------
The database driver plugs right into the original query builder.
When using MongoDB connections, you will be able to build fluent queries to perform database operations.
For your convenience, there is a `collection` alias for `table` as well as some additional MongoDB specific operators/operations.
```php
$books = DB::collection('books')->get();
$hungerGames =
DB::collection('books')
->where('name', 'Hunger Games')
->first();
```
If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), there is the same functionality.
### Available operations
To see the available operations, check the [Eloquent](#eloquent) section.
Schema
------
The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes.
```php
Schema::create('users',function($collection){
$collection->index('name');
$collection->unique('email');
});
```
You can also pass all the parameters specified [in the MongoDB docs](https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#options-for-all-index-types) to the `$options` parameter:
```php
Schema::create('users',function($collection){
$collection->index(
'username',
null,
null,
[
'sparse'=>true,
'unique'=>true,
'background'=>true,
]
);
});
```
Inherited operations:
- create and drop
- collection
- hasCollection
- index and dropIndex (compound indexes supported as well)
- unique
MongoDB specific operations:
- background
- sparse
- expire
- geospatial
All other (unsupported) operations are implemented as dummy pass-through methods, because MongoDB does not use a predefined schema.
Read more about the schema builder on [Laravel Docs](https://laravel.com/docs/6.0/migrations#tables)
### Geospatial indexes
Geospatial indexes are handy for querying location-based documents.
They come in two forms: `2d` and `2dsphere`. Use the schema builder to add these to a collection.
```php
Schema::create('bars',function($collection){
$collection->geospatial('location','2d');
});
```
To add a `2dsphere` index:
```php
Schema::create('bars',function($collection){
$collection->geospatial('location','2dsphere');
});
```
Extending
---------
### Cross-Database Relations
If you're using a hybrid MongoDB and SQL setup, you can define relationships across them.
The model will automatically return a MongoDB-related or SQL-related relation based on the type of the related model.
If you want this functionality to work both ways, your SQL-models will need use the `Jenssegers\Mongodb\Eloquent\HybridRelations` trait.
**This functionality only works for `hasOne`, `hasMany` and `belongsTo`.**
The MySQL model shoul use the `HybridRelations` trait:
```php
useJenssegers\Mongodb\Eloquent\HybridRelations;
classUserextendsModel
{
useHybridRelations;
protected$connection='mysql';
publicfunctionmessages()
{
return$this->hasMany(Message::class);
}
}
```
Within your MongoDB model, you should define the relationship:
```php
useJenssegers\Mongodb\Eloquent\Model;
classMessageextendsModel
{
protected$connection='mongodb';
publicfunctionuser()
{
return$this->belongsTo(User::class);
}
}
```
### Authentication
If you want to use Laravel's native Auth functionality, register this included service provider:
If you want to use this library with [Sentry](https://cartalyst.com/manual/sentry), then check out https://github.com/jenssegers/Laravel-MongoDB-Sentry
### Sessions
The MongoDB session driver is available in a separate package, check out https://github.com/jenssegers/Laravel-MongoDB-Session
