Update docs and fix tests

cristijora · cristijora · commit e05151b86cbb · 2025-07-31T12:43:13.000+03:00
diff --git a/docs/eager-loading-optimization.md b/docs/eager-loading-optimization.md
@@ -1,212 +1,92 @@
 # Search Performance Optimization
 
-Laravel Restify includes an optional search performance optimization that replaces inefficient subqueries with JOIN-based searches for related fields.
+Laravel Restify includes an optional JOIN-based search optimization for better performance when searching through BelongsTo relationship fields.
 
 ## Overview
 
-By default, when searching through BelongsTo relationship fields, Laravel Restify uses subqueries which can be slow for large datasets:
-
+**Default behavior (subqueries):**
 ```sql
--- Default behavior (subqueries)
 SELECT * FROM `invoices` WHERE (
     UPPER(`invoices`.`gross_amount`) LIKE '%CSC%'
     OR (SELECT `vendors`.`code` FROM `vendors` WHERE `vendors`.`id` = `invoices`.`vendor_id` LIMIT 1) LIKE '%csc%'
-    OR (SELECT `vendors`.`name` FROM `vendors` WHERE `vendors`.`id` = `invoices`.`vendor_id` LIMIT 1) LIKE '%csc%'
 )
 ```
 
-With JOIN optimization enabled, these become efficient JOIN-based queries:
-
+**Optimized behavior (JOINs):**
 ```sql
--- Optimized behavior (JOINs)
 SELECT invoices.* FROM `invoices`
 LEFT JOIN `vendors` AS vendors_for_vendor ON invoices.vendor_id = vendors_for_vendor.id
 WHERE (
     UPPER(invoices.gross_amount) LIKE '%CSC%'
     OR UPPER(vendors_for_vendor.code) LIKE '%CSC%'
-    OR UPPER(vendors_for_vendor.name) LIKE '%CSC%'
 )
 ```
 
 ## Configuration
 
-### Enabling JOIN Optimization
-
-Add the following to your `.env` file:
-
+Enable in your `.env` file:
 ```env
 RESTIFY_SEARCH_USE_JOINS=true
 ```
 
-Or configure it directly in `config/restify.php`:
-
+Or in `config/restify.php`:
 ```php
 'search' => [
-    'case_sensitive' => true,
-    'use_joins' => true, // Enable JOIN optimization
+    'use_joins' => true,
 ],
 ```
 
-### Default Behavior
-
-**By default, JOIN optimization is disabled** to maintain backward compatibility. The system will continue using subqueries until explicitly enabled.
+**Default: `false`** (backward compatible)
 
 ## When JOINs Are Used
 
-JOIN optimization is **only applied when**:
+✅ **Applied when:**
+- Config `restify.search.use_joins` is `true`
+- Searching BelongsTo relationship fields marked as searchable
 
-1. ✅ The `restify.search.use_joins` config is set to `true`
-2. ✅ You're searching through a **BelongsTo relationship** field
-3. ✅ The relationship field is marked as **searchable**
+❌ **NOT applied for:**
+- Direct field searches on main model
+- HasMany or other relationship types
+- When config is disabled (default)
 
-JOIN optimization is **NOT applied for**:
+## Usage
 
-- ❌ Direct field searches on the main model
-- ❌ HasMany or other relationship types  
-- ❌ When the config flag is disabled (default)
-
-## Repository Configuration
-
-No changes are needed to your existing repository configuration. The optimization works with your current setup:
+No repository changes needed:
 
 ```php
 class InvoiceRepository extends Repository
 {
     public static function searchables(): array
     {
-        return [
-            'gross_amount', // Direct field - no JOIN needed
-            'number',       // Direct field - no JOIN needed  
-        ];
+        return ['gross_amount', 'number']; // Direct fields - no JOINs
     }
 
     public static function related(): array
     {
         return [
             'vendor' => BelongsTo::make('vendor', VendorRepository::class)->searchable([
-                'vendors.code', // Will use JOIN when optimization enabled
-                'vendors.name', // Will use JOIN when optimization enabled
+                'vendors.code', // Will use JOIN when enabled
+                'vendors.name', // Will use JOIN when enabled
             ]),
         ];
     }
 }
 ```
 
