- Added unit tests

- Added code documentation

Author: ginkelsoft-development

.gitignore

@@ -0,0 +1,47 @@
+# ------------------------------------------------------------
+# Laravel Package .gitignore
+# ------------------------------------------------------------
+
+# Composer dependencies
+/vendor/
+composer.lock
+
+# Node dependencies
+/node_modules/
+npm-debug.log
+yarn-error.log
+pnpm-debug.log
+
+# IDE & OS files
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Environment & local config
+.env
+.env.*
+.phpunit.result.cache
+
+# Build / cache / temporary
+/storage/
+bootstrap/cache/
+coverage/
+*.cache
+*.log
+*.tmp
+
+# Testbench / PHPUnit artifacts
+.phpunit.cache/
+.phpunit.result.cache
+tests/_output/
+tests/_support/_generated/
+
+# Package build output
+/build/
+dist/
+*.zip
+
+# Ignore generated stubs or local test DBs
+database/*.sqlite
+*.sql

composer.json

@@ -23,5 +23,11 @@
   "require-dev": {
     "orchestra/testbench": "^9.0",
     "phpunit/phpunit": "^10.5|^11.0"
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Ginkelsoft\\EncryptedSearch\\Tests\\": "tests/",
+      "Tests\\": "tests/"
+    }
   }
 }

database/migrations/create_encrypted_search_index_table.php

@@ -4,23 +4,72 @@
 use Illuminate\Database\Schema\Blueprint;
 use Illuminate\Support\Facades\Schema;
 
-return new class extends Migration {
+/**
+ * CreateEncryptedSearchIndexTable
+ *
+ * This migration defines the `encrypted_search_index` table, which stores
+ * normalized and hashed tokens to enable secure searching over encrypted data.
+ *
+ * Each record in this table represents a single searchable token for a given
+ * model instance and field. For example, if a "Client" model has an encrypted
+ * `last_name`, its normalized and tokenized forms (exact or prefix) will be
+ * stored here. These tokens can be matched without revealing the original value.
+ *
+ * The combination of `model_type`, `model_id`, `field`, and `type` uniquely
+ * identifies all searchable tokens for a specific model field.
+ *
+ * Indexing strategy:
+ * - `esi_lookup` provides efficient token-based searches.
+ * - `esi_row` accelerates lookup and cleanup operations per model instance.
+ *
+ * Typical usage:
+ * - Generated automatically by the HasEncryptedSearchIndex trait.
+ * - Used for both exact and prefix token searches.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * Creates the `encrypted_search_index` table with tokenized fields for
+     * secure search functionality. Tokens are generated as deterministic
+     * hashes (e.g., SHA-256) and are not reversible, ensuring no sensitive
+     * data is exposed while maintaining fast lookups.
+     */
     public function up(): void
     {
         Schema::create('encrypted_search_index', function (Blueprint $table) {
             $table->id();
-            $table->string('model_type');         // FQCN
+
+            // The fully qualified model class name (e.g. App\Models\Client)
+            $table->string('model_type');
+
+            // The primary key of the model this token belongs to
             $table->unsignedBigInteger('model_id');
-            $table->string('field');              // bv. 'last_names'
-            $table->string('type', 16);           // 'exact' | 'prefix'
-            $table->string('token', 80);          // sha256 hex (64) of korter
+
+            // The model field (e.g. "last_names") from which this token was derived
+            $table->string('field');
+
+            // Token type: 'exact' or 'prefix'
+            $table->string('type', 16);
+
+            // The actual hashed token (e.g. SHA-256 or truncated prefix token)
+            $table->string('token', 80);
+
+            // Record timestamps for auditing and debugging
             $table->timestamps();
 
+            // Composite indexes for optimized lookups
             $table->index(['model_type', 'field', 'type', 'token'], 'esi_lookup');
             $table->index(['model_type', 'model_id'], 'esi_row');
         });
     }
 
