fix: searchables

Author: binaryk

docs-v2/content/en/api/fields.md

@@ -507,6 +507,196 @@ field('author')->matchable(function ($request, $query, $value) {
 }),
 ```
 
+## Searchable
+
+Fields can be made searchable, enabling them to respond to global search queries. This provides field-level control over search behavior while maintaining the simplicity of the global search API.
+
+### Making Fields Searchable
+
+To make a field searchable, chain the `searchable()` method:
+
+```php
+public function fields(RestifyRequest $request)
+{
+    return [
+        field('title')->searchable(),
+        field('description')->searchable(),
+        field('email')->searchable(),
+    ];
+}
+```
+
+The `searchable()` method uses a unified flexible signature that accepts multiple arguments and works consistently across all field types:
+
+```php
+// Basic usage
+field('title')->searchable(),
+
+// Custom column
+field('name')->searchable('users.full_name'),
+
+// With optional type
+field('price')->searchable('products.price', 'numeric'),
+
+// Multiple attributes (especially useful for relationship fields like BelongsTo)
+BelongsTo::make('author')->searchable('name', 'email', 'username'),
+
+// Array of attributes (legacy support)
+BelongsTo::make('editor')->searchable(['users.name', 'users.email']),
+
+// Closure/callback
+field('content')->searchable(function ($request, $query, $value) {
+    // Custom search logic
+}),
+
+// Custom filter instance
+field('complex_search')->searchable(new CustomSearchFilter()),
+
+// Invokable class
+field('tags')->searchable(new TagSearchHandler()),
+```
+
+### Unified Method Signatures
+
+All searchable-related methods now use consistent signatures across regular fields and relationship fields:
+
+```php
+// All field types use the same signatures:
+searchable(...$attributes)                    // Flexible variadic signature
+isSearchable(?RestifyRequest $request = null) // Optional request parameter
+getSearchColumn(?RestifyRequest $request = null) // Optional request parameter
+
+// BelongsTo also provides relationship-specific method:
+getSearchables(): array                       // Returns multiple searchable attributes
+```
+
+### Using Searchable Fields
+
+Searchable fields respond to the standard `search` query parameter:
+
+```http
+GET /api/restify/posts?search=laravel
+```
+
+This will search across all searchable fields for the term "laravel".
+
+### Advanced Searchable Configuration
+
+#### Basic Usage (No Arguments)
+
+When called without arguments, `searchable()` applies standard search behavior using the field's attribute:
+
+```php
+field('title')->searchable(), // Searches the 'title' column with LIKE operator
+```
+
+#### Custom Column
+
+Specify a different database column for searching:
+
+```php
+field('author_name')->searchable('users.name'), // Search in users.name column
+```
+
+You can also specify multiple attributes for relationship fields (like BelongsTo):
+
+```php
+BelongsTo::make('author', UserRepository::class)->searchable('name', 'email'),
+```
+
+#### Closure-based Searching
+
+For custom search logic, pass a closure that receives the request, query builder, and search value:
+
+```php
+field('content')->searchable(function ($request, $query, $value) {
+    $query->where('title', 'LIKE', "%{$value}%")
+          ->orWhere('description', 'LIKE', "%{$value}%");
+}),
+```
+
+#### Custom SearchableFilter Classes
+
+Create dedicated filter classes for complex search logic:
+
+```php
+field('complex_search')->searchable(new CustomContentSearchFilter),
+```
+
+Where `CustomContentSearchFilter` extends `SearchableFilter`:
+
+```php
+use Binaryk\LaravelRestify\Filters\SearchableFilter;
+use Binaryk\LaravelRestify\Http\Requests\RestifyRequest;
+
+class CustomContentSearchFilter extends SearchableFilter
+{
+    public function filter(RestifyRequest $request, $query, $value)
+    {
+        return $query->where(function ($q) use ($value) {
+            $q->where('title', 'LIKE', "%{$value}%")
+              ->orWhere('description', 'LIKE', "%{$value}%")
+              ->orWhere('tags', 'LIKE', "%{$value}%");
+        });
+    }
+}
+```
+
+#### Invokable Classes
+
+For reusable search logic, use invokable classes:
+
+```php
+field('tags')->searchable(new TagSearchFilter),
+```
+
+```php
+class TagSearchFilter
+{
+    public function __invoke($request, $query, $value)
+    {
+        $tags = explode(',', $value);
+        $query->whereHas('tags', function ($q) use ($tags) {
+            $q->whereIn('name', $tags);
+        });
+    }
+}
+```
+
+#### Practical Examples
+
+**Full-text Search:**
+```php
+field('content')->searchable(function ($request, $query, $value) {
+    $query->whereFullText(['title', 'description'], $value);
+}),
+```
+
+**Multi-field Search:**
+```php
+field('user_search')->searchable(function ($request, $query, $value) {
+    $query->where('name', 'LIKE', "%{$value}%")
+          ->orWhere('email', 'LIKE', "%{$value}%")
+          ->orWhere('phone', 'LIKE', "%{$value}%");
+}),
+```
+
+**Relationship Search:**
+```php
+field('author')->searchable(function ($request, $query, $value) {
+    $query->whereHas('author', function ($q) use ($value) {
+        $q->where('name', 'like', "%{$value}%");
+    });
+}),
+```
+
+**JSON Search:**
+```php
+field('metadata')->searchable(function ($request, $query, $value) {
+    $query->whereJsonContains('metadata->tags', $value);
+}),
+```
+
 ## Validation
 
 There is a golden rule that says - catch the exception as soon as possible on its request way.

src/Fields/BelongsTo.php

@@ -42,20 +42,67 @@ public function fillAttribute(RestifyRequest $request, $model, ?int $bulkRow = n
         );
     }
 
+    /**
+     * Override the parent searchable method to handle BelongsTo-specific multiple attributes
+     */
     public function searchable(...$attributes): self
     {
-        $this->searchablesAttributes = collect($attributes)->flatten()->all();
+        // Handle case where a single array is passed (legacy behavior)
+        if (count($attributes) === 1 && is_array($attributes[0])) {
+            $this->searchablesAttributes = collect($attributes[0])->flatten()->all();
+            // Also call parent with the first attribute for consistency
+            if (!empty($this->searchablesAttributes)) {
+                parent::searchable($this->searchablesAttributes[0]);
+            }
+            return $this;
+        }
+
+        // If it's relationship-specific multiple attributes (all strings), use BelongsTo behavior
+        if (count($attributes) > 1 && collect($attributes)->every(fn($attr) => is_string($attr))) {
+            $this->searchablesAttributes = collect($attributes)->flatten()->all();
+            // Also call parent to maintain consistency with CanSearch trait
+            parent::searchable($attributes[0]);
+            return $this;
+        }
+
+        // For single attribute or complex cases (closures, filters), use parent behavior
+        parent::searchable(...$attributes);
+
+        // If parent set a simple string column, also set it in searchablesAttributes for consistency
+        if (count($attributes) === 1 && is_string($attributes[0])) {
+            $this->searchablesAttributes = [$attributes[0]];
+        }
 
         return $this;
     }
 
-    public function isSearchable(): bool
+    /**
+     * Check if this BelongsTo field is searchable (either via attributes or parent CanSearch)
+     */
+    public function isSearchable(?RestifyRequest $request = null): bool
     {
-        return ! is_null($this->searchablesAttributes);
+        return ! is_null($this->searchablesAttributes) || parent::isSearchable($request);
     }
 
+    /**
+     * Get the searchable attributes specific to BelongsTo relationships
+     */
     public function getSearchables(): array
     {
-        return $this->searchablesAttributes;
+        return $this->searchablesAttributes ?? [];
+    }
+
+    /**
+     * Override parent getSearchColumn to provide BelongsTo-specific behavior
+     */
+    public function getSearchColumn(?RestifyRequest $request = null): mixed
+    {
+        // If we have BelongsTo-specific attributes, return the first one for compatibility
+        if (!empty($this->searchablesAttributes)) {
+            return $this->searchablesAttributes[0];
+        }
+
+        // Otherwise, use parent behavior
+        return parent::getSearchColumn($request);
     }
 }