Merge pull request #9 from ginkelsoft-development/develop

dev into main

Author: ginkelsoft-development

.env.example

@@ -1 +1,3 @@
 SEARCH_PEPPER=your-long-random-string-here
+ENCRYPTED_SEARCH_DRIVER=elasticsearch
+ELASTICSEARCH_HOSTS=https://search.example.com

README.md

@@ -173,13 +173,13 @@ The detached index structure scales linearly and supports millions of records ef
 
 ## Framework Compatibility
 
-| Laravel Version | PHP Version(s) Supported |
-| --------------- | ------------------------ |
-| 8.x             | 8.0 – 8.1                |
-| 9.x             | 8.1 – 8.2                |
-| 10.x            | 8.1 – 8.3                |
-| 11.x            | 8.2 – 8.3                |
-| 12.x            | 8.3+                     |
+| Laravel Version | Supported PHP Versions |
+|-----------------|------------------------|
+| **8.x**         | 8.0 – 8.1              |
+| **9.x**         | 8.1 – 8.2              |
+| **10.x**        | 8.1 – 8.3              |
+| **11.x**        | 8.2 – 8.3              |
+| **12.x**        | 8.3 and higher         |
 
 The package is continuously tested across all supported combinations using GitHub Actions.
 

src/Contracts/SearchDriver.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Ginkelsoft\EncryptedSearch\Contracts;
+
+use Illuminate\Database\Eloquent\Model;
+
+interface SearchDriver
+{
+    public function index(Model $model): void;
+    public function delete(Model $model): void;
+    public function search(string $field, string $term, string $mode = 'exact'): array;
+}

src/EncryptedSearchServiceProvider.php

@@ -3,44 +3,38 @@
 namespace Ginkelsoft\EncryptedSearch;
 
 use Illuminate\Support\Facades\Event;
-use Ginkelsoft\EncryptedSearch\Observers\SearchIndexObserver;
 use Illuminate\Support\ServiceProvider;
+use Ginkelsoft\EncryptedSearch\Observers\SearchIndexObserver;
 
 /**
  * Class EncryptedSearchServiceProvider
  *
  * Registers and bootstraps the Laravel Encrypted Search Index package.
  *
- * This service provider integrates the package into a Laravel application by:
- *  - Registering configuration (`config/encrypted-search.php`)
- *  - Publishing database migrations for the `encrypted_search_index` table
- *  - Registering console commands (e.g., index rebuilding)
- *
- * The provider ensures that the encrypted search system is fully
- * self-contained and can be seamlessly installed into any Laravel project.
+ * Responsibilities:
+ * - Merge and publish configuration.
+ * - Publish database migration for the `encrypted_search_index` table.
+ * - Register console commands for index rebuilding.
+ * - Attach a global observer that synchronizes encrypted search indexes
+ *   with Eloquent model lifecycle events.
  *
  * Typical installation:
- * ```bash
+ *
  * composer require ginkelsoft/laravel-encrypted-search-index
  * php artisan vendor:publish --tag=config
  * php artisan vendor:publish --tag=migrations
  * php artisan migrate
- * ```
- *
- * After registration, Eloquent models can use the
- * `HasEncryptedSearchIndex` trait to automatically build searchable,
- * privacy-preserving index entries.
  *
- * @see \Ginkelsoft\EncryptedSearch\Traits\HasEncryptedSearchIndex
- * @see \Ginkelsoft\EncryptedSearch\Console\RebuildIndex
+ * After installation, any model using the
+ * {@see \Ginkelsoft\EncryptedSearch\Traits\HasEncryptedSearchIndex}
+ * trait will automatically maintain a privacy-preserving search index.
  */
 class EncryptedSearchServiceProvider extends ServiceProvider
 {
     /**
      * Register bindings and configuration.
      *
-     * This merges the package configuration into the application’s
-     * global config namespace under the key `encrypted-search`.
+     * Merges the package configuration into the application's config repository.
      *
      * @return void
      */
@@ -53,36 +47,32 @@ public function register(): void
     }
 
     /**
-     * Bootstrap package resources (config, migrations, and commands).
-     *
-     * This method is executed after all other service providers have
-     * been registered and is responsible for publishing configuration,
-     * registering migrations, and exposing console commands.
+     * Bootstrap the package resources, commands, and event listeners.
      *
      * @return void
      */
     public function boot(): void
     {
-        // Publish configuration file
+        // Publish configuration
         $this->publishes([
             __DIR__ . '/../config/encrypted-search.php' => config_path('encrypted-search.php'),
         ], 'config');
 
-        // Publish migration with timestamped filename
+        // Publish migration file
         $timestamp = date('Y_m_d_His');
         $this->publishes([
             __DIR__ . '/../database/migrations/create_encrypted_search_index_table.php'
             => database_path("migrations/{$timestamp}_create_encrypted_search_index_table.php"),
         ], 'migrations');
 
-        // Register CLI commands only in console context
+        // Register Artisan commands
         if ($this->app->runningInConsole()) {
             $this->commands([
                 Console\RebuildIndex::class,
             ]);
         }
 
-        // 🔹 Register the observer for all Eloquent events
+        // Listen for all Eloquent model events and route them through the observer
         Event::listen('eloquent.*: *', SearchIndexObserver::class);
     }
 }

