Add Geonear instructions to ReadMe. Closes #1878 (#2487)

* create aggregate geonear instructions * create aggregate geonear instructions * create aggregate geonear instructions * create aggregate geonear instructions * create aggregate geonear instructions * chore: revert back readme changes * chore: minor readme change Co-authored-by: henriquetroiano <[email protected]> Co-authored-by: divine <[email protected]>
mongodb · Jan 15, 2023 · 551ec9f · 551ec9f
1 parent 317f702
commit 551ec9f
Showing 1 changed file with 128 additions and 76 deletions.
diff --git 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' => '[email protected]']);
@@ -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