Autocomplete Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require backsystem/autocomplete
   

2. Configure routes in config/routes/autocomplete.yaml:

   autocomplete:
       resource: '@AutocompleteBundle/config/routes.yaml'
       prefix: /api/search
   

3. Create a basic API class (e.g., src/Api/UserApi.php):

   namespace App\Api;
   
   use App\Entity\User;
   use BackSystem\Autocomplete\AbstractApi;
   use Doctrine\ORM\EntityRepository;
   use Doctrine\ORM\QueryBuilder;
   
   class UserApi extends AbstractApi {
       public function getEntityClass(): string { return User::class; }
       public function getUrl(): string { return '/users'; }
       public function createFilteredQueryBuilder(EntityRepository $repository, string $query): QueryBuilder {
           return $repository->createQueryBuilder('u')
               ->where('u.name LIKE :query')
               ->setParameter('query', '%'.$query.'%');
       }
       public function getValue($entity): string { return $entity->getId(); }
       public function getLabel($entity): string { return $entity->getName(); }
   }
   

4. Use in a form (src/Form/UserType.php):

   use BackSystem\Autocomplete\Type\AutocompleteType;
   
   $builder->add('user', AutocompleteType::class, [
       'class' => UserApi::class,
       'placeholder' => 'Search users...',
   ]);
   

First Use Case

Integrate autocomplete into a user selection field in a Symfony form (e.g., for assigning authors to blog posts). Test by typing in the field—results should appear dynamically.

Implementation Patterns

Core Workflow

1. API Layer:

   • Extend AbstractApi for each entity type needing autocomplete.
   • Implement:
     • getEntityClass(): Return the entity class (e.g., User::class).
     • createFilteredQueryBuilder(): Define search logic (e.g., LIKE queries).
     • getValue()/getLabel(): Format displayed data (e.g., <b>ID</b> - Name).
   • Tip: Use getTitle() for tooltip text (optional but improves UX).

2. Form Integration:

   • Replace standard EntityType with AutocompleteType.
   • Configure via class (your API) and optional:
     • placeholder: User prompt.
     • multiple: Allow multi-select (true).
     • min_length: Minimum characters before search (default: 2).

3. Frontend Handling:

   • The bundle auto-generates JavaScript for the autocomplete UI.
   • Customize via Twig templates (override autocomplete.html.twig if needed).

Advanced Patterns

• Dynamic API Routing: Use prefix in autocomplete.yaml to group endpoints (e.g., /api/search/users).
• Caching: Cache QueryBuilder results in createFilteredQueryBuilder() for large datasets.
• Validation: Override isValid() to enforce business rules (e.g., check user roles).
• Multi-Entity Forms: Chain multiple AutocompleteType fields (e.g., author + editor).

Integration Tips

• Doctrine Filtering: Apply repository filters (e.g., ActiveUserFilter) in createFilteredQueryBuilder().
• Symfony UX Autocomplete: This bundle wraps Symfony UX’s functionality—leverage its events for custom logic.
• API Testing: Test endpoints directly (e.g., GET /api/search/users?q=john) with tools like Postman.

Gotchas and Tips

Common Pitfalls

1. Case Sensitivity:
   • LIKE queries are case-sensitive by default. Use LOWER() or ILIKE (PostgreSQL) for case-insensitive searches:

     ->where('LOWER(u.name) LIKE LOWER(:query)')
     

2. Whitespace Handling:
   • The example trims spaces (str_replace(' ', '', $query)). Adjust based on requirements (e.g., preserve partial matches).
3. Entity Not Found:
   • isValid() must return null for invalid IDs. Omit this method to skip validation.
4. Route Conflicts:
   • Ensure /api/search doesn’t clash with existing routes. Use unique prefixes (e.g., /app/search).

Debugging Tips

• Check API Responses: Visit /api/search/{url}?q=test in your browser to verify raw data.
• Log Queries: Enable Doctrine logging to inspect generated SQL:

  $this->container->get('doctrine')->getConnection()->getConfiguration()->setSQLLogger(new \Doctrine\DBAL\Logging\EchoSQLLogger());
  

• Frontend Errors: Clear cache (php bin/console cache:clear) if autocomplete fails to load.

Extension Points

1. Custom Templates: Override autocomplete.html.twig to modify the dropdown UI (e.g., add icons).
2. Async Data: Extend AbstractApi to fetch data from external APIs (e.g., REST clients).
3. Permissions: Add security checks in createFilteredQueryBuilder() (e.g., ->andWhere('u.role = :role')).
4. Debouncing: Adjust search delay via JavaScript (override the bundle’s assets).

Performance Quirks

• Large Datasets: Paginate results in createFilteredQueryBuilder():

  ->setMaxResults(20)
  

• N+1 Queries: Fetch related entities (e.g., user.department) in the same query to avoid lazy-loading issues.

Configuration Notes

• Symfony 6+: The bundle requires Symfony 6.0+. Use make:autocomplete (if available) to scaffold APIs.
• Doctrine ORM: Only supports Doctrine ORM (not ODM or other databases). For MongoDB, create a custom adapter.