Changelog

Author: pdphilip

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this `laravel-elasticsearch` package will be documented in this file.
 
+## v5.7.0 - 2026-05-24
+
+This release is compatible with Laravel 11, 12 & 13
+
+### Added
+
+- **`whereNestedFieldExists($path)`** ([docs](https://elasticsearch.pdphilip.com/eloquent/nested-queries#where-nested-field-exists)) - explicit, zero-overhead check for "this nested path has at least one document." Emits the idiomatic `nested + exists` form directly, no closure required. Variants: `whereNestedFieldDoesntExist`, `orWhereNestedFieldExists`, `orWhereNestedFieldDoesntExist`.
+- **`whereFieldExists($field)`** ([docs](https://elasticsearch.pdphilip.com/eloquent/eloquent-queries#wherefieldexists)) - properly named alias for the Elasticsearch `exists` query. Variants: `whereFieldDoesntExist`, `orWhereFieldExists`, `orWhereFieldDoesntExist`.
+- **`nestedQuery($column)`** ([docs](https://elasticsearch.pdphilip.com/eloquent/nested-queries#building-the-inner-query-programmatically)) - returns a pre-configured Builder you can build up across conditionals and functions, then pass straight to `whereNestedObject()`. The closure form still works for simple cases; this is the escape hatch for programmatic composition.
+- `whereNestedObject()` now accepts a pre-built Builder (from `nestedQuery()`) in addition to a Closure or raw DSL string. Invalid input now throws `BuilderException` instead of silently being stored.
+
+### Changed
+
+- **Exists queries on nested-mapped fields auto-wrap in `nested`** ([docs](https://elasticsearch.pdphilip.com/eloquent/eloquent-queries#wherenotnull)) - `whereFieldExists('comments.country')`, `whereNotNull('comments.country')`, and `whereNull('comments.country')` now emit the idiomatic `nested { path: comments, query: { exists: ... } }` form when the target field lives under a nested path. Detection only fires for dotted field names - bare-field calls (`whereNotNull('title')`) pay no overhead.
+- **IDE/PHPDoc improvements** - `find`, `first`, `firstOrCreate` now return `static` (not the abstract base `Model`), so subclass property hints resolve correctly. Collection-returning methods (`get`, `rawSearch`, `distinct`, `bulkDistinct`) annotated as `array<int, static>` so `foreach` typing works in PhpStorm. `ElasticCollection` template hygiene tightened (FQN parent in `@extends`, dropped name-colliding `use Model as TModel` alias).
+
+### Deprecated
+
+- **`whereTermExists` family** - replaced by `whereFieldExists`. The `Term` prefix was historical (the underlying ES query isn't term-related) and the old name avoided collision with Laravel's base `whereExists(Closure)`. Old methods still work; will be removed in v6:
+    - `whereTermExists` → `whereFieldExists`
+    - `whereNotTermExists` → `whereFieldDoesntExist`
+    - `orWhereTermExists` → `orWhereFieldExists`
+    - `orWhereNotTermsExists` → `orWhereFieldDoesntExist` (also fixes the typo'd plural "Terms")
+
+**Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.6.1...v5.7.0
+
 ## v5.6.1 - 2026-04-06
 
 > **Future-proofing note:** After GitHub incorrectly shadow-banned my account (since reinstated with no
@@ -13,7 +39,7 @@ This release is compatible with Laravel 11, 12 & 13
 
 ### Fixed
 
-- **Laravel 13.3 compatibility** — `newCollection()` override on base Model to prevent `HasCollection`
+- **Laravel 13.3 compatibility** - `newCollection()` override on base Model to prevent `HasCollection`
   trait from attempting to instantiate the abstract parent class (`Cannot instantiate abstract class`
   error introduced in Laravel 13.3's new `resolveCollectionFromAttribute` grandchild resolution)
 - **QueryException** crash on `Undefined array key "error"` when Elasticsearch returns responses
@@ -41,7 +67,7 @@ This release is compatible with Laravel 11, 12 & 13
 ### Refactored
 
 - Collapsed Laravel version compatibility layer from 12 files (4 dispatchers + 4 v11 traits + 4 v12 traits) into 4 self-contained traits. Version checks now happen inside each method with spread operators for different constructor
-  signatures — no more file-level conditional trait loading. Removed phpstan bootstrap `class_alias` hacks that were needed for the old pattern.
+  signatures - no more file-level conditional trait loading. Removed phpstan bootstrap `class_alias` hacks that were needed for the old pattern.
 
 **Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.5.3...v5.6.0
 
@@ -50,7 +76,7 @@ This release is compatible with Laravel 11, 12 & 13
 ### Fixed
 
 - `distinct()`, `bulkDistinct()`, and `groupBy()` now work on nested fields (e.g., `distinct('tags.key', true)`). Previously these returned empty results because the compiled DSL lacked the required `nested` aggregation wrapper. The package
-  now auto-detects nested mappings and wraps aggregations accordingly — no changes needed in userland code.
+  now auto-detects nested mappings and wraps aggregations accordingly - no changes needed in userland code.
 - When `whereNestedObject()` is combined with `distinct()` on the same nested path, the nested filter is injected inside the aggregation context so that only matching sub-documents are aggregated.
 
 **Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.5.2...v5.5.3
@@ -67,8 +93,8 @@ This release is compatible with Laravel 11, 12 & 13
 
 ### Added
 
-- `Schema::compileMapping()` — compile a Blueprint callback into its resulting ES mapping structure without creating the index. Useful for debugging and previewing what `mappingDefinition()` will produce.
-- `Grammar::compileMapping()` — public access to the Blueprint-to-properties compilation pipeline.
+- `Schema::compileMapping()` - compile a Blueprint callback into its resulting ES mapping structure without creating the index. Useful for debugging and previewing what `mappingDefinition()` will produce.
+- `Grammar::compileMapping()` - public access to the Blueprint-to-properties compilation pipeline.
 
 ### Fixed
 
@@ -86,7 +112,7 @@ This release is compatible with Laravel 10, 11 & 12
 
 #### Automated Re-indexing Command
 
-New `elastic:re-index` command that automates the entire re-indexing process when your field mappings change. Pass a model name and the command handles the rest — creating a temp index, copying data, verifying counts, swapping, and cleaning
+New `elastic:re-index` command that automates the entire re-indexing process when your field mappings change. Pass a model name and the command handles the rest - creating a temp index, copying data, verifying counts, swapping, and cleaning
 up across 9 interactive phases with confirmation prompts between each step. - [Docs](https://elasticsearch.pdphilip.com/schema/artisan-commands/#elasticre-index)
 
 ```bash
@@ -97,7 +123,7 @@ php artisan elastic:re-index "App\Models\ES\UserLog"
 Features include:
 
 - Smart mapping analysis that detects type mismatches and sub-field changes (e.g., adding `hasKeyword: true`)
-- Resume capability — interrupted runs pick up where they left off
+- Resume capability - interrupted runs pick up where they left off
 - Configurable tolerance and retry settings
 - `--force` flag to skip all confirmation prompts
 
@@ -286,7 +312,7 @@ Why: Massive performance gains vs running sequential distinct queries.
 `groupByRanges()` performs a [range aggregation](https://www.elastic.co/docs/reference/aggregations/search-aggregations-bucket-range-aggregation) on the specified
 field. - [Docs](https://elasticsearch.pdphilip.com/eloquent/distinct/#groupby-ranges)
 
-`groupByRanges()->get()`  — return bucketed results - [Docs](https://elasticsearch.pdphilip.com/eloquent/distinct/#groupby-ranges)
+`groupByRanges()->get()`  - return bucketed results - [Docs](https://elasticsearch.pdphilip.com/eloquent/distinct/#groupby-ranges)
 
 `groupByRanges()->agg()` - apply metric aggregations per bucket -[Docs](https://elasticsearch.pdphilip.com/eloquent/distinct/#groupby-ranges-with-aggregations)
 
@@ -295,9 +321,9 @@ field. - [Docs](https://elasticsearch.pdphilip.com/eloquent/distinct/#groupby-ra
 `groupByDateRanges()` performs a [date range aggregation](https://www.elastic.co/docs/reference/aggregations/search-aggregations-bucket-daterange-aggregation) on the specified
 field. - [Docs](https://elasticsearch.pdphilip.com/eloquent/distinct/#groupby-date-ranges)
 
-`groupByDateRanges()->get()` — bucketed date ranges
+`groupByDateRanges()->get()` - bucketed date ranges
 
-`groupByDateRanges()->agg()` — metrics per date bucket
+`groupByDateRanges()->agg()` - metrics per date bucket
 
 #### Model Meta Accessor
 
@@ -334,7 +360,7 @@ This release is compatible with Laravel 10, 11 & 12
 This release introduces Query String Queries, bringing full Elasticsearch `query_string` syntax support directly into your Eloquent-style queries.
 
 - Method: `searchQueryString(query, $fields = null, $options = [])` and related methods (`orSearchQueryString`, `searchNotQueryString`, etc.)
-- Supports all `query_string` features — logical operators, wildcards, fuzziness, ranges, regex, boosting, field scoping, and more
+- Supports all `query_string` features - logical operators, wildcards, fuzziness, ranges, regex, boosting, field scoping, and more
 - Includes a dedicated `QueryStringOptions` class for fluent option configuration or array-based parameters
 - [See Tests](https://github.com/pdphilip/laravel-elasticsearch/blob/main/tests/QueryStringTest.php)
 - [Full documentation](https://elasticsearch.pdphilip.com/eloquent/query-string-queries/)

src/Data/QueryMeta.php

@@ -20,7 +20,7 @@ public function __construct(?MetaDTO $meta = null)
     }
 
     // ----------------------------------------------------------------------
-    // Getters — delegate to MetaDTO
+    // Getters - delegate to MetaDTO
     // ----------------------------------------------------------------------
 
     public function getIndex(): string

src/Eloquent/ElasticCollection.php

@@ -11,7 +11,7 @@
  * @template TKey of array-key
  * @template TModel of \PDPhilip\Elasticsearch\Eloquent\Model
  *
- * @extends \Illuminate\Database\Eloquent\Collection<TKey, TModel>
+ * @extends Collection<TKey, TModel>
  */
 class ElasticCollection extends Collection
 {

src/Eloquent/GeneratesTimeOrderedIds.php

@@ -12,7 +12,7 @@
  * Generates time-ordered, sortable IDs for Elasticsearch models.
  *
  * Use this trait when you need IDs that sort chronologically across
- * multiple processes/workers — ideal for high-volume APIs where
+ * multiple processes/workers - ideal for high-volume APIs where
  * time-sequenced analytics matter.
  *
  * IDs are 20 characters, URL-safe, and sort lexicographically in

src/Query/Concerns/BuildsFieldQueries.php

@@ -8,10 +8,10 @@
  * ES-specific field queries: term, match, phrase, fuzzy, regex, prefix.
  *
  * Each query type provides four variants:
- *   where{Type}()         — AND match
- *   orWhere{Type}()       — OR match
- *   whereNot{Type}()      — AND NOT match
- *   orWhereNot{Type}()    — OR NOT match
+ *   where{Type}()         - AND match
+ *   orWhere{Type}()       - OR match
+ *   whereNot{Type}()      - AND NOT match
+ *   orWhereNot{Type}()    - OR NOT match
  *
  * Aliases:
  *   whereExact*  → whereTerm*
@@ -85,7 +85,7 @@ public function orWhereNotExact($column, $value, $options = []): self
     // https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-query.html
     //
     // Named whereFieldExists (not whereExists) to avoid colliding with
-    // Laravel's base Builder::whereExists(Closure $callback) — the SQL
+    // Laravel's base Builder::whereExists(Closure $callback) - the SQL
     // EXISTS subquery clause, which has entirely different semantics.
     //
     // Works on top-level fields and on nested-mapped fields: the compiler

src/Query/Concerns/BuildsNestedQueries.php

@@ -139,7 +139,7 @@ public function filterNested($column, $query, $options = [])
     public function whereNestedFieldExists(string $path, string $boolean = 'and', bool $not = false): self
     {
         // Stored as 'path' (not 'column') to bypass the where-loop's automatic
-        // parent-field prepending — the path here is the nested path itself,
+        // parent-field prepending - the path here is the nested path itself,
         // not a field inside a nested context.
         $this->wheres[] = [
             'type' => 'NestedFieldExists',

src/Query/Concerns/BuildsSearchQueries.php

@@ -12,15 +12,15 @@
  * Multi-field search queries for Elasticsearch (multi_match + query_string).
  *
  * All convenience methods delegate to search() with different multi_match types:
- *   searchTerm*          — best_fields   (highest score from best-matching field)
- *   searchTermMost*      — most_fields   (combined score from all matching fields)
- *   searchTermCross*     — cross_fields  (treats fields as one combined field)
- *   searchPhrase*        — phrase        (exact phrase match)
- *   searchPhrasePrefix*  — phrase_prefix (phrase + prefix on last term)
- *   searchBoolPrefix*    — bool_prefix   (search-as-you-type)
- *   searchFuzzy*         — best_fields + fuzziness:AUTO
- *   searchFuzzyPrefix*   — bool_prefix  + fuzziness:AUTO
- *   searchQueryString*   — query_string  (Lucene query syntax)
+ *   searchTerm*          - best_fields   (highest score from best-matching field)
+ *   searchTermMost*      - most_fields   (combined score from all matching fields)
+ *   searchTermCross*     - cross_fields  (treats fields as one combined field)
+ *   searchPhrase*        - phrase        (exact phrase match)
+ *   searchPhrasePrefix*  - phrase_prefix (phrase + prefix on last term)
+ *   searchBoolPrefix*    - bool_prefix   (search-as-you-type)
+ *   searchFuzzy*         - best_fields + fuzziness:AUTO
+ *   searchFuzzyPrefix*   - bool_prefix  + fuzziness:AUTO
+ *   searchQueryString*   - query_string  (Lucene query syntax)
  *
  * Each type has four variants: search{Type}, orSearch{Type}, searchNot{Type}, orSearchNot{Type}
  *

src/Query/Grammar/Concerns/FieldUtilities.php

@@ -171,7 +171,7 @@ protected function resolveNestedPaths(Builder $builder): array
                 }
             }
         } catch (\Exception) {
-            // Index may not exist yet — no nested paths to detect
+            // Index may not exist yet - no nested paths to detect
         }
 
         $builder->options()->add($cacheKey, $nestedPaths);

src/Query/ManagesOptions.php

@@ -162,7 +162,7 @@ protected function parseOptions($value, ?string $type = null)
 
                 return tap(new $class, $value)->toArray();
             } catch (Exception $e) {
-                // Callable didn't match expected option signature — return empty options
+                // Callable didn't match expected option signature - return empty options
                 return [];
             }
         }

src/Query/Processor/Processor.php

@@ -67,7 +67,7 @@ public function processAggregations(Builder $query, $result)
         $response = $this->getRawResponse();
         $this->rawAggregations = $response['aggregations'] ?? [];
 
-        // Extract after_key — may be inside a nested agg wrapper
+        // Extract after_key - may be inside a nested agg wrapper
         $groupByAggs = $this->unwrapNestedAggregation($this->rawAggregations, 'group_by');
         if (! empty($groupByAggs['group_by']['after_key'])) {
             $this->query->getMetaTransfer()->set('after_key', $groupByAggs['group_by']['after_key']);