Skip to content

Add Geonear instructions to ReadMe. Closes #1878 #2487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jan 15, 2023
Merged

Add Geonear instructions to ReadMe. Closes #1878 #2487

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
09cd51d
create aggregate geonear instructions
Dec 20, 2022
21c4880
create aggregate geonear instructions
Dec 20, 2022
8aac21d
create aggregate geonear instructions
Dec 20, 2022
4858361
create aggregate geonear instructions
Dec 20, 2022
b70a4d5
create aggregate geonear instructions
Dec 20, 2022
d365697
chore: revert back readme changes
divine Jan 15, 2023
efd98f3
chore: minor readme change
divine Jan 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 128 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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
-------------
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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**

Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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();

Expand All @@ -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
Expand All @@ -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]']);
Expand All @@ -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']);
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -1112,6 +1161,7 @@ class User extends Model
}
}
```

Within your MongoDB model, you should define the relationship:

```php
Expand All @@ -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
Expand All @@ -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
Expand Down