Ajax Autocomplete Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require antqa/ajax-autocomplete-bundle
   

   Add to config/bundles.php (Laravel 5.4+):

   return [
       // ...
       AntQa\AjaxAutoCompleteBundle\AntQaAjaxAutoCompleteBundle::class => ['all' => true],
   ];
   

2. Define Routes (in routes/web.php):

   Route::get('/find', [YourController::class, 'find'])->name('autocomplete.find');
   Route::get('/get/{ids}', [YourController::class, 'get'])->name('autocomplete.get');
   

3. Basic Controller (Laravel-style):

   use Illuminate\Http\Request;
   use Illuminate\Support\Facades\DB;
   
   public function find(Request $request) {
       $query = $request->input('q');
       $results = DB::table('your_table')
           ->where('column', 'LIKE', "%{$query}%")
           ->select('id', 'name')
           ->get();
       return response()->json($results);
   }
   
   public function get($ids) {
       $ids = explode(',', $ids);
       $results = DB::table('your_table')
           ->whereIn('id', $ids)
           ->select('id', 'name')
           ->get();
       return response()->json($results);
   }
   

4. Frontend Integration (jQuery + Select2):

   $('select').select2({
       ajax: {
           url: '/find',
           dataType: 'json',
           data: function(params) {
               return { q: params.term };
           },
           processResults: function(data) {
               return { results: data };
           }
       }
   });
   

Implementation Patterns

Common Workflows

1. Form Integration:

   • Use with Laravel Collective's Form facade:

     {!! Form::select('search', null, [], [
         'class' => 'autocomplete-select',
         'data-placeholder' => 'Search...'
     ]) !!}
     

   • Add JavaScript initialization in a blade template:

     $(document).ready(function() {
         $('.autocomplete-select').select2({
             ajax: { url: '{{ route("autocomplete.find") }}' }
         });
     });
     

2. Dynamic Data Sources:

   • Elasticsearch: Modify find() to query Elasticsearch instead of SQL.
   • APIs: Fetch remote data in find() and cache responses.

3. Validation & Sanitization:

   • Sanitize input in find():

     $query = trim($request->input('q', ''));
     if (strlen($query) < 2) return response()->json([]);
     

4. Pagination:

   • Add limit and offset to queries:

     $results = DB::table('your_table')
         ->where('column', 'LIKE', "%{$query}%")
         ->select('id', 'name')
         ->limit(10)
         ->offset($request->input('offset', 0))
         ->get();
     

5. Caching:

   • Cache frequent queries (e.g., top 100 results):

     $cacheKey = "autocomplete:{$query}";
     $results = Cache::remember($cacheKey, 3600, function() use ($query) {
         return DB::table('your_table')->where('column', 'LIKE', "%{$query}%")->get();
     });
     

Integration Tips

1. Laravel Mix/Webpack:

   • Bundle Select2 CSS/JS:

     // resources/js/app.js
     import 'select2/dist/css/select2.min.css';
     import 'select2/dist/js/select2.min.js';
     

2. API Resources:

   • Use Laravel's ApiResource for consistent JSON responses:

     class AutocompleteResource extends JsonResource {
         public function toArray($request) {
             return [
                 'id' => $this->id,
                 'text' => $this->name,
             ];
         }
     }
     

     Then return:

     return response()->json(AutocompleteResource::collection($results));
     

3. Middleware:

   • Protect routes with auth or throttle middleware:

     Route::get('/find', [YourController::class, 'find'])
         ->middleware('auth')
         ->name('autocomplete.find');
     

4. Testing:

   • Test routes with Http::fake():

     $response = $this->get('/find?q=test');
     $response->assertJsonCount(2);
     

Gotchas and Tips

Pitfalls

1. CSRF Protection:

   • Disable CSRF for AJAX routes (Laravel 5.5+):

     Route::get('/find', [YourController::class, 'find'])
         ->middleware('web')
         ->middleware('csrf-exempt'); // Only if needed!
     

   • Better: Use VerifyCsrfToken exception:

     public function find(Request $request) {
         if (!$request->expectsJson()) {
             abort(403);
         }
         // ...
     }
     

2. SQL Injection:

   • Always use parameter binding (as shown in examples). Avoid raw string concatenation:

     // ❌ Bad
     DB::table('users')->where("name LIKE '%{$query}%'");
     
     // ✅ Good
     DB::table('users')->where('name', 'LIKE', "%{$query}%");
     

3. Case Sensitivity:

   • Add LOWER() or ILIKE for case-insensitive searches:

     DB::table('users')->whereRaw('LOWER(name) LIKE ?', ["%{$query}%"]);
     

4. Performance:

   • Avoid SELECT *; explicitly define columns.
   • Add indexes to search columns:

     CREATE INDEX idx_name ON users(name);
     

5. Select2 Version Mismatch:

   • The bundle assumes Select2 3.x. For Select2 4.x, update the formatResult/formatSelection to use text:

     formatResult: object => object.text,
     formatSelection: object => object.text,
     

Debugging Tips

1. Check Network Requests:

   • Use browser dev tools to verify:
     • Correct URL and parameters are sent.
     • Response format matches Select2 expectations ({ results: [...] }).

2. Log Queries:

   • Enable Laravel query logging:

     DB::enableQueryLog();
     // Run query...
     dd(DB::getQueryLog());
     

3. Validate JSON:

   • Ensure responses are valid JSON:

     return response()->json($data)->setEncodingOptions(JSON_UNESCAPED_SLASHES);
     

4. Test with Postman:

   • Manually test /find?q=test to isolate backend issues.

Extension Points

1. Custom Data Transformers:

   • Create a service to transform entities to autocomplete format:

     class AutocompleteTransformer {
         public static function transform($entity) {
             return [
                 'id' => $entity->id,
                 'text' => $entity->name,
                 'children' => $entity->children->pluck('name'),
             ];
         }
     }
     

2. Event Listeners:

   • Dispatch events for search actions:

     event(new AutocompleteSearched($query, $results));
     

3. Dynamic Route Binding:

   • Use Laravel's route model binding for /get/{ids}:

     Route::get('/get/{ids}', [YourController::class, 'get'])
         ->where('ids', '.*');
     

4. Twig Integration (if using Symfony):

   • Extend the bundle to support Twig templates for autocomplete fields.

Configuration Quirks

1. Symfony vs. Laravel:

   • The bundle is Symfony-based. In Laravel:
     • Replace QueryBuilder with Eloquent or Query Builder.
     • Use Laravel's routing (Route::get) instead of Symfony's YAML routes.

2. Deprecated Methods:

   • Avoid setParameter('name', $value) in Laravel; use ->where('name', $value).

3. Bundle Auto-Loading:

   • If using Laravel's auto-discovery, ensure the bundle is listed in config/app.php under providers.

4. JavaScript Conflicts:

   • If Select2 doesn’t initialize, ensure jQuery is loaded before Select2:

     <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/select2@4.1.0-rc.0/dist/js/select2.min.js"></script>