Skip to content

Commit 904fbd2

Browse files
pdphilippdphilip
committed
V5 README
1 parent 41cd5b2 commit 904fbd2

File tree

1 file changed

+124
-117
lines changed

1 file changed

+124
-117
lines changed

‎README.md‎

Lines changed: 124 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,120 @@
1-
<img align="left" width="70" height="70" src="https://cdn.snipform.io/pdphilip/elasticsearch/laravel-x-es.png">
2-
3-
# Laravel-Elasticsearch
1+
<img
2+
src="https://cdn.snipform.io/pdphilip/elasticsearch/laravel-es-banner.png"
3+
alt="Laravel Elasticsearch"
4+
/>
45

56
[![Latest Stable Version](http://img.shields.io/github/release/pdphilip/laravel-elasticsearch.svg)](https://packagist.org/packages/pdphilip/elasticsearch)
67
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/pdphilip/laravel-elasticsearch/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/pdphilip/laravel-elasticsearch/actions/workflows/run-tests.yml?query=branch%3Amain)
78
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/pdphilip/laravel-elasticsearch/phpstan.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/pdphilip/laravel-elasticsearch/actions/workflows/phpstan.yml?query=branch%3Amain++)
89
[![Total Downloads](http://img.shields.io/packagist/dm/pdphilip/elasticsearch.svg)](https://packagist.org/packages/pdphilip/elasticsearch)
9-
### Laravel-Elasticsearch: An Elasticsearch implementation of Laravel's Eloquent ORM
10+
11+
## Laravel-Elasticsearch <br/> An Elasticsearch implementation of Laravel's Eloquent ORM
12+
13+
### The Power of Elasticsearch with Laravel's Eloquent
1014

1115
This package extends Laravel's Eloquent model and query builder with seamless integration of Elasticsearch functionalities. Designed to feel native to Laravel, this package enables you to work with Eloquent models while leveraging the
1216
powerful search and analytics capabilities of Elasticsearch.
1317

14-
Examples:
18+
---
19+
20+
The Eloquent you already know:
1521

1622
```php
17-
$logs = UserLog::where('created_at','>=',Carbon::now()->subDays(30))->get();
23+
UserLog::where('created_at','>=',Carbon::now()->subDays(30))->get();
1824
```
1925

2026
```php
21-
$updates = UserLog::where('status', 1)->update(['status' => 4]);
27+
UserLog::create([
28+
'user_id' => '2936adb0-b10d-11ed-8e03-0b234bda3e12',
29+
'ip' => '62.182.98.146',
30+
'location' => [40.7185,-74.0025],
31+
'country_code' => 'US',
32+
'status' => 1,
33+
]);
2234
```
2335

2436
```php
25-
$updates = UserLog::where('status', 1)->paginate(50);
37+
UserLog::where('status', 1)->update(['status' => 4]);
2638
```
2739

2840
```php
29-
$profiles = UserProfile::whereIn('country_code',['US','CA'])->orderByDesc('last_login')->take(10)->get();
41+
UserLog::where('status', 4)->orderByDesc('created_at')->paginate(50);
3042
```
3143

3244
```php
33-
$deleted = UserProfile::where('state','unsubscribed')->where('updated_at','<=',Carbon::now()->subDays(90))->delete();
45+
UserProfile::whereIn('country_code',['US','CA'])
46+
->orderByDesc('last_login')->take(10)->get();
3447
```
3548

3649
```php
37-
$search = UserProfile::phrase('loves espressos')->highlight()->search();
50+
UserProfile::where('state','unsubscribed')
51+
->where('updated_at','<=',Carbon::now()->subDays(90))->delete();
52+
```
53+
54+
Elasticsearch with Eloquent:
55+
56+
```php
57+
UserProfile::searchTerm('Laravel')->orSearchTerm('Elasticsearch')->get();
58+
```
59+
60+
```php
61+
UserProfile::searchPhrasePrefix('loves espressos and t')->highlight()->get();
62+
```
63+
64+
```php
65+
UserProfile::whereMatch('bio', 'PHP')->get();
66+
```
67+
68+
```php
69+
UserLog::whereGeoDistance('location', '10km', [40.7185,-74.0025])->get();
70+
```
71+
72+
```php
73+
UserProfile::whereFuzzy('description', 'qick brwn fx')->get();
74+
```
75+
76+
Built in Relationships (even to SQL models):
77+
78+
```php
79+
UserLog::where('status', 1)->orderByDesc('created_at')->with('user')->get();
3880
```
3981

40-
### Read the [Documentation](https://elasticsearch.pdphilip.com/)
41-
---
42-
> #### Using [OpenSearch](https://opensearch.pdphilip.com/)? [Github](https://github.com/pdphilip/laravel-opensearch)
43-
---
44-
> #### [Package Tests](https://github.com/pdphilip/laravel-elasticsearch-tests)
4582
---
4683

84+
# Read the [Documentation](https://elasticsearch.pdphilip.com/)
85+
4786
## Installation
4887

4988
### Maintained versions (Elasticsearch 8.x):
5089

51-
**Laravel 10.x & 11.x (main):**
90+
**Laravel 10.x, 11.x & 12.x (main):**
5291

5392
```bash
5493
composer require pdphilip/elasticsearch
5594
```
5695

57-
| Laravel Version | Command | Maintained |
58-
|-----------------|------------------------------------------------|------------|
59-
| Laravel 10 & 11 | `composer require pdphilip/elasticsearch:~4 ` | ✅ |
60-
| Laravel 9 | `composer require pdphilip/elasticsearch:~3.9` | ✅ |
61-
| Laravel 8 | `composer require pdphilip/elasticsearch:~3.8` | ✅ |
96+
| Laravel Version | Command | Maintained |
97+
|--------------------|------------------------------------------------|------------|
98+
| Laravel 10/11/12 | `composer require pdphilip/elasticsearch:~5 ` | ✅ Active |
99+
| Laravel 10/11 (v4) | `composer require pdphilip/elasticsearch:~4` | 🛠️ LTS |
100+
| Laravel 9 | `composer require pdphilip/elasticsearch:~3.9` | 🛠️ LTS |
101+
| Laravel 8 | `composer require pdphilip/elasticsearch:~3.8` | 🛠️ LTS |
62102

63103
### Unmaintained versions (Elasticsearch 8.x):
64104

65105
| Laravel Version | Command | Maintained |
66106
|-------------------|------------------------------------------------|------------|
67-
| Laravel 7.x | `composer require pdphilip/elasticsearch:~2.7` | ❌ |
68-
| Laravel 6.x (5.8) | `composer require pdphilip/elasticsearch:~2.6` | ❌ |
107+
| Laravel 7.x | `composer require pdphilip/elasticsearch:~2.7` | ❌ EOL |
108+
| Laravel 6.x (5.8) | `composer require pdphilip/elasticsearch:~2.6` | ❌ EOL |
69109

70110
### Unmaintained versions (Elasticsearch 7.x):
71111

72112
| Laravel Version | Command | Maintained |
73113
|-------------------|------------------------------------------------|------------|
74-
| Laravel 9.x | `composer require pdphilip/elasticsearch:~1.9` | ❌ |
75-
| Laravel 8.x | `composer require pdphilip/elasticsearch:~1.8` | ❌ |
76-
| Laravel 7.x | `composer require pdphilip/elasticsearch:~1.7` | ❌ |
77-
| Laravel 6.x (5.8) | `composer require pdphilip/elasticsearch:~1.6` | ❌ |
114+
| Laravel 9.x | `composer require pdphilip/elasticsearch:~1.9` | ❌ EOL |
115+
| Laravel 8.x | `composer require pdphilip/elasticsearch:~1.8` | ❌ EOL |
116+
| Laravel 7.x | `composer require pdphilip/elasticsearch:~1.7` | ❌ EOL |
117+
| Laravel 6.x (5.8) | `composer require pdphilip/elasticsearch:~1.6` | ❌ EOL |
78118

79119
## Configuration
80120

@@ -89,9 +129,9 @@ ES_CLOUD_ID=
89129
ES_API_ID=
90130
ES_API_KEY=
91131
ES_SSL_CA=
92-
ES_INDEX_PREFIX=my_app
132+
ES_INDEX_PREFIX=my_app_
93133
# prefix will be added to all indexes created by the package with an underscore
94-
# ex: my_app_user_logs for UserLog.php model
134+
# ex: my_app_user_logs for UserLog model
95135
ES_SSL_CERT=
96136
ES_SSL_CERT_PASSWORD=
97137
ES_SSL_KEY=
@@ -102,6 +142,9 @@ ES_OPT_VERIFY_SSL=true
102142
ES_OPT_RETRIES=
103143
ES_OPT_META_HEADERS=true
104144
ES_ERROR_INDEX=
145+
ES_OPT_BYPASS_MAP_VALIDATION=false
146+
ES_OPT_DEFAULT_LIMIT=1000
147+
105148
```
106149

107150
For multiple nodes, pass in as comma-separated:
@@ -122,7 +165,7 @@ ES_CLOUD_ID=XXXXX:ZXVyb3BlLXdl.........SQwYzM1YzU5ODI5MTE0NjQ3YmEyNDZlYWUzOGNkN2
122165
ES_API_ID=
123166
ES_API_KEY=
124167
ES_SSL_CA=
125-
ES_INDEX_PREFIX=my_app
168+
ES_INDEX_PREFIX=my_app_
126169
ES_ERROR_INDEX=
127170
```
128171

@@ -132,35 +175,37 @@ ES_ERROR_INDEX=
132175

133176
```php
134177
'elasticsearch' => [
135-
'driver' => 'elasticsearch',
136-
'auth_type' => env('ES_AUTH_TYPE', 'http'), //http or cloud
137-
'hosts' => explode(',', env('ES_HOSTS', 'http://localhost:9200')),
138-
'username' => env('ES_USERNAME', ''),
139-
'password' => env('ES_PASSWORD', ''),
140-
'cloud_id' => env('ES_CLOUD_ID', ''),
141-
'api_id' => env('ES_API_ID', ''),
142-
'api_key' => env('ES_API_KEY', ''),
143-
'ssl_cert' => env('ES_SSL_CA', ''),
144-
'ssl' => [
145-
'cert' => env('ES_SSL_CERT', ''),
178+
'driver' => 'elasticsearch',
179+
'auth_type' => env('ES_AUTH_TYPE', 'http'), //http or cloud
180+
'hosts' => explode(',', env('ES_HOSTS', 'http://localhost:9200')),
181+
'username' => env('ES_USERNAME', ''),
182+
'password' => env('ES_PASSWORD', ''),
183+
'cloud_id' => env('ES_CLOUD_ID', ''),
184+
'api_id' => env('ES_API_ID', ''),
185+
'api_key' => env('ES_API_KEY', ''),
186+
'ssl_cert' => env('ES_SSL_CA', ''),
187+
'ssl' => [
188+
'cert' => env('ES_SSL_CERT', ''),
146189
'cert_password' => env('ES_SSL_CERT_PASSWORD', ''),
147-
'key' => env('ES_SSL_KEY', ''),
148-
'key_password' => env('ES_SSL_KEY_PASSWORD', ''),
190+
'key' => env('ES_SSL_KEY', ''),
191+
'key_password' => env('ES_SSL_KEY_PASSWORD', ''),
149192
],
150193
'index_prefix' => env('ES_INDEX_PREFIX', false),
151-
'options' => [
152-
'allow_id_sort' => env('ES_OPT_ID_SORTABLE', false),
194+
'options' => [
195+
'bypass_map_validation' => env('ES_OPT_BYPASS_MAP_VALIDATION', false),
196+
'logging' => env('ES_OPT_LOGGING', false),
153197
'ssl_verification' => env('ES_OPT_VERIFY_SSL', true),
154-
'retires' => env('ES_OPT_RETRIES', null),
155-
'meta_header' => env('ES_OPT_META_HEADERS', true),
198+
'retires' => env('ES_OPT_RETRIES', null),
199+
'meta_header' => env('ES_OPT_META_HEADERS', true),
200+
'default_limit' => env('ES_OPT_DEFAULT_LIMIT', true),
201+
'allow_id_sort' => env('ES_OPT_ID_SORTABLE', false),
156202
],
157-
'error_log_index' => env('ES_ERROR_INDEX', false), //If set will log ES errors to this index, ex: 'laravel_es_errors'
158203
],
159204
```
160205

161206
### 3. If packages are not autoloaded, add the service provider:
162207

163-
For **Laravel 11**:
208+
For **Laravel 11 +**:
164209

165210
```php
166211
//bootstrap/providers.php
@@ -191,82 +236,44 @@ Now, you're all set to use Elasticsearch with Laravel as if it were native to th
191236

192237
## Getting Started
193238

194-
- [Installation](https://elasticsearch.pdphilip.com/#installation)
195-
- [Configuration](https://elasticsearch.pdphilip.com/#configuration)
239+
- [Installation](https://elasticsearch.pdphilip.com/getting-started)
240+
- [Configuration](https://elasticsearch.pdphilip.com/getting-started#configuration-guide)
196241

197-
## Eloquent
242+
### Eloquent
198243

199-
- [The Base Model](https://elasticsearch.pdphilip.com/the-base-model)
200-
- [Querying Models](https://elasticsearch.pdphilip.com/querying-models)
201-
- [Saving Models](https://elasticsearch.pdphilip.com/saving-models)
202-
- [Deleting Models](https://elasticsearch.pdphilip.com/deleting-models)
203-
- [Ordering and Pagination](https://elasticsearch.pdphilip.com/ordering-and-pagination)
204-
- [Distinct and GroupBy](https://elasticsearch.pdphilip.com/distinct)
205-
- [Aggregations](https://elasticsearch.pdphilip.com/aggregation)
206-
- [Chunking](https://elasticsearch.pdphilip.com/chunking)
207-
- [Nested Queries](https://elasticsearch.pdphilip.com/nested-queries)
208-
- [Elasticsearch Specific Queries](https://elasticsearch.pdphilip.com/es-specific)
209-
- [Full-Text Search](https://elasticsearch.pdphilip.com/full-text-search)
210-
- [Dynamic Indices](https://elasticsearch.pdphilip.com/dynamic-indices)
244+
- [The Base Model](https://elasticsearch.pdphilip.com/eloquent/the-base-model)
245+
- [Saving Models](https://elasticsearch.pdphilip.com/eloquent/saving-models)
246+
- [Deleting Models](https://elasticsearch.pdphilip.com/eloquent/deleting-models)
247+
- [Querying Models](https://elasticsearch.pdphilip.com/eloquent/querying-models)
248+
- [Eloquent Queries](https://elasticsearch.pdphilip.com/eloquent/eloquent-queries)
249+
- [ES Eloquent Queries](https://elasticsearch.pdphilip.com/eloquent/es-queries)
250+
- [Cross Fields Search Queries](https://elasticsearch.pdphilip.com/eloquent/search-queries)
251+
- [Aggregation Queries](https://elasticsearch.pdphilip.com/eloquent/aggregation)
252+
- [Distinct and GroupBy Queries](https://elasticsearch.pdphilip.com/eloquent/distinct)
253+
- [Nested Queries](https://elasticsearch.pdphilip.com/eloquent/nested-queries)
254+
- [Ordering and Pagination](https://elasticsearch.pdphilip.com/eloquent/ordering-and-pagination)
255+
- [Chunking](https://elasticsearch.pdphilip.com/eloquent/chunking)
256+
- [Dynamic Indices](https://elasticsearch.pdphilip.com/eloquent/dynamic-indices)
211257

212-
## Relationships
258+
### Relationships
213259

214-
- [Elasticsearch to Elasticsearch](https://elasticsearch.pdphilip.com/es-es)
215-
- [Elasticsearch to MySQL](https://elasticsearch.pdphilip.com/es-mysql)
260+
- [Elasticsearch to Elasticsearch](https://elasticsearch.pdphilip.com/relationships/es-es)
261+
- [Elasticsearch to SQL](https://elasticsearch.pdphilip.com/relationships/es-sql)
216262

217-
## Schema/Index
263+
### Migrations: Schema/Index
218264

219-
- [Migrations](https://elasticsearch.pdphilip.com/migrations)
220-
- [Re-indexing Process](https://elasticsearch.pdphilip.com/re-indexing)
265+
- [Migrations](https://elasticsearch.pdphilip.com/schema/migrations)
266+
- [Index Blueprint](https://elasticsearch.pdphilip.com/schema/index-blueprint)
221267

222-
## Misc
268+
### Misc
223269

224-
- [Handling Errors](https://elasticsearch.pdphilip.com/handling-errors)
270+
- [Mapping ES to Eloquent](https://elasticsearch.pdphilip.com/notes/elasticsearch-to-eloquent-map)
225271

226-
---
227-
228-
# New in Version 4
229-
230-
(and 3.9.1/3.8.1)
231-
232-
- [Search Highlighting](https://elasticsearch.pdphilip.com/full-text-search#highlighting)
233-
- [whereTimestamp()](https://elasticsearch.pdphilip.com/es-specific#where-timestamp)
234-
- [Raw Aggregation](https://elasticsearch.pdphilip.com/es-specific#raw-aggregation-queries)
235-
- [Updated Error Handling](https://elasticsearch.pdphilip.com/handling-errors)
236-
- [Chunk Upgrade: Point In Time (PIT)](https://elasticsearch.pdphilip.com/chunking#chunking-under-the-hood-pit)
237-
238-
---
272+
## Credits
239273

240-
# New in Version 3
274+
- [David Philip](https://github.com/pdphilip)
275+
- [@use-the-fork](https://github.com/use-the-fork)
241276

242-
### Nested Queries [(see)](https://elasticsearch.pdphilip.com/nested-queries)
243-
244-
- [Nested Object Queries](https://elasticsearch.pdphilip.com/nested-queries#where-nested-object)
245-
- [Order By Nested](https://elasticsearch.pdphilip.com/nested-queries#order-by-nested-field)
246-
- [Filter Nested Values](https://elasticsearch.pdphilip.com/nested-queries#filtering-nested-values): Filters nested values of the parent collection
247-
248-
### New `Where` clauses
249-
250-
- [Phrase Matching](https://elasticsearch.pdphilip.com/es-specific#where-phrase): The enhancement in phrase matching capabilities allows for refined search precision, facilitating the targeting of exact word sequences within textual
251-
fields, thus improving search specificity
252-
and relevance.
253-
- [Exact Matching](https://elasticsearch.pdphilip.com/es-specific#where-exact): Strengthening exact match queries enables more stringent search criteria, ensuring the retrieval of documents that precisely align with specified parameters.
254-
255-
### Sorting Enhancements
256-
257-
- [Ordering with ES features](https://elasticsearch.pdphilip.com/ordering-and-pagination#extending-ordering-for-elasticsearch-features): Includes modes and missing values for sorting fields.
258-
- [Order by Geo Distance](https://elasticsearch.pdphilip.com/ordering-and-pagination#order-by-geo-distance)
259-
260-
### Saving Updates
261-
262-
- [First Or Create](https://elasticsearch.pdphilip.com/saving-models#first-or-create)
263-
- [First Or Create without Refresh](https://elasticsearch.pdphilip.com/saving-models#first-or-create-without-refresh)
264-
265-
### Grouped Queries
266-
267-
- [Grouped Queries](https://elasticsearch.pdphilip.com/querying-models#grouped-queries): Queries can be grouped allowing multiple conditions to be nested within a single query block.
268-
269-
---
277+
## License
270278

271-
### Roadmap
272-
- Add Global modifer on model to add a *, or an index modifer to end of the table. that way you can do global search or add to a sub index.
279+
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

0 commit comments

Comments
 (0)