+    /**
+     * Reverse the migrations.
+     *
+     * Drops the `encrypted_search_index` table if it exists.
+     */
     public function down(): void
     {
         Schema::dropIfExists('encrypted_search_index');

phpunit.xml.dist

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+        bootstrap="vendor/autoload.php"
+        colors="true"
+        testdox="true"
+        verbose="true"
+>
+    <testsuites>
+        <testsuite name="Package Test Suite">
+            <directory suffix="Test.php">./tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <php>
+        <env name="APP_KEY" value="base64:8vXh4sV6JhZ8pUy8WZ4v7T+6W3lBd6pE7j28x7yT3Z8="/>
+        <env name="SEARCH_PEPPER" value="test-pepper-secret"/>
+        <env name="DB_CONNECTION" value="sqlite"/>
+        <env name="DB_DATABASE" value=":memory:"/>
+        <env name="APP_ENV" value="testing"/>
+    </php>
+
+    <coverage processUncoveredFiles="true">
+        <include>
+            <directory suffix=".php">./src</directory>
+        </include>
+    </coverage>
+</phpunit>

src/Console/RebuildIndex.php

@@ -6,11 +6,63 @@
 use Illuminate\Database\Eloquent\Model;
 use Ginkelsoft\EncryptedSearch\Models\SearchIndex;
 
+/**
+ * Class RebuildIndex
+ *
+ * This Artisan command rebuilds the encrypted search index for a given Eloquent model.
+ * It is designed for maintenance operations where the search index may be outdated,
+ * corrupted, or needs regeneration after schema or normalization changes.
+ *
+ * The command iterates over all records of the specified model and regenerates
+ * both "exact" and "prefix" tokens as defined by the model’s
+ * `HasEncryptedSearchIndex` trait configuration.
+ *
+ * Usage example:
+ *   php artisan encryption:index-rebuild "App\Models\Client"
+ *
+ * Options:
+ *   --chunk=100   Number of records processed per batch (default: 100)
+ *
+ * Implementation details:
+ * - Before rebuilding, all existing search index entries for the given model
+ *   are removed.
+ * - Records are then reprocessed in chunks to prevent memory exhaustion.
+ * - For each model instance, `updateSearchIndex()` is called to regenerate
+ *   the normalized token rows.
+ *
+ * This ensures a clean and consistent index aligned with the current model data.
+ */
 class RebuildIndex extends Command
 {
+    /**
+     * The name and signature of the console command.
+     *
+     * {model}  The fully qualified class name (FQCN) of the Eloquent model.
+     * {--chunk=100}  The number of model records to process per batch.
+     *
+     * @var string
+     */
     protected $signature = 'encryption:index-rebuild {model : FQCN of the Eloquent model} {--chunk=100}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
     protected $description = 'Rebuild encrypted search index for a given model.';
 
+    /**
+     * Execute the console command.
+     *
+     * This method performs the following steps:
+     *  1. Validates the provided model class.
+     *  2. Deletes all existing search index entries for that model.
+     *  3. Iterates through all model records in configurable chunks.
+     *  4. Calls `updateSearchIndex()` for each record to regenerate tokens.
+     *  5. Displays progress and a final summary of processed records.
+     *
+     * @return int Command exit code (0 on success, 1 on failure).
+     */
     public function handle(): int
     {
         /** @var class-string<Model> $class */
@@ -23,20 +75,23 @@ public function handle(): int
 
         $chunk = (int) $this->option('chunk');
 
-        // Drop alle tokens voor dit model
+        // Remove all existing search tokens for this model
         SearchIndex::where('model_type', $class)->delete();
 
         /** @var \Illuminate\Database\Eloquent\Builder $q */
         $q = $class::query();
 
         $count = 0;
+
+        // Process model data in chunks to minimize memory usage
         $q->chunk($chunk, function ($rows) use (&$count, $class) {
             foreach ($rows as $model) {
                 if (method_exists($class, 'updateSearchIndex')) {
                     $class::updateSearchIndex($model);
                 }
                 $count++;
             }
+            // Write a dot to indicate progress
             $this->output->write('.');
         });
 

src/EncryptedSearchServiceProvider.php

@@ -4,27 +4,76 @@
 
 use Illuminate\Support\ServiceProvider;
 
+/**
+ * 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.
+ *
+ * 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
+ */
 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`.
+     *
+     * @return void
+     */
     public function register(): void
     {
-        $this->mergeConfigFrom(__DIR__.'/../config/encrypted-search.php', 'encrypted-search');
+        $this->mergeConfigFrom(
+            __DIR__ . '/../config/encrypted-search.php',
+            'encrypted-search'
+        );
     }
 
+    /**
+     * 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.
+     *
+     * @return void
+     */
     public function boot(): void
     {
-        // Publish config & migration
+        // Publish configuration file
         $this->publishes([
-            __DIR__.'/../config/encrypted-search.php' => config_path('encrypted-search.php'),
+            __DIR__ . '/../config/encrypted-search.php' => config_path('encrypted-search.php'),
         ], 'config');
 
+        // Publish migration with timestamped filename
         $timestamp = date('Y_m_d_His');
         $this->publishes([
-            __DIR__."/../database/migrations/create_encrypted_search_index_table.php"
+            __DIR__ . '/../database/migrations/create_encrypted_search_index_table.php'
             => database_path("migrations/{$timestamp}_create_encrypted_search_index_table.php"),
         ], 'migrations');
 
-        // Commands
+        // Register CLI commands only in console context
         if ($this->app->runningInConsole()) {
             $this->commands([
                 Console\RebuildIndex::class,

src/Models/SearchIndex.php

@@ -4,11 +4,50 @@
 
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * Class SearchIndex
+ *
+ * Represents a single tokenized entry in the encrypted search index.
+ *
+ * Each record in this table corresponds to one searchable token derived from
+ * a field of an Eloquent model that uses the `HasEncryptedSearchIndex` trait.
+ * These tokens enable efficient searching over encrypted or normalized fields
+ * without exposing the original plaintext data.
+ *
+ * Structure overview:
+ * - model_type: Fully Qualified Class Name (FQCN) of the related Eloquent model.
+ * - model_id:   Primary key of the model record.
+ * - field:      Name of the model field from which the token was derived.
+ * - type:       Type of token — "exact" for full-word matches, "prefix" for prefix matches.
+ * - token:      The deterministic, non-reversible hash (e.g. SHA-256) used for lookups.
+ *
+ * Typical usage:
+ * - Automatically maintained by the HasEncryptedSearchIndex trait.
+ * - Used internally to resolve `encryptedExact()` and `encryptedPrefix()` scopes.
+ *
+ * Security notes:
+ * - Tokens are irreversible and contain no plaintext information.
+ * - The table can be safely indexed and queried without leaking sensitive data.
+ */
 class SearchIndex extends Model
 {
+    /**
+     * The database table associated with the model.
+     *
+     * @var string
+     */
     protected $table = 'encrypted_search_index';
 
+    /**
+     * The attributes that are mass assignable.
+     *
+     * @var string[]
+     */
     protected $fillable = [
-        'model_type', 'model_id', 'field', 'type', 'token',
+        'model_type',
+        'model_id',
+        'field',
+        'type',
+        'token',
     ];
 }