src/Traits/HasEncryptedSearchIndex.php

@@ -12,16 +12,14 @@
 /**
  * Trait HasEncryptedSearchIndex
  *
- * Provides automatic encrypted search indexing for Eloquent models.
+ * Adds encrypted search indexing capabilities to Eloquent models.
  *
- * When attached to a model, this trait builds and maintains a companion index
- * table (`encrypted_search_index`) that stores deterministic, non-reversible
- * search tokens derived from model attributes.
+ * When applied, the model automatically generates deterministic, non-reversible
+ * search tokens for configured fields and stores them in the
+ * `encrypted_search_index` table. These tokens support privacy-preserving
+ * search queries while keeping plaintext data out of the database.
  *
- * These tokens enable privacy-preserving search queries (exact or prefix-based)
- * without revealing plaintext values in the database.
- *
- * Example usage:
+ * Example:
  *
  * class Client extends Model {
  *     use HasEncryptedSearchIndex;
@@ -31,47 +29,38 @@
  *         'last_names'  => ['exact' => true, 'prefix' => true],
  *     ];
  * }
- *
- * On each save or delete:
- * - Tokens are (re)generated and stored in `encrypted_search_index`.
- * - Old entries for the record are automatically replaced or removed.
- *
- * Search queries:
- *
- * Client::encryptedExact('last_names', 'vermeer')->get();
- * Client::encryptedPrefix('first_names', 'wie')->get();
  */
 trait HasEncryptedSearchIndex
 {
     /**
-     * Boot logic for the trait.
+     * Boot logic for this trait.
      *
-     * Automatically updates or removes encrypted search tokens whenever
-     * a model instance is saved, updated, deleted, or restored.
+     * Automatically rebuilds or removes search index entries on
+     * create, update, save, delete, restore, and force-delete events.
      *
      * @return void
      */
     public static function bootHasEncryptedSearchIndex(): void
     {
-        // Rebuild index when model is created, updated or saved
+        // Rebuild index on save-related events
         foreach (['created', 'updated', 'saved'] as $event) {
             static::$event(function (Model $model) {
                 $model->updateSearchIndex();
             });
         }
 
-        // Always remove tokens when model is deleted
+        // Remove index entries when deleted
         static::deleted(fn(Model $m) => $m->removeSearchIndex());
 
-        // Register forceDeleted/restored events only if the model uses SoftDeletes
+        // Register SoftDelete-specific hooks only if supported
         if (in_array(SoftDeletes::class, class_uses_recursive(static::class), true)) {
             static::forceDeleted(fn(Model $m) => $m->removeSearchIndex());
             static::restored(fn(Model $m) => $m->updateSearchIndex());
         }
     }
 
     /**
-     * Create or refresh all search index entries for this model instance.
+     * Create or refresh all encrypted search entries for this model instance.
      *
      * @return void
      */
@@ -86,7 +75,7 @@ public function updateSearchIndex(): void
         $pepper = (string) config('encrypted-search.search_pepper', '');
         $max    = (int) config('encrypted-search.max_prefix_depth', 6);
 
-        // Remove existing entries
+        // Remove existing entries for this model
         SearchIndex::where('model_type', static::class)
             ->where('model_id', $this->getKey())
             ->delete();
@@ -99,45 +88,47 @@ public function updateSearchIndex(): void
                 continue;
             }
 
