Pagerfanta Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require babdev/pagerfanta-bundle

Ensure the bundle is enabled in config/bundles.php (auto-enabled in Symfony 4+).

2. First Use Case: Create a paginated query in a controller:

   use Pagerfanta\Doctrine\ORM\QueryAdapter;
   use Pagerfanta\Pagerfanta;
   
   $queryBuilder = $entityManager->getRepository(Entity::class)->createQueryBuilder('e');
   $pagerfanta = new Pagerfanta(new QueryAdapter($queryBuilder));
   return $this->render('template.html.twig', ['pager' => $pagerfanta]);
   

3. Render in Twig:

   {{ pagerfanta(pager) }}
   

   This auto-generates pagination links using the default view.

Implementation Patterns

Common Workflows

1. API Responses: Serialize Pagerfanta directly in controllers:

   return $this->json($pagerfanta, context: ['groups' => ['api']]);
   

   Outputs structured JSON with items and pagination metadata.

2. Custom Views: Define reusable views in config/services.yaml:

   services:
       pagerfanta.view.custom:
           class: Pagerfanta\View\OptionableView
           arguments:
               - '@pagerfanta.view.default'
               - { proximity: 3, max_links: 5 }
           tags: { name: pagerfanta.view, alias: custom }
   

   Use in Twig: {{ pagerfanta(pager, 'custom') }}.

3. Dynamic Route Parameters: Override the default page parameter:

   {{ pagerfanta(pager, 'default', { pageParameter: '[custom_page]' }) }}
   

4. Doctrine Integration: Use QueryAdapter for Doctrine ORM:

   $adapter = new QueryAdapter($queryBuilder, $fetchJoinCollection = false);
   $pagerfanta = new Pagerfanta($adapter);
   

5. Custom Route Generation: Replace the default route generator factory:

   services:
       pagerfanta.route_generator_factory:
           class: App\RouteGenerator\CustomRouteGeneratorFactory
   

Integration Tips

• Twig Extensions: Leverage pagerfanta() for seamless pagination rendering.
• Serializer Groups: Use groups in serialization context for API responses:

  return $this->json($pagerfanta, context: ['groups' => ['pagination']]);
  

• Configuration: Centralize settings in config/packages/babdev_pagerfanta.yaml:

  babdev_pagerfanta:
      default_view: custom
      default_twig_template: '@App/pagination.html.twig'
  

Gotchas and Tips

Pitfalls

1. Route Parameter Naming:

   • Forgetting to wrap custom route parameters in brackets ([param]) breaks URL generation.
   • Example: pageParameter: '[page]' (correct) vs. pageParameter: 'page' (fails).

2. Serialization Quirks:

   • Nested entities may require explicit serialization groups:

     return $this->json($pagerfanta, context: ['groups' => ['api', 'pagination']]);
     

   • Use pagerfanta_preserve_keys context for array key preservation:

     return $this->json($pagerfanta, context: ['pagerfanta_preserve_keys' => true]);
     

3. Exception Handling:

   • Default behavior converts NotValidCurrentPageException to HTTP 404. Disable with:

     babdev_pagerfanta:
         exceptions_strategy:
             not_valid_current_page: custom
     

4. View Caching:

   • Custom views must be tagged with pagerfanta.view; otherwise, they won’t register.
   • Avoid public services for views—use the ViewFactoryInterface to retrieve them.

Debugging Tips

• Check Registered Views: Dump available views in a controller:

  $viewFactory = $this->container->get('pagerfanta.view_factory');
  dump($viewFactory->getViewNames());
  

• Validate Route Generation: Test route generation manually:

  $routeGenerator = $this->container->get('pagerfanta.route_generator_factory')->create();
  $url = $routeGenerator->generate('app_route_name', ['page' => 2]);
  

• Twig Debugging: Override the Twig extension temporarily to debug:

  $twig->addExtension(new \BabDev\PagerfantaBundle\Twig\PagerfantaExtension($viewFactory, $routeGeneratorFactory));
  

Extension Points

1. Custom Views: Extend Pagerfanta\View\ViewInterface and register via pagerfanta.view tag.

2. Route Generators: Implement RouteGeneratorInterface and replace the factory service.

3. Serializer Normalizers: Add custom normalizers for Pagerfanta in Symfony’s serializer configuration:

   framework:
       serializer:
           mappings:
               - App\Serializer\PagerfantaNormalizer
   

4. Event Listeners: Listen for Pagerfanta\Event\PagerfantaEvents to modify pagination behavior dynamically.

---