README

Laravel-OpenSearch

OpenSearch is a distributed, community-driven, Apache 2.0-licensed, 100% open-source search and analytics suite used for a broad set of use cases like real-time application monitoring, log analytics, and website search.

An OpenSearch implementation of Laravel's Eloquent ORM

The Power of OpenSearch with Laravel's Eloquent

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

The Eloquent you already know:

UserLog::where('created_at','>=',Carbon::now()->subDays(30))->get();

UserLog::create([
    'user_id' => '2936adb0-b10d-11ed-8e03-0b234bda3e12',
    'ip' => '62.182.98.146',
    'location' => [40.7185,-74.0025],
    'country_code' => 'US',
    'status' => 1,
]);

UserLog::where('status', 1)->update(['status' => 4]);

UserLog::where('status', 4)->orderByDesc('created_at')->paginate(50);

UserProfile::whereIn('country_code',['US','CA'])
    ->orderByDesc('last_login')->take(10)->get();

UserProfile::where('state','unsubscribed')
    ->where('updated_at','<=',Carbon::now()->subDays(90))->delete();

opensearch with Eloquent:

UserProfile::searchTerm('Laravel')->orSearchTerm('opensearch')->get();

UserProfile::searchPhrasePrefix('loves espressos and t')->highlight()->get();

UserProfile::whereMatch('bio', 'PHP')->get();

UserLog::whereGeoDistance('location', '10km', [40.7185,-74.0025])->get();

UserProfile::whereFuzzy('description', 'qick brwn fx')->get();

Built in Relationships (even to SQL models):

UserLog::where('status', 1)->orderByDesc('created_at')->with('user')->get();

Read the Documentation

Installation

Laravel 10.x, 11.x & 12.x (main):

composer require pdphilip/opensearch

Configuration

1. Set up your .env with the following OpenSearch settings:

OS_HOSTS="http://opensearch:9200"
OS_USERNAME=
OS_PASSWORD=
OS_INDEX_PREFIX=my_app_
# prefix will be added to all indexes created by the package with an underscore
# ex: my_app_user_logs for UserLog.php model
    
# AWS SigV4 Config:
OS_SIG_V4_PROVIDER=
OS_SIG_V4_REGION=
OS_SIG_V4_SERVICE=

# Cert Config:
OS_SSL_CERT=
OS_SSL_CERT_PASSWORD=
OS_SSL_KEY=
OS_SSL_KEY_PASSWORD=

# Optional Settings:
OS_OPT_VERIFY_SSL=true
OS_OPT_RETRIES=
OS_OPT_SNIFF_ON_START=
OS_OPT_PORT_HOST_HEADERS=
OS_OPT_ID_SORTABLE=false
OS_OPT_META_HEADERS=true
OS_OPT_BYPASS_MAP_VALIDATION=false
OS_OPT_DEFAULT_LIMIT=1000

For multiple nodes, pass in as comma-separated:

OS_HOSTS="http://opensearch-node1:9200,http://opensearch-node2:9200,http://opensearch-node3:9200"

1. In config/database.php, add the OpensSearch connection:

'opensearch' => [
    'driver'       => 'opensearch',
    'hosts'        => explode(',', env('OS_HOSTS', 'http://localhost:9200')),
    'basic_auth'   => [
        'username' => env('OS_USERNAME', ''),
        'password' => env('OS_PASSWORD', ''),
    ],
    'sig_v4'       => [
        'provider' => env('OS_SIG_V4_PROVIDER'),
        'region'   => env('OS_SIG_V4_REGION'),
        'service'  => env('OS_SIG_V4_SERVICE'),
    ],
    'ssl'          => [
        'cert'          => env('OS_SSL_CERT', ''),
        'cert_password' => env('OS_SSL_CERT_PASSWORD', ''),
        'key'           => env('OS_SSL_KEY', ''),
        'key_password'  => env('OS_SSL_KEY_PASSWORD', ''),
    ],
    'index_prefix' => env('OS_INDEX_PREFIX', false),
    'options'      => [
        'bypass_map_validation' => env('OS_OPT_BYPASS_MAP_VALIDATION', false),
        'ssl_verification'      => env('OS_OPT_VERIFY_SSL', true),
        'retires'               => env('OS_OPT_RETRIES',null),
        'sniff_on_start'        => env('OS_OPT_SNIFF_ON_START',false),
        'logging'               => env('OS_OPT_LOGGING', false),
        'port_in_host_header'   => env('OS_OPT_PORT_HOST_HEADERS',false),
        'default_limit'         => env('OS_OPT_DEFAULT_LIMIT', 1000),
        'allow_id_sort'         => env('OS_OPT_ID_SORTABLE', false),
    ],
],

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

For Laravel 10 and below:

//config/app.php
'providers' => [
    ...
    ...
    PDPhilip\OpenSearch\OpenSearchServiceProvider::class,
    ...

For Laravel 11:

//bootstrap/providers.php
<?php
return [
    App\Providers\AppServiceProvider::class,
    PDPhilip\OpenSearch\OpenSearchServiceProvider::class,
];

Now, you're all set to use OpenSearch with Laravel as if it were native to the framework.

Documentation Links

Getting Started

• Installation
• Configuration

Eloquent

• The Base Model
• Saving Models
• Deleting Models
• Querying Models
• Eloquent Queries
• OS Eloquent Queries
• Cross Fields Search Queries
• Aggregation Queries
• Distinct and GroupBy Queries
• Nested Queries
• Ordering and Pagination
• Chunking
• Dynamic Indices

Relationships

• OpenSearch to OpenSearch
• OpenSearch to SQL

Migrations: Schema/Index

• Migrations
• Index Blueprint

Misc

• Mapping OS to Eloquent

Credits

• David Philip

License

The MIT License (MIT). Please see License File for more information.