Bsky Jqueryautocomplete Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bzoote/bsky-jqueryautocomplete-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Bzoote\BSkyJQueryAutoCompleteBundle\BSkyJQueryAutoCompleteBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Override default settings in config/packages/bzoote_bsky_jquery_autocomplete.yaml:

   bsky_jquery_autocomplete:
       endpoint: '/api/autocomplete'  # Your API endpoint
       min_length: 2                  # Minimum characters to trigger search
       delay: 300                     # Delay in ms before triggering search
   

3. First Use Case: Simple Autocomplete Field In a Twig template:

   {{ bsky_jquery_autocomplete({
       name: 'search',
       source: path('app_autocomplete_source'),
       placeholder: 'Search...'
   }) }}
   

   Create a controller route (app_autocomplete_source) returning JSON:

   // src/Controller/AutocompleteController.php
   use Symfony\Component\HttpFoundation\JsonResponse;
   
   class AutocompleteController extends AbstractController {
       public function source(Request $request): JsonResponse {
           $term = $request->query->get('term');
           $results = $this->fetchResults($term); // Your logic here
           return $this->json($results);
       }
   }
   

Implementation Patterns

Common Workflows

1. Dynamic Data Sources Use dependency injection to fetch data from services:

   // src/Service/UserSearchService.php
   class UserSearchService {
       public function search(string $term): array {
           return $this->entityManager->getRepository(User::class)
               ->createQueryBuilder('u')
               ->where('u.name LIKE :term')
               ->setParameter('term', "%$term%")
               ->getQuery()
               ->getResult();
       }
   }
   

   Inject into controller:

   public function source(Request $request, UserSearchService $searchService) {
       $term = $request->query->get('term');
       $results = $searchService->search($term);
       return $this->json(array_map(fn($user) => [
           'id' => $user->getId(),
           'label' => $user->getName(),
           'value' => $user->getEmail()
       ], $results));
   }
   

2. Custom Templates Override the default Twig template by creating: templates/bsky_jquery_autocomplete/default.html.twig

   <input type="text" name="{{ name }}" class="autocomplete-input"
          data-source="{{ source }}"
          data-min-length="{{ min_length }}"
          data-delay="{{ delay }}">
   

3. Integration with Forms Use with Symfony Forms:

   $builder->add('search', TextType::class, [
       'attr' => [
           'class' => 'autocomplete-field',
           'data-source' => $this->generateUrl('app_autocomplete_source'),
       ],
   ]);
   

4. Pagination Support Modify the controller to handle pagination:

   public function source(Request $request): JsonResponse {
       $term = $request->query->get('term');
       $page = $request->query->getInt('page', 1);
       $results = $this->searchService->search($term, $page);
       return $this->json([
           'results' => $results['items'],
           'pagination' => [
               'total' => $results['total'],
               'page' => $page,
               'per_page' => $results['per_page'],
           ]
       ]);
   }
   

   Update Twig to handle pagination:

   {{ bsky_jquery_autocomplete({
       name: 'search',
       source: path('app_autocomplete_source'),
       pagination: true
   }) }}
   

Gotchas and Tips

Common Pitfalls

1. CORS Issues If using AJAX from a different domain, ensure:

   • Your API endpoint has proper CORS headers (Access-Control-Allow-Origin).
   • Use fetch or axios with credentials if needed.

2. Case Sensitivity Default behavior may be case-sensitive. Normalize terms:

   $term = mb_strtolower($request->query->get('term'));
   

3. Rate Limiting Unbounded requests can overwhelm your API. Implement:

   • Database-level rate limiting.
   • Cache results (e.g., Redis) for frequent queries.

4. Template Overrides Forgetting to clear cache after customizing templates:

   php bin/console cache:clear
   

Debugging Tips

1. Check Network Requests Use browser dev tools (Network tab) to verify:

   • The correct endpoint is being called.
   • Request payload matches expectations (term, page, etc.).
   • Response format is valid JSON.

2. Log Raw Data Add logging in your controller:

   $this->logger->info('Autocomplete request', [
       'term' => $term,
       'query' => $request->query->all(),
   ]);
   

3. Validate JSON Response Ensure responses match the expected format:

   [
       {
           "id": "1",
           "label": "John Doe",
           "value": "john@example.com"
       }
   ]
   

   Missing label or value will break rendering.

Extension Points

1. Custom Matching Logic Extend the bundle by creating a custom service:

   // src/Service/CustomAutocompleteService.php
   class CustomAutocompleteService {
       public function match(string $term, array $items): array {
           return array_filter($items, fn($item) =>
               stripos($item['name'], $term) !== false ||
               stripos($item['email'], $term) !== false
           );
       }
   }
   

2. Event Listeners Listen for autocomplete events (if the bundle supports them):

   // config/services.yaml
   services:
       App\EventListener\AutocompleteListener:
           tags:
               - { name: kernel.event_listener, event: bsky.autocomplete.query, method: onQuery }
   

3. Asset Customization Override CSS/JS by publishing assets:

   php bin/console assets:install
   

   Then customize:

   • public/bundles/bskyjqueryautocomplete/
   • Override via twig.config or custom bundles.

4. Symfony UX Integration Combine with Symfony UX for modern JavaScript:

   {{ bsky_jquery_autocomplete({
       name: 'search',
       source: path('app_autocomplete_source'),
       ux: true  # Enable if bundle supports Symfony UX
   }) }}