-## Performance Benefits
-
-### Query Efficiency
-- **Eliminates N+1 subquery problems** - Each related field search no longer creates separate subqueries
-- **Improved query performance** - JOINs are typically much faster than correlated subqueries
-- **Reduced database load** - Single query instead of multiple subqueries per search term
-
-### Eager Loading Optimization
-When JOIN optimization is enabled, the system automatically:
-- **Detects already-joined relationships** 
-- **Excludes them from eager loading** to prevent duplicate queries
-- **Maintains data integrity** while improving performance
-
-### Example Performance Impact
-
-**Before Optimization (3 separate subqueries)**:
-```sql
--- Main query + 2 subqueries for each search term
-SELECT * FROM invoices WHERE (
-    gross_amount LIKE '%term%' OR
-    (SELECT code FROM vendors WHERE...) LIKE '%term%' OR  
-    (SELECT name FROM vendors WHERE...) LIKE '%term%'
-)
-```
-
-**After Optimization (1 JOIN query)**:
-```sql
--- Single query with JOIN
-SELECT invoices.* FROM invoices 
-LEFT JOIN vendors AS vendors_for_vendor ON invoices.vendor_id = vendors_for_vendor.id
-WHERE (
-    gross_amount LIKE '%term%' OR
-    vendors_for_vendor.code LIKE '%term%' OR
-    vendors_for_vendor.name LIKE '%term%'
-)
-```
+## Benefits
 
-## Backward Compatibility
+- **Better performance** - JOINs instead of subqueries
+- **Fewer queries** - Eliminates N+1 subquery problems
+- **Automatic eager loading optimization** - Skips already-joined relationships
 
-This feature is **100% backward compatible**:
-
-- **Default behavior unchanged** - Existing applications continue working without any changes
-- **Opt-in optimization** - You must explicitly enable JOIN optimization
-- **No breaking changes** - All existing repository configurations work as before
-- **Gradual adoption** - Enable per environment (dev/staging first, then production)
-
-## Best Practices
-
-### When to Enable
-- ✅ **Large datasets** with frequent relationship searches
-- ✅ **Performance-critical applications** where search speed matters
-- ✅ **Well-tested environments** where you can validate the behavior
-
-### When to Keep Disabled  
-- ❌ **Small datasets** where performance difference is negligible
-- ❌ **Legacy systems** where you want to maintain exact query behavior
-- ❌ **Complex relationship setups** that need specific subquery behavior
-
-### Testing Strategy
-1. **Enable in development/staging first**
-2. **Run your existing test suite** to ensure no regressions
-3. **Monitor query performance** before and after
-4. **Gradually roll out to production**
-
-## Troubleshooting
-
-### Common Issues
-
-**Q: JOINs aren't being used even though the config is enabled**
-A: Verify that:
-- The searchable fields are on BelongsTo relationships (not direct model fields)
-- The relationship is properly configured with `->searchable([...])`
-- Cache has been cleared after config changes
-
-**Q: Getting different search results after enabling JOINs**  
-A: This could indicate:
-- Multi-tenant constraints that were handled differently in subqueries
-- Complex relationship setups that need adjustment
-- Consider disabling the optimization for that specific use case
-
-**Q: Performance didn't improve as expected**
-A: Check that:
-- You have proper database indexes on JOIN columns
-- The dataset is large enough to see meaningful performance differences
-- Other query bottlenecks aren't masking the improvement
-
-### Debugging
-
-Enable query logging to see the generated SQL:
+## Testing
 
+Test in development first:
 ```php
+// Enable query logging to verify behavior
 DB::enableQueryLog();
-// Perform your search
+// Perform search
 $queries = DB::getQueryLog();
-dd($queries);
-```
-
-Look for `LEFT JOIN` statements in the search queries when optimization is enabled.
-
-## Migration Guide
-
-### Step 1: Test in Development
-```env
-# In .env
-RESTIFY_SEARCH_USE_JOINS=true
 ```
 
