diff --git a/README.md b/README.md index 0c07e7288..f201b2514 100644 --- a/README.md +++ b/README.md @@ -10,69 +10,70 @@ Laravel MongoDB This package adds functionalities to the Eloquent model and Query builder for MongoDB, using the original Laravel API. *This library extends the original Laravel classes, so it uses exactly the same methods.* - [Laravel MongoDB](#laravel-mongodb) - - [Installation](#installation) - - [Laravel version Compatibility](#laravel-version-compatibility) - - [Laravel](#laravel) - - [Lumen](#lumen) - - [Non-Laravel projects](#non-laravel-projects) - - [Testing](#testing) - - [Database Testing](#database-testing) - - [Configuration](#configuration) - - [Eloquent](#eloquent) - - [Extending the base model](#extending-the-base-model) - - [Extending the Authenticable base model](#extending-the-authenticable-base-model) - - [Soft Deletes](#soft-deletes) - - [Guarding attributes](#guarding-attributes) - - [Dates](#dates) - - [Basic Usage](#basic-usage) - - [MongoDB-specific operators](#mongodb-specific-operators) - - [MongoDB-specific Geo operations](#mongodb-specific-geo-operations) - - [Inserts, updates and deletes](#inserts-updates-and-deletes) - - [MongoDB specific operations](#mongodb-specific-operations) - - [Relationships](#relationships) - - [Basic Usage](#basic-usage-1) - - [belongsToMany and pivots](#belongstomany-and-pivots) - - [EmbedsMany Relationship](#embedsmany-relationship) - - [EmbedsOne Relationship](#embedsone-relationship) - - [Query Builder](#query-builder) - - [Basic Usage](#basic-usage-2) - - [Available operations](#available-operations) - - [Transactions](#transactions) - - [Schema](#schema) - - [Basic Usage](#basic-usage-3) - - [Geospatial indexes](#geospatial-indexes) - - [Extending](#extending) - - [Cross-Database Relationships](#cross-database-relationships) - - [Authentication](#authentication) - - [Queues](#queues) - - [Laravel specific](#laravel-specific) - - [Lumen specific](#lumen-specific) - - [Upgrading](#upgrading) - - [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3) - - [Security contact information](#security-contact-information) + - [Installation](#installation) + - [Laravel version Compatibility](#laravel-version-compatibility) + - [Laravel](#laravel) + - [Lumen](#lumen) + - [Non-Laravel projects](#non-laravel-projects) + - [Testing](#testing) + - [Database Testing](#database-testing) + - [Configuration](#configuration) + - [Eloquent](#eloquent) + - [Extending the base model](#extending-the-base-model) + - [Extending the Authenticable base model](#extending-the-authenticable-base-model) + - [Soft Deletes](#soft-deletes) + - [Guarding attributes](#guarding-attributes) + - [Dates](#dates) + - [Basic Usage](#basic-usage) + - [MongoDB-specific operators](#mongodb-specific-operators) + - [MongoDB-specific Geo operations](#mongodb-specific-geo-operations) + - [Inserts, updates and deletes](#inserts-updates-and-deletes) + - [MongoDB specific operations](#mongodb-specific-operations) + - [Relationships](#relationships) + - [Basic Usage](#basic-usage-1) + - [belongsToMany and pivots](#belongstomany-and-pivots) + - [EmbedsMany Relationship](#embedsmany-relationship) + - [EmbedsOne Relationship](#embedsone-relationship) + - [Query Builder](#query-builder) + - [Basic Usage](#basic-usage-2) + - [Available operations](#available-operations) + - [Transactions](#transactions) + - [Schema](#schema) + - [Basic Usage](#basic-usage-3) + - [Geospatial indexes](#geospatial-indexes) + - [Extending](#extending) + - [Cross-Database Relationships](#cross-database-relationships) + - [Authentication](#authentication) + - [Queues](#queues) + - [Laravel specific](#laravel-specific) + - [Lumen specific](#lumen-specific) + - [Upgrading](#upgrading) + - [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3) + - [Security contact information](#security-contact-information) Installation ------------ + Make sure you have the MongoDB PHP driver installed. You can find installation instructions at http://php.net/manual/en/mongodb.installation.php ### Laravel version Compatibility - Laravel | Package | Maintained -:---------|:---------------|:---------- - 9.x | 3.9.x | :white_check_mark: - 8.x | 3.8.x | :white_check_mark: - 7.x | 3.7.x | :x: - 6.x | 3.6.x | :white_check_mark: - 5.8.x | 3.5.x | :x: - 5.7.x | 3.4.x | :x: - 5.6.x | 3.4.x | :x: - 5.5.x | 3.3.x | :x: - 5.4.x | 3.2.x | :x: - 5.3.x | 3.1.x or 3.2.x | :x: - 5.2.x | 2.3.x or 3.0.x | :x: - 5.1.x | 2.2.x or 3.0.x | :x: - 5.0.x | 2.1.x | :x: - 4.2.x | 2.0.x | :x: +| Laravel | Package | Maintained | +| :------ | :------------- | :----------------- | +| 9.x | 3.9.x | :white_check_mark: | +| 8.x | 3.8.x | :white_check_mark: | +| 7.x | 3.7.x | :x: | +| 6.x | 3.6.x | :x: | +| 5.8.x | 3.5.x | :x: | +| 5.7.x | 3.4.x | :x: | +| 5.6.x | 3.4.x | :x: | +| 5.5.x | 3.3.x | :x: | +| 5.4.x | 3.2.x | :x: | +| 5.3.x | 3.1.x or 3.2.x | :x: | +| 5.2.x | 2.3.x or 3.0.x | :x: | +| 5.1.x | 2.2.x or 3.0.x | :x: | +| 5.0.x | 2.1.x | :x: | +| 4.2.x | 2.0.x | :x: | Install the package via Composer: @@ -139,8 +140,9 @@ use DatabaseMigrations; ``` Keep in mind that these traits are not yet supported: -- `use Database Transactions;` -- `use RefreshDatabase;` + +- `use Database Transactions;` +- `use RefreshDatabase;` Configuration ------------- @@ -179,6 +181,7 @@ Eloquent -------- ### Extending the base model + This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections. ```php @@ -229,6 +232,7 @@ class Book extends Model ``` ### Extending the Authenticatable base model + This package includes a MongoDB Authenticatable Eloquent class `Jenssegers\Mongodb\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. ```php @@ -354,8 +358,8 @@ $users = User::whereNull('age')->get(); ```php $users = User::whereDate('birthday', '2021-5-12')->get(); ``` -The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime` +The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime` **Advanced wheres** @@ -584,6 +588,44 @@ $bars = Bar::where('location', 'geoIntersects', [ ], ])->get(); ``` + +**GeoNear** + +You are able to make a `geoNear` query on mongoDB. +You don't need to specify the automatic fields on the model. +The returned instance is a collection. So you're able to make the [Collection](https://laravel.com/docs/9.x/collections) operations. +Just make sure that your model has a `location` field, and a [2ndSphereIndex](https://www.mongodb.com/docs/manual/core/2dsphere). +The data in the `location` field must be saved as [GeoJSON](https://www.mongodb.com/docs/manual/reference/geojson/). +The `location` points must be saved as [WGS84](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-WGS84) reference system for geometry calculation. That means, basically, you need to save `longitude and latitude`, in that order specifically, and to find near with calculated distance, you `need to do the same way`. + +``` +Bar::find("63a0cd574d08564f330ceae2")->update( + [ + 'location' => [ + 'type' => 'Point', + 'coordinates' => [ + -0.1367563, + 51.5100913 + ] + ] + ] +); +$bars = Bar::raw(function ($collection) { + return $collection->aggregate([ + [ + '$geoNear' => [ + "near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ], + "distanceField" => "dist.calculated", + "minDistance" => 0, + "maxDistance" => 6000, + "includeLocs" => "dist.location", + "spherical" => true, + ] + ] + ]); +}); +``` + ### 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). @@ -740,14 +782,16 @@ Relationships ### Basic Usage The only available relationships are: - - hasOne - - hasMany - - belongsTo - - belongsToMany + +- hasOne +- hasMany +- belongsTo +- belongsToMany The MongoDB-specific relationships are: - - embedsOne - - embedsMany + +- embedsOne +- embedsMany Here is a small example: @@ -889,7 +933,6 @@ class User extends Model 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 Relationship The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. @@ -954,7 +997,6 @@ When using MongoDB connections, you will be able to build fluent queries to perf 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(); @@ -967,10 +1009,12 @@ $hungerGames = 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. Transactions ------------ + Transactions require MongoDB version ^4.0 as well as deployment of replica set or sharded clusters. You can find more information [in the MongoDB docs](https://docs.mongodb.com/manual/core/transactions/) ### Basic Usage @@ -995,6 +1039,7 @@ DB::commit(); ``` To abort a transaction, call the `rollBack` method at any point during the transaction: + ```php DB::beginTransaction(); User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); @@ -1004,6 +1049,7 @@ DB::rollBack(); ``` **NOTE:** Transactions in MongoDB cannot be nested. DB::beginTransaction() function will start new transactions in a new created or existing session and will raise the RuntimeException when transactions already exist. See more in MongoDB official docs [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions) + ```php DB::beginTransaction(); User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); @@ -1017,6 +1063,7 @@ DB::rollBack(); Schema ------ + The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes. ### Basic Usage @@ -1046,17 +1093,19 @@ Schema::create('users', function ($collection) { ``` Inherited operations: -- create and drop -- collection -- hasCollection -- index and dropIndex (compound indexes supported as well) -- unique + +- create and drop +- collection +- hasCollection +- index and dropIndex (compound indexes supported as well) +- unique MongoDB specific operations: -- background -- sparse -- expire -- geospatial + +- background +- sparse +- expire +- geospatial All other (unsupported) operations are implemented as dummy pass-through methods because MongoDB does not use a predefined schema. @@ -1112,6 +1161,7 @@ class User extends Model } } ``` + Within your MongoDB model, you should define the relationship: ```php @@ -1129,6 +1179,7 @@ class Message extends Model ``` ### Authentication + If you want to use Laravel's native Auth functionality, register this included service provider: ```php @@ -1140,6 +1191,7 @@ This service provider will slightly modify the internal DatabaseReminderReposito If you don't use password reminders, you don't have to register this service provider and everything else should work just fine. ### Queues + If you want to use MongoDB as your database backend, change the driver in `config/queue.php`: ```php