Skip to content

Commit 551ec9f

Browse files
henriquetroianohenriquetroianodivine
authored
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]>
1 parent 317f702 commit 551ec9f

File tree

1 file changed

+128
-76
lines changed

1 file changed

+128
-76
lines changed

Diff for: ‎README.md

+128-76
Original file line numberDiff line numberDiff line change
@@ -10,69 +10,70 @@ Laravel MongoDB
1010
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.*
1111

1212
- [Laravel MongoDB](#laravel-mongodb)
13-
- [Installation](#installation)
14-
- [Laravel version Compatibility](#laravel-version-compatibility)
15-
- [Laravel](#laravel)
16-
- [Lumen](#lumen)
17-
- [Non-Laravel projects](#non-laravel-projects)
18-
- [Testing](#testing)
19-
- [Database Testing](#database-testing)
20-
- [Configuration](#configuration)
21-
- [Eloquent](#eloquent)
22-
- [Extending the base model](#extending-the-base-model)
23-
- [Extending the Authenticable base model](#extending-the-authenticable-base-model)
24-
- [Soft Deletes](#soft-deletes)
25-
- [Guarding attributes](#guarding-attributes)
26-
- [Dates](#dates)
27-
- [Basic Usage](#basic-usage)
28-
- [MongoDB-specific operators](#mongodb-specific-operators)
29-
- [MongoDB-specific Geo operations](#mongodb-specific-geo-operations)
30-
- [Inserts, updates and deletes](#inserts-updates-and-deletes)
31-
- [MongoDB specific operations](#mongodb-specific-operations)
32-
- [Relationships](#relationships)
33-
- [Basic Usage](#basic-usage-1)
34-
- [belongsToMany and pivots](#belongstomany-and-pivots)
35-
- [EmbedsMany Relationship](#embedsmany-relationship)
36-
- [EmbedsOne Relationship](#embedsone-relationship)
37-
- [Query Builder](#query-builder)
38-
- [Basic Usage](#basic-usage-2)
39-
- [Available operations](#available-operations)
40-
- [Transactions](#transactions)
41-
- [Schema](#schema)
42-
- [Basic Usage](#basic-usage-3)
43-
- [Geospatial indexes](#geospatial-indexes)
44-
- [Extending](#extending)
45-
- [Cross-Database Relationships](#cross-database-relationships)
46-
- [Authentication](#authentication)
47-
- [Queues](#queues)
48-
- [Laravel specific](#laravel-specific)
49-
- [Lumen specific](#lumen-specific)
50-
- [Upgrading](#upgrading)
51-
- [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3)
52-
- [Security contact information](#security-contact-information)
13+
- [Installation](#installation)
14+
- [Laravel version Compatibility](#laravel-version-compatibility)
15+
- [Laravel](#laravel)
16+
- [Lumen](#lumen)
17+
- [Non-Laravel projects](#non-laravel-projects)
18+
- [Testing](#testing)
19+
- [Database Testing](#database-testing)
20+
- [Configuration](#configuration)
21+
- [Eloquent](#eloquent)
22+
- [Extending the base model](#extending-the-base-model)
23+
- [Extending the Authenticable base model](#extending-the-authenticable-base-model)
24+
- [Soft Deletes](#soft-deletes)
25+
- [Guarding attributes](#guarding-attributes)
26+
- [Dates](#dates)
27+
- [Basic Usage](#basic-usage)
28+
- [MongoDB-specific operators](#mongodb-specific-operators)
29+
- [MongoDB-specific Geo operations](#mongodb-specific-geo-operations)
30+
- [Inserts, updates and deletes](#inserts-updates-and-deletes)
31+
- [MongoDB specific operations](#mongodb-specific-operations)
32+
- [Relationships](#relationships)
33+
- [Basic Usage](#basic-usage-1)
34+
- [belongsToMany and pivots](#belongstomany-and-pivots)
35+
- [EmbedsMany Relationship](#embedsmany-relationship)
36+
- [EmbedsOne Relationship](#embedsone-relationship)
37+
- [Query Builder](#query-builder)
38+
- [Basic Usage](#basic-usage-2)
39+
- [Available operations](#available-operations)
40+
- [Transactions](#transactions)
41+
- [Schema](#schema)
42+
- [Basic Usage](#basic-usage-3)
43+
- [Geospatial indexes](#geospatial-indexes)
44+
- [Extending](#extending)
45+
- [Cross-Database Relationships](#cross-database-relationships)
46+
- [Authentication](#authentication)
47+
- [Queues](#queues)
48+
- [Laravel specific](#laravel-specific)
49+
- [Lumen specific](#lumen-specific)
50+
- [Upgrading](#upgrading)
51+
- [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3)
52+
- [Security contact information](#security-contact-information)
5353

5454
Installation
5555
------------
56+
5657
Make sure you have the MongoDB PHP driver installed. You can find installation instructions at http://php.net/manual/en/mongodb.installation.php
5758

5859
### Laravel version Compatibility
5960

60-
Laravel | Package | Maintained
61-
:---------|:---------------|:----------
62-
9.x | 3.9.x | :white_check_mark:
63-
8.x | 3.8.x | :white_check_mark:
64-
7.x | 3.7.x | :x:
65-
6.x | 3.6.x | :white_check_mark:
66-
5.8.x | 3.5.x | :x:
67-
5.7.x | 3.4.x | :x:
68-
5.6.x | 3.4.x | :x:
69-
5.5.x | 3.3.x | :x:
70-
5.4.x | 3.2.x | :x:
71-
5.3.x | 3.1.x or 3.2.x | :x:
72-
5.2.x | 2.3.x or 3.0.x | :x:
73-
5.1.x | 2.2.x or 3.0.x | :x:
74-
5.0.x | 2.1.x | :x:
75-
4.2.x | 2.0.x | :x:
61+
| Laravel | Package | Maintained |
62+
| :------ | :------------- | :----------------- |
63+
| 9.x | 3.9.x | :white_check_mark: |
64+
| 8.x | 3.8.x | :white_check_mark: |
65+
| 7.x | 3.7.x | :x: |
66+
| 6.x | 3.6.x | :x: |
67+
| 5.8.x | 3.5.x | :x: |
68+
| 5.7.x | 3.4.x | :x: |
69+
| 5.6.x | 3.4.x | :x: |
70+
| 5.5.x | 3.3.x | :x: |
71+
| 5.4.x | 3.2.x | :x: |
72+
| 5.3.x | 3.1.x or 3.2.x | :x: |
73+
| 5.2.x | 2.3.x or 3.0.x | :x: |
74+
| 5.1.x | 2.2.x or 3.0.x | :x: |
75+
| 5.0.x | 2.1.x | :x: |
76+
| 4.2.x | 2.0.x | :x: |
7677

7778
Install the package via Composer:
7879

@@ -139,8 +140,9 @@ use DatabaseMigrations;
139140
```
140141

141142
Keep in mind that these traits are not yet supported:
142-
- `use Database Transactions;`
143-
- `use RefreshDatabase;`
143+
144+
- `use Database Transactions;`
145+
- `use RefreshDatabase;`
144146

145147
Configuration
146148
-------------
@@ -179,6 +181,7 @@ Eloquent
179181
--------
180182

181183
### Extending the base model
184+
182185
This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections.
183186

184187
```php
@@ -229,6 +232,7 @@ class Book extends Model
229232
```
230233

231234
### Extending the Authenticatable base model
235+
232236
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.
233237

234238
```php
@@ -354,8 +358,8 @@ $users = User::whereNull('age')->get();
354358
```php
355359
$users = User::whereDate('birthday', '2021-5-12')->get();
356360
```
357-
The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime`
358361

362+
The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime`
359363

360364
**Advanced wheres**
361365

@@ -584,6 +588,44 @@ $bars = Bar::where('location', 'geoIntersects', [
584588
],
585589
])->get();
586590
```
591+
592+
**GeoNear**
593+
594+
You are able to make a `geoNear` query on mongoDB.
595+
You don't need to specify the automatic fields on the model.
596+
The returned instance is a collection. So you're able to make the [Collection](https://laravel.com/docs/9.x/collections) operations.
597+
Just make sure that your model has a `location` field, and a [2ndSphereIndex](https://www.mongodb.com/docs/manual/core/2dsphere).
598+
The data in the `location` field must be saved as [GeoJSON](https://www.mongodb.com/docs/manual/reference/geojson/).
599+
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`.
600+
601+
```
602+
Bar::find("63a0cd574d08564f330ceae2")->update(
603+
[
604+
'location' => [
605+
'type' => 'Point',
606+
'coordinates' => [
607+
-0.1367563,
608+
51.5100913
609+
]
610+
]
611+
]
612+
);
613+
$bars = Bar::raw(function ($collection) {
614+
return $collection->aggregate([
615+
[
616+
'$geoNear' => [
617+
"near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ],
618+
"distanceField" => "dist.calculated",
619+
"minDistance" => 0,
620+
"maxDistance" => 6000,
621+
"includeLocs" => "dist.location",
622+
"spherical" => true,
623+
]
624+
]
625+
]);
626+
});
627+
```
628+
587629
### Inserts, updates and deletes
588630

589631
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
740782
### Basic Usage
741783

742784
The only available relationships are:
743-
- hasOne
744-
- hasMany
745-
- belongsTo
746-
- belongsToMany
785+
786+
- hasOne
787+
- hasMany
788+
- belongsTo
789+
- belongsToMany
747790

748791
The MongoDB-specific relationships are:
749-
- embedsOne
750-
- embedsMany
792+
793+
- embedsOne
794+
- embedsMany
751795

752796
Here is a small example:
753797

@@ -889,7 +933,6 @@ class User extends Model
889933

890934
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
891935

892-
893936
### EmbedsOne Relationship
894937

895938
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
954997

955998
For your convenience, there is a `collection` alias for `table` as well as some additional MongoDB specific operators/operations.
956999

957-
9581000
```php
9591001
$books = DB::collection('books')->get();
9601002

@@ -967,10 +1009,12 @@ $hungerGames =
9671009
If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), there is the same functionality.
9681010

9691011
### Available operations
1012+
9701013
To see the available operations, check the [Eloquent](#eloquent) section.
9711014

9721015
Transactions
9731016
------------
1017+
9741018
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/)
9751019

9761020
### Basic Usage
@@ -995,6 +1039,7 @@ DB::commit();
9951039
```
9961040

9971041
To abort a transaction, call the `rollBack` method at any point during the transaction:
1042+
9981043
```php
9991044
DB::beginTransaction();
10001045
User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => '[email protected]']);
@@ -1004,6 +1049,7 @@ DB::rollBack();
10041049
```
10051050

10061051
**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)
1052+
10071053
```php
10081054
DB::beginTransaction();
10091055
User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']);
@@ -1017,6 +1063,7 @@ DB::rollBack();
10171063

10181064
Schema
10191065
------
1066+
10201067
The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes.
10211068

10221069
### Basic Usage
@@ -1046,17 +1093,19 @@ Schema::create('users', function ($collection) {
10461093
```
10471094

10481095
Inherited operations:
1049-
- create and drop
1050-
- collection
1051-
- hasCollection
1052-
- index and dropIndex (compound indexes supported as well)
1053-
- unique
1096+
1097+
- create and drop
1098+
- collection
1099+
- hasCollection
1100+
- index and dropIndex (compound indexes supported as well)
1101+
- unique
10541102

10551103
MongoDB specific operations:
1056-
- background
1057-
- sparse
1058-
- expire
1059-
- geospatial
1104+
1105+
- background
1106+
- sparse
1107+
- expire
1108+
- geospatial
10601109

10611110
All other (unsupported) operations are implemented as dummy pass-through methods because MongoDB does not use a predefined schema.
10621111

@@ -1112,6 +1161,7 @@ class User extends Model
11121161
}
11131162
}
11141163
```
1164+
11151165
Within your MongoDB model, you should define the relationship:
11161166

11171167
```php
@@ -1129,6 +1179,7 @@ class Message extends Model
11291179
```
11301180

11311181
### Authentication
1182+
11321183
If you want to use Laravel's native Auth functionality, register this included service provider:
11331184

11341185
```php
@@ -1140,6 +1191,7 @@ This service provider will slightly modify the internal DatabaseReminderReposito
11401191
If you don't use password reminders, you don't have to register this service provider and everything else should work just fine.
11411192

11421193
### Queues
1194+
11431195
If you want to use MongoDB as your database backend, change the driver in `config/queue.php`:
11441196

11451197
```php

0 commit comments

Comments
 (0)