-            $norm = Normalizer::normalize($raw);
-            if (! $norm) {
+            $normalized = Normalizer::normalize($raw);
+            if (! $normalized) {
                 continue;
             }
 
+            // Exact matches
             if (! empty($modes['exact'])) {
                 $rows[] = [
                     'model_type' => static::class,
                     'model_id'   => $this->getKey(),
                     'field'      => $field,
                     'type'       => 'exact',
-                    'token'      => Tokens::exact($norm, $pepper),
+                    'token'      => Tokens::exact($normalized, $pepper),
                     'created_at' => now(),
                     'updated_at' => now(),
                 ];
             }
 
+            // Prefix matches
             if (! empty($modes['prefix'])) {
-                foreach (Tokens::prefixes($norm, $max, $pepper) as $t) {
+                foreach (Tokens::prefixes($normalized, $max, $pepper) as $token) {
                     $rows[] = [
                         'model_type' => static::class,
                         'model_id'   => $this->getKey(),
                         'field'      => $field,
                         'type'       => 'prefix',
-                        'token'      => $t,
+                        'token'      => $token,
                         'created_at' => now(),
                         'updated_at' => now(),
                     ];
                 }
             }
         }
 
-        if ($rows) {
+        if (! empty($rows)) {
             SearchIndex::insert($rows);
         }
     }
 
     /**
-     * Remove all index entries for this model instance.
+     * Delete all encrypted search entries related to this model instance.
      *
      * @return void
      */
@@ -149,26 +140,23 @@ public function removeSearchIndex(): void
     }
 
     /**
-     * Query scope: find models by exact match on an indexed field.
-     *
-     * Example:
-     * Client::encryptedExact('last_names', 'vermeer')->get();
+     * Scope: query models by exact encrypted token match.
      *
-     * @param  \Illuminate\Database\Eloquent\Builder  $query
-     * @param  string  $field
-     * @param  string  $term
-     * @return \Illuminate\Database\Eloquent\Builder
+     * @param Builder $query
+     * @param string $field
+     * @param string $term
+     * @return Builder
      */
     public function scopeEncryptedExact(Builder $query, string $field, string $term): Builder
     {
         $pepper = (string) config('encrypted-search.search_pepper', '');
-        $norm   = Normalizer::normalize($term);
+        $normalized = Normalizer::normalize($term);
 
-        if (! $norm) {
+        if (! $normalized) {
             return $query->whereRaw('1=0');
         }
 
-        $token = Tokens::exact($norm, $pepper);
+        $token = Tokens::exact($normalized, $pepper);
 
         return $query->whereIn($this->getQualifiedKeyName(), function ($sub) use ($field, $token) {
             $sub->select('model_id')
@@ -181,26 +169,27 @@ public function scopeEncryptedExact(Builder $query, string $field, string $term)
     }
 
     /**
-     * Query scope: find models by prefix match on an indexed field.
-     *
-     * Example:
-     * Client::encryptedPrefix('first_names', 'wi')->get();
+     * Scope: query models by prefix-based encrypted token match.
      *
-     * @param  \Illuminate\Database\Eloquent\Builder  $query
-     * @param  string  $field
-     * @param  string  $term
-     * @return \Illuminate\Database\Eloquent\Builder
+     * @param Builder $query
+     * @param string $field
+     * @param string $term
+     * @return Builder
      */
     public function scopeEncryptedPrefix(Builder $query, string $field, string $term): Builder
     {
         $pepper = (string) config('encrypted-search.search_pepper', '');
-        $norm   = Normalizer::normalize($term);
+        $normalized = Normalizer::normalize($term);
 
-        if (! $norm) {
+        if (! $normalized) {
             return $query->whereRaw('1=0');
         }
 
-        $tokens = Tokens::prefixes($norm, (int) config('encrypted-search.max_prefix_depth', 6), $pepper);
+        $tokens = Tokens::prefixes(
+            $normalized,
+            (int) config('encrypted-search.max_prefix_depth', 6),
+            $pepper
+        );
 
         return $query->whereIn($this->getQualifiedKeyName(), function ($sub) use ($field, $tokens) {
             $sub->select('model_id')
@@ -213,9 +202,9 @@ public function scopeEncryptedPrefix(Builder $query, string $field, string $term
     }
 
     /**
-     * Resolve the encrypted search configuration for this model.
+     * Retrieve the encrypted search field configuration.
      *
-     * This allows models to define searchable fields either via a
+     * Models may define configuration either via a
      * `getEncryptedSearchFields()` method or a `$encryptedSearch` property.
      *
      * @return array<string, array<string,bool>>
@@ -226,6 +215,8 @@ protected function getEncryptedSearchConfiguration(): array
             return $this->getEncryptedSearchFields();
         }
 
-        return property_exists($this, 'encryptedSearch') ? $this->encryptedSearch : [];
+        return property_exists($this, 'encryptedSearch')
+            ? $this->encryptedSearch
+            : [];
     }
 }