List Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require arturdoruch/list-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3).

2. Basic Controller Integration: Create a controller action with a GET route returning an ItemList object:

   use ArturDoruch\ListBundle\ItemList;
   use ArturDoruch\ListBundle\Paginator;
   use ArturDoruch\ListBundle\Request\QueryParameterBag;
   
   public function list(Request $request)
   {
       $parameterBag = new QueryParameterBag($request);
       $items = $this->fetchItems(); // Your data source (array, QueryBuilder, etc.)
       $pagination = Paginator::paginate($items, $parameterBag->getPage(), $parameterBag->getLimit(10));
   
       return [
           'itemList' => new ItemList($pagination)
       ];
   }
   

3. Template Rendering: Use Twig functions to render the list:

   {{ arturdoruch_list_items_and_pagination(itemList.pagination) }}
   

Implementation Patterns

1. Filtering Workflow

• Form Creation: Extend ArturDoruch\ListBundle\Form\FilterType or use FilterType directly in the controller:

  $form = $this->createForm(BookFilterType::class, null, ['method' => 'GET', 'csrf_protection' => false]);
  $form->handleRequest($request);
  

• Criteria Extraction: Pass filtered data to your repository:

  $criteria = $form->isSubmitted() && $form->isValid() ? $form->getData() : [];
  $items = $repository->findBy($criteria);
  

2. Sorting Integration

• Dynamic Sorting: Use QueryParameterBag to extract sort parameters from the request:

  $sort = $parameterBag->getSort(); // Returns ["field" => "order"]
  $items = $repository->findBy([], $sort);
  

• Sort Choice Collection (for dropdowns):

  $sortChoices = new SortChoiceCollection();
  $sortChoices
      ->add('Name (A-Z)', 'name', 'asc')
      ->add('Name (Z-A)', 'name', 'desc');
  return new ItemList($pagination, $form, $sortChoices);
  

3. Pagination Customization

• Override Default Limits:

  $pagination = Paginator::paginate($items, $page, $limit);
  $pagination->setItemLimits([10, 25, 50]); // Custom limits
  

• Configuration: Set global limits in config/packages/arturdoruch_list.yaml:

  arturdoruch_list:
      pagination:
          item_limits: [10, 25, 50]
  

4. AJAX Support

• Partial Rendering: Extend a base template for AJAX requests:

  {% extends app.request.xmlHttpRequest ? '@App/ajax_list.html.twig' : '@App/base.html.twig' %}
  

  Only render the list block for AJAX:

  {% block list %}
      {{ arturdoruch_list_items_and_pagination(itemList.pagination) }}
  {% endblock %}
  

5. Custom Paginators

• Extend for Non-Supported Data Sources: Implement ArturDoruch\ListBundle\Paginator\PaginatorInterface:

  class CustomPaginator implements PaginatorInterface {
      public function paginate($items, $page, $limit) { ... }
  }
  

  Register in config/packages/arturdoruch_list.yaml:

  arturdoruch_list:
      paginators:
          custom: App\Paginator\CustomPaginator
  

Gotchas and Tips

Common Pitfalls

1. CSRF Protection: Filter forms must have csrf_protection: false to work with query parameters.

   $form = $this->createForm(BookFilterType::class, null, ['csrf_protection' => false]);
   

2. Form Name Matters: The filter form’s name (e.g., filter) determines the query parameter prefix for filtering. Use createNamed() to customize:

   $form = $this->createForm(BookFilterType::class, null, ['name' => 'custom_filter']);
   

3. Sorting Conflicts: If sorting fails, ensure your QueryBuilder supports dynamic ordering:

   $qb->orderBy($sort['field'], $sort['order']);
   

4. Pagination Edge Cases:

   • Empty Results: Handle count === 0 in templates to avoid rendering empty tables.
   • Invalid Page/Limit: QueryParameterBag throws exceptions for invalid values. Validate or catch:

     try {
         $page = $parameterBag->getPage();
     } catch (\InvalidArgumentException $e) {
         $page = 1;
     }
     

Debugging Tips

1. Inspect Request Parameters: Dump QueryParameterBag to verify sorting/filtering:

   dump($parameterBag->getSort()); // ["field" => "order"]
   dump($parameterBag->getFilter()); // Filter criteria
   

2. Twig Debugging: Use {{ dump(itemList) }} to inspect the ItemList object structure.

3. JavaScript Integration: For @arturdoruch/list, ensure the JS bundle is properly linked and configured to match the PHP bundle’s settings.

Performance Optimizations

1. Eager-Loading: Use QueryBuilder with join() and addSelect() to avoid N+1 queries:

   $qb->join('b.category', 'c')->addSelect('c');
   

2. Limit Query Complexity: Avoid overly complex WHERE clauses in filters. Use indexed fields where possible.

3. Caching: Cache ItemList objects if data changes infrequently:

   $cacheKey = md5(serialize($criteria));
   $itemList = $cache->get($cacheKey, function() use ($criteria) {
       return new ItemList($pagination);
   });
   

Extension Points

1. Custom Twig Functions: Override or extend Twig functions in your bundle’s compiler pass:

   // src/Twig/ArturDoruchListExtension.php
   class ArturDoruchListExtension extends \Twig_Extension {
       public function getFunctions() {
           return [
               new \Twig_SimpleFunction('custom_list_function', [$this, 'renderCustomList']),
           ];
       }
   }
   

2. Event Listeners: Hook into the bundle’s lifecycle (e.g., modify ItemList before rendering):

   // config/services.yaml
   services:
       App\EventListener\ListListener:
           tags:
               - { name: kernel.event_listener, event: arturdoruch.list.pre_render, method: onPreRender }
   

3. Configuration Overrides: Use environment-specific configs (e.g., config/packages/dev/arturdoruch_list.yaml) to tweak behavior per environment.