V3 prep

pdphilip · pdphilip · commit 1dc998498156 · 2025-04-12T21:25:27.000+02:00
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1,11 @@
+# Laravel Elasticsearch Package Code Ownership
+# Defines who must review changes to specific parts of the codebase.
+
+# Package metadata and config
+/composer.json @pdphilip
+/LICENSE       @pdphilip
+/.github/      @pdphilip
+/README.md     @pdphilip
+
+# Core source code
+/src/          @pdphilip
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -22,8 +22,8 @@ jobs:
 
     # Docs: https://docs.github.com/en/actions/using-containerized-services
     services:
-      elasticsearch:
-        image: elasticsearch:7.17.3
+      opensearch:
+        image: opensearch:latest
         env:
           discovery.type: single-node
           ES_JAVA_OPTS: '-Xms512m -Xmx512m'
@@ -41,9 +41,9 @@ jobs:
       - name: Checkout 🛎
         uses: actions/checkout@v4
 
-      - name: Verify Elasticsearch connection 🧩
+      - name: Verify Opensearch connection
         run: |
-          curl -X GET "localhost:${{ job.services.elasticsearch.ports['9200'] }}/_cluster/health?pretty=true"
+          curl -X GET "localhost:${{ job.services.opensearch.ports['9200'] }}/_cluster/health?pretty=true"
 
       - name: Setup PHP 🏗
         uses: shivammathur/setup-php@v2
@@ -57,13 +57,13 @@ jobs:
         run: |
           composer install --no-interaction --prefer-dist --optimize-autoloader
 
-      - name: List Installed Dependencies 📦
+      - name: List Installed Dependencies
         run: composer show -D
 
-      - name: Run tests 🧪
+      - name: Run tests
         run: |
           ./vendor/bin/pest  --version
           ./vendor/bin/pest
         env:
           REDIS_PORT: ${{ job.services.redis.ports['6379'] }}
-          ELASTICSEARCH_PORT: ${{ job.services.elasticsearch.ports['9200'] }}
+          OPENSEARCH_PORT: ${{ job.services.opensearch.ports['9200'] }}
diff --git a/.github/workflows/update-changelog.yml b/.github/workflows/update-changelog.yml
@@ -0,0 +1,32 @@
+name: "Update Changelog"
+
+on:
+  release:
+    types: [released]
+
+permissions:
+  contents: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Update Changelog
+        uses: stefanzweifel/changelog-updater-action@v1
+        with:
+          latest-version: ${{ github.event.release.name }}
+          release-notes: ${{ github.event.release.body }}
+
+      - name: Commit updated CHANGELOG
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          branch: main
+          commit_message: Update CHANGELOG
+          file_pattern: CHANGELOG.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this `laravel-opensearch` package will be documented in this file.
diff --git a/README.md b/README.md
@@ -2,64 +2,100 @@
 
 # Laravel-OpenSearch
 
