docs: expand README with auto-indexing, attributes, and Elasticsearch guidance

- Added documentation for automatic indexing of encrypted casts
- Added section describing #[EncryptedSearch] attribute usage
- Clarified configuration with new 'auto_index_encrypted_casts' option
- Added note about Elasticsearch requirement and driver transparency
- Updated "Rebuilding" section title and behavior description
- Introduced Troubleshooting section for common Elasticsearch issues
- Cleaned up badges in header

Author: ginkelsoft-development

README.md

@@ -4,8 +4,9 @@
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/ginkelsoft/laravel-encrypted-search-index.svg?style=flat-square)](https://packagist.org/packages/ginkelsoft/laravel-encrypted-search-index)
 [![Total Downloads](https://img.shields.io/packagist/dt/ginkelsoft/laravel-encrypted-search-index.svg?style=flat-square)](https://packagist.org/packages/ginkelsoft/laravel-encrypted-search-index)
 [![License](https://img.shields.io/github/license/ginkelsoft-development/laravel-encrypted-search-index.svg?style=flat-square)](LICENSE.md)
-[![Laravel](https://img.shields.io/badge/Laravel-8--12-brightgreen?style=flat-square\&logo=laravel)](https://laravel.com)
-[![PHP](https://img.shields.io/badge/PHP-8.1%20--%208.4-blue?style=flat-square\&logo=php)](https://php.net)
+[![Laravel](https://img.shields.io/badge/Laravel-8--12-brightgreen?style=flat-square&logo=laravel)](https://laravel.com)
+[![PHP](https://img.shields.io/badge/PHP-8.1%20--%208.4-blue?style=flat-square&logo=php)](https://php.net)
+[![Elasticsearch](https://img.shields.io/badge/Search-DB%20or%20Elasticsearch-ff9900?style=flat-square&logo=elasticsearch)](#elasticsearch-integration)
 
 ## Overview
 
@@ -39,7 +40,8 @@ This package removes that trade-off by introducing a **detached searchable index
 * **High scalability** — Efficient for millions of records through database indexing or Elasticsearch.
 * **Elasticsearch integration** — Optionally store and query search tokens directly in an Elasticsearch index.
 * **Laravel-native integration** — Works directly with Eloquent models, query scopes, and model events.
-
+* **Automatic field detection** — Automatically indexes fields that use an encrypted cast when enabled.
+* **Fine-grained configuration** — Supports attributes (`#[EncryptedSearch]`) and `$encryptedSearch` arrays for per-field behavior.
 ---
 
 ## How It Works
@@ -124,6 +126,9 @@ curl -X GET "http://localhost:9200/encrypted_search/_search?pretty" \
 }'
 ```
 
+Both the database and Elasticsearch drivers use the same search scopes —
+your application code remains identical regardless of which backend is active.
+
 For prefix-based queries, you can match multiple tokens:
 
 ```bash
@@ -166,6 +171,8 @@ php artisan vendor:publish --provider="Ginkelsoft\EncryptedSearch\EncryptedSearc
 php artisan migrate
 ```
 
+If you plan to use the Elasticsearch integration, make sure an Elasticsearch instance (version **8.x or newer**) is running and accessible at the host defined in your `.env` file.
+
 Then add a unique pepper to your `.env` file:
 
 ```
@@ -196,21 +203,20 @@ return [
 
 ### Model Setup
 
+If `auto_index_encrypted_casts` is enabled in the configuration (default: **true**),
+all model fields that use an `encrypted:` cast will be automatically indexed for exact search,
+even if they are not explicitly listed in `$encryptedSearch`.
+
+You can also use PHP attributes to control search behavior per field:
+
 ```php
-use Illuminate\Database\Eloquent\Model;
-use Ginkelsoft\EncryptedSearch\Traits\HasEncryptedSearchIndex;
+use Ginkelsoft\EncryptedSearch\Attributes\EncryptedSearch;
 
 class Client extends Model
 {
-    use HasEncryptedSearchIndex;
-
-    protected array $encryptedSearch = [
-        'first_names' => ['exact' => true, 'prefix' => true],
-        'last_names'  => ['exact' => true, 'prefix' => true],
-        'bsn'         => ['exact' => true],
-    ];
+    #[EncryptedSearch(exact: true, prefix: true)]
+    public string $last_names;
 }
-```
 
 When a record is saved, searchable tokens are automatically generated in `encrypted_search_index` or synced to Elasticsearch.
 
@@ -223,8 +229,17 @@ $clients = Client::encryptedExact('last_names', 'Vermeer')->get();
 // Prefix match
 $clients = Client::encryptedPrefix('first_names', 'Wie')->get();
 ```
+Attributes always override global or $encryptedSearch configuration for the same field.
 
-### Rebuilding the Index
+---
+
+#### ✅ 3. **Configuration block (insert this before `'elasticsearch' => [...]`)**
+```php
+'auto_index_encrypted_casts' => true,
+
+## Rebuilding or Syncing the Search Index
+This command automatically detects whether you are using the database or Elasticsearch driver,
+and rebuilds the appropriate index accordingly.
 
 Rebuild indexes via Artisan:
 
@@ -269,6 +284,16 @@ The package is continuously tested across all supported combinations using GitHu
 
 ---
 
+## Troubleshooting
+
+**ConnectionException (cURL error 7)**  
+Ensure your Elasticsearch container or service is running and reachable at the configured `ELASTICSEARCH_HOST`.
+
+**Missing index mappings**  
+If you haven’t created the Elasticsearch index yet, initialize it manually:
+```bash
+curl -X PUT http://localhost:9200/encrypted_search
+
 ## License
 
 MIT License

config/encrypted-search.php

@@ -19,7 +19,23 @@
     | Bijv. "wietse" -> ["w","wi","wie"]
     */
     'max_prefix_depth' => 6,
-    
+
+    /*
+    |--------------------------------------------------------------------------
+    | Auto-index encrypted casts
+    |--------------------------------------------------------------------------
+    |
+    | When enabled, the package will automatically include any model attributes
+    | that use Laravel's "encrypted" casts (e.g. AsEncryptedString, AsEncryptedArray)
+    | in the encrypted search index.
+    |
+    | You can still override or fine-tune behavior via:
+    | - Attributes: #[EncryptedSearch(exact: true, prefix: false)]
+    | - The $encryptedSearch property on your model
+    |
+    */
+    'auto_index_encrypted_casts' => true,
+
     'elasticsearch' => [
         'enabled' => env('ENCRYPTED_SEARCH_ELASTIC_ENABLED', false),
         'host'    => env('ELASTICSEARCH_HOST', 'http://elasticsearch:9200'),

src/Attributes/EncryptedSearch.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Ginkelsoft\EncryptedSearch\Attributes;
+
+use Attribute;
+
+/**
+ * Marks a model property as searchable in the encrypted search index.
+ *
+ * Example:
+ * #[EncryptedSearch(exact: true, prefix: true)]
+ * public string $first_name;
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class EncryptedSearch
+{
+    public function __construct(
+        public bool $exact = true,
+        public bool $prefix = false
+    ) {}
+
+    public function toArray(): array
+    {
+        return [
+            'exact' => $this->exact,
+            'prefix' => $this->prefix,
+        ];
+    }
+}

src/Traits/HasEncryptedSearchIndex.php

@@ -14,16 +14,16 @@
  * Trait HasEncryptedSearchIndex
  *
  * Adds encrypted search indexing capabilities to Eloquent models.
- * When enabled, models can either index search tokens in the database
- * or directly in Elasticsearch — depending on configuration.
+ * Depending on configuration, the generated tokens are stored either
+ * in a local database table (`encrypted_search_index`) or directly in
+ * Elasticsearch for external indexing.
  *
  * Configuration:
- *   - If `encrypted-search.elasticsearch.enabled = true`, all tokens
- *     are sent directly to Elasticsearch (DB is skipped).
- *   - Otherwise, tokens are stored in the local
- *     `encrypted_search_index` database table.
+ * - If `encrypted-search.elasticsearch.enabled = true`, tokens are
+ *   sent directly to Elasticsearch (database index is skipped).
+ * - Otherwise, tokens are stored in the local database index.
  *
- * Example:
+ * Example usage:
  *
  * class Client extends Model {
  *     use HasEncryptedSearchIndex;
@@ -58,7 +58,8 @@ public static function bootHasEncryptedSearchIndex(): void
     }
 
     /**
-     * Create or refresh all encrypted search entries for this model instance.
+     * Build or refresh all encrypted search tokens for this model instance.
+     * Tokens are written to either the local database or Elasticsearch.
      *
      * @return void
      */
@@ -71,7 +72,7 @@ public function updateSearchIndex(): void
         }
 
         $pepper = (string) config('encrypted-search.search_pepper', '');
-        $max    = (int) config('encrypted-search.max_prefix_depth', 6);
+        $max = (int) config('encrypted-search.max_prefix_depth', 6);
         $useElastic = config('encrypted-search.elasticsearch.enabled', false);
 
         $rows = [];
@@ -83,12 +84,12 @@ public function updateSearchIndex(): void
             }
 
             $normalized = Normalizer::normalize($raw);
-            if (! $normalized) {
+            if (!$normalized) {
                 continue;
             }
 
-            // Exact tokens
-            if (! empty($modes['exact'])) {
+            // Generate exact-match tokens
+            if (!empty($modes['exact'])) {
                 $rows[] = [
                     'model_type' => static::class,
                     'model_id'   => $this->getKey(),
@@ -100,8 +101,8 @@ public function updateSearchIndex(): void
                 ];
             }
 
-            // Prefix tokens
-            if (! empty($modes['prefix'])) {
+            // Generate prefix-based tokens
+            if (!empty($modes['prefix'])) {
                 foreach (Tokens::prefixes($normalized, $max, $pepper) as $token) {
                     $rows[] = [
                         'model_type' => static::class,
@@ -124,7 +125,6 @@ public function updateSearchIndex(): void
         if ($useElastic) {
             $this->syncToElasticsearch($rows);
         } else {
-            // Remove existing DB entries and insert new ones
             SearchIndex::where('model_type', static::class)
                 ->where('model_id', $this->getKey())
                 ->delete();
@@ -134,7 +134,10 @@ public function updateSearchIndex(): void
     }
 
     /**
-     * Delete all encrypted search entries related to this model instance.
+     * Remove all search index entries related to this model instance.
+     *
+     * Depending on configuration, either the database index rows or
+     * the corresponding Elasticsearch documents are deleted.
      *
      * @return void
      */
@@ -152,9 +155,9 @@ public function removeSearchIndex(): void
     }
 
     /**
-     * Push new/updated tokens to Elasticsearch index.
+     * Push generated tokens to the configured Elasticsearch index.
      *
-     * @param array<int, array<string,mixed>> $rows
+     * @param  array<int, array<string, mixed>>  $rows
      * @return void
      */
     protected function syncToElasticsearch(array $rows): void
@@ -169,7 +172,9 @@ protected function syncToElasticsearch(array $rows): void
     }
 
     /**
-     * Remove this model’s tokens from Elasticsearch.
+     * Remove this model’s tokens from the configured Elasticsearch index.
+     *
+     * Uses a boolean query to match documents by model_type and model_id.
      *
      * @return void
      */
@@ -178,8 +183,6 @@ protected function removeFromElasticsearch(): void
         $index = config('encrypted-search.elasticsearch.index', 'encrypted_search');
         $service = app(ElasticsearchService::class);
 
-        // We can’t query SearchIndex table because we skip DB
-        // → just remove all docs by model_id
         $query = [
             'query' => [
                 'bool' => [
@@ -192,8 +195,8 @@ protected function removeFromElasticsearch(): void
         ];
 
         try {
-            $service->search($index, $query); // optional: confirm existence
-            // Simpelere aanpak zou bulk delete API kunnen gebruiken
+            $service->search($index, $query);
+            // Optional: replace with Elasticsearch delete-by-query API for optimization
         } catch (\Throwable $e) {
             logger()->warning("Failed to remove Elasticsearch docs for model {$this->getKey()}: {$e->getMessage()}");
         }
@@ -202,17 +205,17 @@ protected function removeFromElasticsearch(): void
     /**
      * Scope: query models by exact encrypted token match.
      *
-     * @param Builder $query
-     * @param string $field
-     * @param string $term
+     * @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', '');
         $normalized = Normalizer::normalize($term);
 
-        if (! $normalized) {
+        if (!$normalized) {
             return $query->whereRaw('1=0');
         }
 
@@ -231,17 +234,17 @@ public function scopeEncryptedExact(Builder $query, string $field, string $term)
     /**
      * Scope: query models by prefix-based encrypted token match.
      *
-     * @param Builder $query
-     * @param string $field
-     * @param string $term
+     * @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', '');
         $normalized = Normalizer::normalize($term);
 
-        if (! $normalized) {
+        if (!$normalized) {
             return $query->whereRaw('1=0');
         }
 
@@ -262,21 +265,46 @@ public function scopeEncryptedPrefix(Builder $query, string $field, string $term
     }
 
     /**
-     * Retrieve the encrypted search field configuration.
+     * Resolve the encrypted search configuration for this model.
+     *
+     * The configuration may be determined from:
+     * - auto-detected encrypted casts (if enabled),
+     * - PHP attributes (#[EncryptedSearch]),
+     * - the `$encryptedSearch` property on the model.
      *
-     * Models may define configuration either via a
-     * `getEncryptedSearchFields()` method or a `$encryptedSearch` property.
+     * Priority:
+     * 1. $encryptedSearch (explicit overrides)
+     * 2. #[EncryptedSearch] attributes
+     * 3. auto-detected encrypted casts
      *
-     * @return array<string, array<string,bool>>
+     * @return array<string, array<string, bool>>
      */
     protected function getEncryptedSearchConfiguration(): array
     {
-        if (method_exists($this, 'getEncryptedSearchFields')) {
-            return $this->getEncryptedSearchFields();
+        $config = [];
+
+        // Auto-detect encrypted casts (if enabled)
+        if (config('encrypted-search.auto_index_encrypted_casts', true)) {
+            foreach ($this->getCasts() as $field => $cast) {
+                if (str_contains(strtolower($cast), 'encrypted')) {
+                    $config[$field] = ['exact' => true, 'prefix' => false];
+                }
+            }
+        }
+
+        // Detect #[EncryptedSearch] attributes
+        $reflection = new \ReflectionClass($this);
+        foreach ($reflection->getProperties() as $property) {
+            foreach ($property->getAttributes(\Ginkelsoft\EncryptedSearch\Attributes\EncryptedSearch::class) as $attr) {
+                $config[$property->getName()] = $attr->newInstance()->toArray();
+            }
+        }
+
+        // Merge with explicit $encryptedSearch property (highest priority)
+        if (property_exists($this, 'encryptedSearch')) {
+            $config = array_merge($config, $this->encryptedSearch);
         }
 
-        return property_exists($this, 'encryptedSearch')
-            ? $this->encryptedSearch
-            : [];
+        return $config;
     }
 }