Core Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require pagerfanta/core
   

   • No additional configuration is needed for the core package. It provides the foundational API for pagination.

2. First Use Case: Basic Pagination

   use Pagerfanta\Pagerfanta;
   
   // Create a pagerfanta instance with an adapter (e.g., Doctrine, Array, etc.)
   $adapter = new \Pagerfanta\Adapter\ArrayAdapter($yourDataArray);
   $pagerfanta = new Pagerfanta($adapter);
   
   // Configure pagination settings
   $pagerfanta->setMaxPerPage(10); // Items per page
   $pagerfanta->setCurrentPage(1); // Current page
   
   // Get the current page data
   $currentPageData = $pagerfanta->getCurrentPageResults();
   

3. Where to Look First

   • Documentation: Pagerfanta Official Docs (core API is a subset).
   • Adapter Classes: Explore \Pagerfanta\Adapter namespace for data source integrations (e.g., ArrayAdapter, DoctrineORMAdapter).
   • Pagerfanta Class: Core methods like getCurrentPageResults(), setMaxPerPage(), and getNbPages().

Implementation Patterns

Common Workflows

1. Adapter Integration

   • Use adapters to wrap your data source (e.g., Eloquent collections, database results, or arrays).
   • Example with Eloquent:

     use Pagerfanta\Adapter\DoctrineORMAdapter;
     use Doctrine\ORM\EntityManagerInterface;
     
     $em = app(EntityManagerInterface::class);
     $query = $em->createQuery('SELECT u FROM User u');
     $adapter = new DoctrineORMAdapter($query);
     $pagerfanta = new Pagerfanta($adapter);
     

2. Dynamic Pagination in Controllers

   • Pass the current page and max per page from the request:

     $currentPage = $request->get('page', 1);
     $maxPerPage = $request->get('per_page', 10);
     
     $pagerfanta->setMaxPerPage($maxPerPage);
     $pagerfanta->setCurrentPage($currentPage);
     

3. View Integration

   • Pass the pagerfanta instance to a view and use a template (e.g., pagerfanta/twig for Twig or custom Blade logic):

     return view('posts.index', [
         'pagerfanta' => $pagerfanta,
         'posts' => $pagerfanta->getCurrentPageResults()
     ]);
     

4. Lazy Loading with Iterators

   • Use Pagerfanta\Pagerfanta with iterators for large datasets:

     $iterator = new \Pagerfanta\Iterator\CurrentPageIterator($pagerfanta);
     foreach ($iterator as $item) {
         // Process items one page at a time
     }
     

Laravel-Specific Tips

• Service Provider Binding Bind the adapter and pagerfanta in a service provider for reuse:

  $this->app->bind(Pagerfanta::class, function ($app) {
      $adapter = new ArrayAdapter($app['your.data.source']);
      return new Pagerfanta($adapter);
  });
  

• Request-Based Pagination Use Laravel's Request to dynamically set pagination:

  $pagerfanta->setCurrentPage($request->input('page', 1));
  $pagerfanta->setMaxPerPage($request->input('per_page', 15));
  

Gotchas and Tips

Pitfalls

1. Adapter Compatibility

   • Not all adapters support all query types (e.g., DoctrineORMAdapter may not work with DQL COUNT queries in some cases).
   • Fix: Use Pagerfanta\Adapter\DoctrineDBALAdapter for raw SQL queries or ensure your DQL is compatible.

2. Current Page Validation

   • Pagerfanta does not validate setCurrentPage() against getNbPages(). Invalid pages may return empty results.
   • Fix: Clamp the current page:

     $currentPage = max(1, min($pagerfanta->getNbPages(), $request->get('page', 1)));
     $pagerfanta->setCurrentPage($currentPage);
     

3. Memory Issues with Large Datasets

   • Loading all data into an array adapter can cause memory problems.
   • Fix: Use database cursors or streaming adapters (e.g., Pagerfanta\Adapter\CursorAdapter).

4. Zero-Based vs One-Based Indexing

   • Some adapters (e.g., ArrayAdapter) use zero-based indexing internally, while others (e.g., DoctrineORMAdapter) use one-based.
   • Fix: Ensure consistency when calculating offsets/limits.

Debugging Tips

• Check Adapter Counts Verify getNbResults() matches your expected dataset size:

  $adapter = $pagerfanta->getAdapter();
  $totalItems = $adapter->getNbResults();
  

• Log Pagerfanta State Dump the pagerfanta object to debug:

  \Log::debug([
      'current_page' => $pagerfanta->getCurrentPage(),
      'max_per_page' => $pagerfanta->getMaxPerPage(),
      'nb_pages' => $pagerfanta->getNbPages(),
      'nb_results' => $pagerfanta->getNbResults(),
  ]);
  

Extension Points

1. Custom Adapters Extend \Pagerfanta\Adapter\AdapterInterface for new data sources (e.g., API responses, Elasticsearch):

   class ApiAdapter implements AdapterInterface {
       public function getNbResults() { /* ... */ }
       public function getSlice($offset, $length) { /* ... */ }
   }
   

2. Override Pagerfanta Behavior Extend \Pagerfanta\Pagerfanta to add custom logic (e.g., caching, analytics):

   class CustomPagerfanta extends Pagerfanta {
       public function getCachedPage($page) { /* ... */ }
   }
   

3. Integrate with Laravel Collections Use Pagerfanta\Bridge\Doctrine\ORM\QueryAdapter or wrap collections:

   $collection = Post::paginate(10)->getCollection();
   $adapter = new ArrayAdapter($collection->all());
   

Config Quirks

• No Built-in Configuration The core package has no config file. All settings are runtime (e.g., setMaxPerPage()).
  • Workaround: Use Laravel's config to define defaults:

    'pagination' => [
        'default_per_page' => 15,
    ],
    

    Then apply in your code:

    $pagerfanta->setMaxPerPage(config('pagination.default_per_page'));