-[![Latest Stable Version](http://img.shields.io/github/release/pdphilip/laravel-opensearch.svg)](https://packagist.org/packages/pdphilip/laravel-opensearch)
+[![Latest Stable Version](http://img.shields.io/github/release/pdphilip/laravel-opensearch.svg)](https://packagist.org/packages/pdphilip/opensearch)
+[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/pdphilip/laravel-opensearch/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/pdphilip/laravel-opensearch/actions/workflows/run-tests.yml?query=branch%3Amain)
+[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/pdphilip/laravel-opensearch/phpstan.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/pdphilip/laravel-opensearch/actions/workflows/phpstan.yml?query=branch%3Amain++)
 [![Total Downloads](http://img.shields.io/packagist/dm/pdphilip/opensearch.svg)](https://packagist.org/packages/pdphilip/opensearch)
 
-
-> **This package has been built off the back of the original [Elasticsearch version](https://github.com/pdphilip/laravel-elasticsearch) of this package**
->
-> **The starting point of this package was forked from `v4.0.1` with over 2 years of development**
-
 [OpenSearch](https://opensearch.net/) 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.
 
-Examples:
+The Eloquent you already know:
 
 ```php
-$logs = UserLog::where('created_at','>=',Carbon::now()->subDays(30))->get();
+UserLog::where('created_at','>=',Carbon::now()->subDays(30))->get();
 ```
 
 ```php
-$updates = UserLog::where('status', 1)->update(['status' => 4]);
+UserLog::create([
+    'user_id' => '2936adb0-b10d-11ed-8e03-0b234bda3e12',
+    'ip' => '62.182.98.146',
+    'location' => [40.7185,-74.0025],
+    'country_code' => 'US',
+    'status' => 1,
+]);
 ```
 
 ```php
-$updates = UserLog::where('status', 1)->paginate(50);
+UserLog::where('status', 1)->update(['status' => 4]);
 ```
 
 ```php
-$profiles = UserProfile::whereIn('country_code',['US','CA'])->orderByDesc('last_login')->take(10)->get();
+UserLog::where('status', 4)->orderByDesc('created_at')->paginate(50);
 ```
 
 ```php
-$deleted = UserProfile::where('state','unsubscribed')->where('updated_at','<=',Carbon::now()->subDays(90))->delete();
+UserProfile::whereIn('country_code',['US','CA'])
+    ->orderByDesc('last_login')->take(10)->get();
 ```
 
 ```php
-$search = UserProfile::phrase('loves espressos')->highlight()->search();
+UserProfile::where('state','unsubscribed')
+    ->where('updated_at','<=',Carbon::now()->subDays(90))->delete();
+```
+
+opensearch with Eloquent:
+
+```php
+UserProfile::searchTerm('Laravel')->orSearchTerm('opensearch')->get();
+```
+
+```php
+UserProfile::searchPhrasePrefix('loves espressos and t')->highlight()->get();
+```
+
+```php
+UserProfile::whereMatch('bio', 'PHP')->get();
+```
+
+```php
+UserLog::whereGeoDistance('location', '10km', [40.7185,-74.0025])->get();
+```
+
+```php
+UserProfile::whereFuzzy('description', 'qick brwn fx')->get();
+```
+
+Built in Relationships (even to SQL models):
+
+```php
+UserLog::where('status', 1)->orderByDesc('created_at')->with('user')->get();
 ```
 
----
-> ### Read the [Documentation](https://opensearch.pdphilip.com/)
 ---
 
+# Read the [Documentation](https://opensearch.pdphilip.com/)
+
 ## Installation
 
-**Laravel 10 & 11 (main):**
+**Laravel 10.x, 11.x & 12.x (main):**
 
 ```bash
 composer require pdphilip/opensearch
 ```
 
-| Laravel Version | Command                                    | Maintained |
-|-----------------|--------------------------------------------|------------|
-| Laravel 10 & 11 | `composer require pdphilip/opensearch:~2 ` | ✅          |
-| Laravel 8 & 9   | `composer require pdphilip/opensearch:~1`  | ✅          |
+| Laravel Version    | Command                                    | Maintained |
+|--------------------|--------------------------------------------|------------|
+| Laravel 10/11/12   | `composer require pdphilip/opensearch:~3 ` | ✅          |
+| Laravel 10/11 (v2) | `composer require pdphilip/opensearch:~2 ` | ❌ EOL      |
+| Laravel 8 & 9      | `composer require pdphilip/opensearch:~1`  | ❌ EOL      |
 
 ## Configuration
 
@@ -69,22 +105,30 @@ composer require pdphilip/opensearch
 OS_HOSTS="http://opensearch:9200"
 OS_USERNAME=
 OS_PASSWORD=
-OS_INDEX_PREFIX=my_app
-
+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_ERROR_INDEX=
+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:
@@ -93,7 +137,7 @@ For multiple nodes, pass in as comma-separated:
 OS_HOSTS="http://opensearch-node1:9200,http://opensearch-node2:9200,http://opensearch-node3:9200"
 ```
 
-2. In `config/database.php`, add the opensearch connection:
+2. In `config/database.php`, add the OpensSearch connection:
 
 ```php
 'opensearch' => [
@@ -116,12 +160,15 @@ OS_HOSTS="http://opensearch-node1:9200,http://opensearch-node2:9200,http://opens
     ],
     'index_prefix' => env('OS_INDEX_PREFIX', false),
     'options'      => [
-        'ssl_verification'    => env('OS_OPT_VERIFY_SSL', true),
-        'retires'             => env('OS_OPT_RETRIES'),
-        'sniff_on_start'      => env('OS_OPT_SNIFF_ON_START'),
-        'port_in_host_header' => env('OS_OPT_PORT_HOST_HEADERS'),
+        '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),
     ],
-    'error_log_index' => env('OS_ERROR_INDEX', false),
 ],
 ```
 
@@ -156,34 +203,45 @@ Now, you're all set to use OpenSearch with Laravel as if it were native to the f
 
 # Documentation Links
 
-## Getting Started
+### Getting Started
 
-- [Installation](https://opensearch.pdphilip.com/#installation)
-- [Configuration](https://opensearch.pdphilip.com/#configuration)
+- [Installation](https://opensearch.pdphilip.com/getting-started)
+- [Configuration](https://opensearch.pdphilip.com/getting-started#configuration-guide)
 
-## Eloquent
+### Eloquent
 
-- [The Base Model](https://opensearch.pdphilip.com/the-base-model)
-- [Querying Models](https://opensearch.pdphilip.com/querying-models)
-- [Saving Models](https://opensearch.pdphilip.com/saving-models)
-- [Deleting Models](https://opensearch.pdphilip.com/deleting-models)
-- [Ordering and Pagination](https://opensearch.pdphilip.com/ordering-and-pagination)
-- [Distinct and GroupBy](https://opensearch.pdphilip.com/distinct)
-- [Aggregations](https://opensearch.pdphilip.com/aggregation)
-- [Chunking](https://opensearch.pdphilip.com/chunking)
-- [Nested Queries](https://opensearch.pdphilip.com/nested-queries)
-- [OpenSearch Specific Queries](https://opensearch.pdphilip.com/os-specific)
-- [Full-Text Search](https://opensearch.pdphilip.com/full-text-search)
-- [Dynamic Indices](https://opensearch.pdphilip.com/dynamic-indices)
+- [The Base Model](https://opensearch.pdphilip.com/eloquent/the-base-model)
+- [Saving Models](https://opensearch.pdphilip.com/eloquent/saving-models)
+- [Deleting Models](https://opensearch.pdphilip.com/eloquent/deleting-models)
+- [Querying Models](https://opensearch.pdphilip.com/eloquent/querying-models)
+- [Eloquent Queries](https://opensearch.pdphilip.com/eloquent/eloquent-queries)
+- [OS Eloquent Queries](https://opensearch.pdphilip.com/eloquent/os-queries)
+- [Cross Fields Search Queries](https://opensearch.pdphilip.com/eloquent/search-queries)
+- [Aggregation Queries](https://opensearch.pdphilip.com/eloquent/aggregation)
+- [Distinct and GroupBy Queries](https://opensearch.pdphilip.com/eloquent/distinct)
+- [Nested Queries](https://opensearch.pdphilip.com/eloquent/nested-queries)
+- [Ordering and Pagination](https://opensearch.pdphilip.com/eloquent/ordering-and-pagination)
+- [Chunking](https://opensearch.pdphilip.com/eloquent/chunking)
+- [Dynamic Indices](https://opensearch.pdphilip.com/eloquent/dynamic-indices)
 
-## Relationships
+### Relationships
 
-- [OpenSearch to OpenSearch](https://opensearch.pdphilip.com/os-os)
-- [OpenSearch to MySQL](https://opensearch.pdphilip.com/os-mysql)
+- [OpenSearch to OpenSearch](https://opensearch.pdphilip.com/relationships/os-os)
+- [OpenSearch to SQL](https://opensearch.pdphilip.com/relationships/os-sql)
 
-## Schema/Index
+### Migrations: Schema/Index
 
-- [Migrations](https://opensearch.pdphilip.com/migrations)
-- [Re-indexing Process](https://opensearch.pdphilip.com/re-indexing)
+- [Migrations](https://opensearch.pdphilip.com/schema/migrations)
+- [Index Blueprint](https://opensearch.pdphilip.com/schema/index-blueprint)
 
----
+### Misc
+
+- [Mapping OS to Eloquent](https://opensearch.pdphilip.com/notes/opensearch-to-eloquent-map)
+
+## Credits
+
+- [David Philip](https://github.com/pdphilip)
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
diff --git a/src/Eloquent/Docs/ModelDocs.php b/src/Eloquent/Docs/ModelDocs.php
@@ -8,6 +8,7 @@
 use Illuminate\Pagination\Cursor;
 use PDPhilip\OpenSearch\Eloquent\Builder;
 use PDPhilip\OpenSearch\Eloquent\Model;
+use PDPhilip\OpenSearch\Eloquent\OpenCollection;
 use PDPhilip\OpenSearch\Pagination\SearchAfterPaginator;
 
 /**
@@ -178,14 +179,14 @@
  * @method static Model firstOrCreate($attributes, $values = [])
  *-----------------------------------
  * @method static array getModels($columns = ['*'])
- * @method static ElasticCollection get($columns = ['*'])
- * @method static ElasticCollection insert($values, $returnData = null)
+ * @method static OpenCollection get($columns = ['*'])
+ * @method static OpenCollection insert($values, $returnData = null)
  *-----------------------------------
  * @method static array toDsl($columns = ['*'])
  * @method static array toSql($columns = ['*'])
  *-----------------------------------
  * @method static mixed rawDsl($bodyParams)
- * @method static ElasticCollection rawSearch($bodyParams)
+ * @method static OpenCollection rawSearch($bodyParams)
  * @method static array rawAggregation($bodyParams)
  *-----------------------------------
  * @method static LengthAwarePaginator paginate($perPage = 15, $columns = ['*'], $pageName = 'page', $page = null,  $total = null)
@@ -194,7 +195,7 @@
  * @method static bool chunk($count, $callback)
  * @method static bool chunkById($count, $callback, $column = '_id', $alias = null)
  *                                                                                  -----------------------------------
- * @method static ElasticCollection distinct($columns = [], $includeCount = false)
+ * @method static OpenCollection distinct($columns = [], $includeCount = false)
  *===========================================
  * Aggregators Methods
  *===========================================
@@ -204,14 +205,12 @@
  * @method static int|array avg($columns)
  * @method static mixed agg(array $functions, $column)
  *-----------------------------------
- * @method static mixed boxplot($columns, $options = [])
  * @method static mixed cardinality($columns, $options = [])
  * @method static mixed extendedStats($columns, $options = [])
  * @method static mixed matrix($columns, $options = [])
  * @method static mixed medianAbsoluteDeviation($columns, $options = [])
  * @method static mixed percentiles($columns, $options = [])
  * @method static mixed stats($columns, $options = [])
- * @method static mixed stringStats( $columns, $options = [])
  *-----------------------------------
  * @method static array getAggregationResults()
  * @method static array getRawAggregationResults()

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Changelog`
	`2`	`+`
	`3`	+All notable changes to this `laravel-opensearch` package will be documented in this file.