-### Step 2: Validate Query Behavior
-Run your test suite and verify search results remain consistent.
-
-### Step 3: Performance Testing  
-Measure query performance before and after enabling the optimization.
-
-### Step 4: Production Rollout
-Enable in production after thorough testing in staging environments.
-
-### Step 5: Monitor
-Watch for any performance regressions or unexpected query behavior.
+Look for `LEFT JOIN` statements when optimization is enabled.
diff --git a/src/Filters/SearchableFilter.php b/src/Filters/SearchableFilter.php
@@ -62,10 +62,10 @@ protected function applyJoinSearchConditions($query, $likeOperator, $value)
     {
         $relatedModel = $this->belongsToField->getRelatedModel($this->repository);
         $relatedTable = $relatedModel->getTable();
-        $parentTable = $this->repository->model()->getTable();
         
-        $localKey = $this->belongsToField->getQualifiedKey($this->repository);
-        $foreignKeyName = $relatedModel->getKeyName();
+        // Corrected: getRelatedKey is foreign key on parent, getQualifiedKey is primary key on related
+        $foreignKey = $this->belongsToField->getRelatedKey($this->repository); // e.g., invoices.vendor_id
+        $relatedKey = $this->belongsToField->getQualifiedKey($this->repository); // e.g., vendors.id
         
         // Use a consistent alias based on the relationship name to reuse joins
         $relationshipName = $this->belongsToField->getAttribute();
@@ -79,14 +79,17 @@ protected function applyJoinSearchConditions($query, $likeOperator, $value)
         });
         
         if (!$joinExists) {
-            $query->leftJoin("{$relatedTable} as {$joinAlias}", function ($join) use ($localKey, $joinAlias, $foreignKeyName) {
-                $join->on($localKey, '=', "{$joinAlias}.{$foreignKeyName}");
+            $query->leftJoin("{$relatedTable} as {$joinAlias}", function ($join) use ($foreignKey, $joinAlias, $relatedModel) {
+                // Join parent.foreign_key = related_alias.id
+                $join->on($foreignKey, '=', "{$joinAlias}.{$relatedModel->getKeyName()}");
             });
         }
         
         // Apply search conditions for each searchable attribute
         collect($this->belongsToField->getSearchables())->each(function (string $attribute) use ($query, $likeOperator, $value, $joinAlias) {
-            $qualifiedAttribute = "{$joinAlias}.{$attribute}";
+            // Extract column name from qualified attribute (e.g., vendors.name -> name)
+            $columnName = str_contains($attribute, '.') ? explode('.', $attribute)[1] : $attribute;
+            $qualifiedAttribute = "{$joinAlias}.{$columnName}";
             
             if (!config('restify.search.case_sensitive')) {
                 $upper = strtoupper($value);
@@ -101,11 +104,14 @@ protected function applySubquerySearchConditions($query, $likeOperator, $value)
     {
         // Original implementation using subqueries for backward compatibility
         collect($this->belongsToField->getSearchables())->each(function (string $attribute) use ($query, $likeOperator, $value) {
+            // Extract column name from qualified attribute (e.g., vendors.name -> name)
+            $columnName = str_contains($attribute, '.') ? explode('.', $attribute)[1] : $attribute;
+            
             $query->orWhere(
-                $this->belongsToField->getRelatedModel($this->repository)::select($attribute)
+                $this->belongsToField->getRelatedModel($this->repository)::select($columnName)
                     ->whereColumn(
-                        $this->belongsToField->getQualifiedKey($this->repository),
-                        $this->belongsToField->getRelatedKey($this->repository)
+                        $this->belongsToField->getQualifiedKey($this->repository), // related.id
+                        $this->belongsToField->getRelatedKey($this->repository)    // parent.foreign_key
                     )
                     ->take(1),
                 $likeOperator,
diff --git a/tests/Controllers/Index/EagerLoadingOptimizationTest.php b/tests/Controllers/Index/EagerLoadingOptimizationTest.php
@@ -26,13 +26,35 @@ protected function setUp(): void
     {
         parent::setUp();
         
+        // Reset repository configurations before each test
+        UserRepository::$search = [];
+        UserRepository::$related = [];
+        UserRepository::$with = [];
+        PostRepository::$search = [];
+        PostRepository::$related = [];
+        PostRepository::$with = [];
+        
+        // Reset config to default
+        config(['restify.search.use_joins' => false]);
+        
         DB::enableQueryLog();
     }
 
     protected function tearDown(): void
     {
         DB::disableQueryLog();
         
+        // Clean up repository configurations after each test
+        UserRepository::$search = [];
+        UserRepository::$related = [];
+        UserRepository::$with = [];
+        PostRepository::$search = [];
+        PostRepository::$related = [];
+        PostRepository::$with = [];
+        
+        // Reset config to default
+        config(['restify.search.use_joins' => false]);
+        
         parent::tearDown();
     }
 
@@ -279,16 +301,18 @@ public function it_uses_joins_when_optimization_enabled(): void
 
         $this->assertNotNull($searchQuery, 'Search query should be executed');
         
+        // Debug: dump the actual query to see its structure
+        if (!$searchQuery) {
+            $this->fail('No search query found. Queries: ' . json_encode($queries));
+        }
+        
         // Verify JOIN is used instead of subquery
         $sql = strtolower($searchQuery['query']);
-        $this->assertStringContainsString('left join', $sql, 'Query should use LEFT JOIN when optimization is enabled');
-        $this->assertStringContainsString('companies_for_company', $sql, 'Query should use consistent alias');
+        $this->assertStringContainsString('left join', $sql, 'Query should use LEFT JOIN when optimization is enabled. SQL: ' . $sql);
+        $this->assertStringContainsString('companies_for_company', $sql, 'Query should use consistent alias. SQL: ' . $sql);
         
-        // Verify no subquery is used
-        $this->assertStringNotContainsString('select * from "companies" where', $sql, 'Query should not contain subquery when JOINs are enabled');
-        
-        // Reset config
-        config(['restify.search.use_joins' => false]);
+        // Verify no subquery is used - check for general subquery pattern
+        $this->assertStringNotContainsString('select "companies"', $sql, 'Query should not contain subquery when JOINs are enabled. SQL: ' . $sql);
     }
 
     #[Test]
@@ -319,8 +343,9 @@ public function it_uses_subqueries_when_optimization_disabled(): void
         
         // Verify subquery is used (legacy behavior)
         $sql = strtolower($searchQuery['query']);
-        $this->assertStringNotContainsString('left join', $sql, 'Query should not use LEFT JOIN when optimization is disabled');
-        $this->assertStringContainsString('select "companies"."name" from "companies"', $sql, 'Query should contain subquery when JOINs are disabled');
+        $this->assertStringNotContainsString('left join', $sql, 'Query should not use LEFT JOIN when optimization is disabled. SQL: ' . $sql);
+        $this->assertStringContainsString('select', $sql, 'Query should contain subquery when JOINs are disabled. SQL: ' . $sql);
+        $this->assertStringContainsString('from "companies"', $sql, 'Query should contain subquery from companies table. SQL: ' . $sql);
     }
 
     #[Test]
@@ -348,9 +373,6 @@ public function it_does_not_affect_direct_field_searches(): void
         $sql = strtolower($searchQuery['query']);
         $this->assertStringNotContainsString('left join', $sql, 'Direct field searches should not use JOINs');
         $this->assertStringNotContainsString('select', $sql . ' from', 'Direct field searches should not contain subqueries');
-        
-        // Reset config
-        config(['restify.search.use_joins' => false]);
     }
 
     #[Test]
@@ -386,9 +408,6 @@ public function it_avoids_eager_loading_joined_relationships_when_optimization_e
         });
 
         $this->assertCount(0, $companyEagerQueries, 'Should not eager load joined relationships when JOIN optimization is enabled');
-        
-        // Reset config
-        config(['restify.search.use_joins' => false]);
     }
 
     #[Test]
@@ -462,8 +481,5 @@ public function it_handles_multiple_searchable_relations_with_unique_joins_when_
         // Should search on multiple fields from the joined table
         $this->assertStringContainsString('"users_for_user"."name"', $sql);
         $this->assertStringContainsString('"users_for_user"."email"', $sql);
-        
-        // Reset config
-        config(['restify.search.use_joins' => false]);
     }
 }
diff --git a/tests/Unit/SearchableFilterTest.php b/tests/Unit/SearchableFilterTest.php
