Porpaginas Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beberlei/porpaginas
   

   Add to composer.json under require-dev if only needed for testing.

2. Basic Usage Import the package and wrap your collection:

   use Beberlei\Porpaginas\Porpaginas;
   
   $results = Model::query()->get();
   $paginated = new Porpaginas($results, 10, $request->page ?? 1);
   

3. First Use Case Replace Laravel’s default pagination with a unified interface:

   return response()->json($paginated->toArray());
   

   Outputs consistent structure for both paginated and non-paginated results.

Implementation Patterns

Core Workflows

1. Unified Response Handling

   // Paginated
   $paginated = new Porpaginas($query->paginate(10), 10, $page);
   // Non-paginated
   $nonPaginated = new Porpaginas($query->get(), 10, 1);
   

   Both return identical toArray() output.

2. Customizing Metadata Override default metadata keys:

   $paginated->setMetadataKeys([
       'total' => 'total_items',
       'per_page' => 'items_per_page',
   ]);
   

3. Integration with API Resources

   public function toArray($request)
   {
       return [
           'data' => $this->resource->toArray($request),
           'meta' => (new Porpaginas($this->collection, 10))->toArray()['meta'],
       ];
   }
   

4. Dynamic Page Size

   $pageSize = $request->input('per_page', 10);
   $paginated = new Porpaginas($query->paginate($pageSize), $pageSize, $request->page);
   

Advanced Patterns

• Hybrid Pagination: Mix paginated and non-paginated results in a single response.
• Caching: Cache Porpaginas instances for API responses:

  Cache::remember("paginated_{$page}", 60, fn() => new Porpaginas($results, 10, $page));
  

Gotchas and Tips

Common Pitfalls

1. Page Validation

   • Always validate $page and $perPage to avoid SQL errors:

     $page = max(1, (int)$request->page);
     $perPage = min(100, max(1, (int)$request->per_page));
     

2. Collection vs. Paginator

   • Porpaginas expects a Collection or LengthAwarePaginator. Pass raw QueryBuilder results directly:

     $results = Model::query()->get(); // Collection
     $paginated = new Porpaginas($results, 10, 1);
     

3. Metadata Overrides

   • Custom metadata keys must match the structure expected by your frontend. Test thoroughly.

Debugging Tips

• Empty Results: Check if $total is null or 0 in metadata. Ensure your query returns a Collection/Paginator.
• Offset Calculation: For non-standard pagination (e.g., cursor-based), extend Porpaginas:

  class CustomPorpaginas extends Porpaginas {
      public function getOffset(): int { return 0; } // Override for cursor-based
  }
  

Extension Points

1. Custom Metadata Add extra metadata dynamically:

   $paginated->setMetadata('filters', $request->query());
   

2. Serialization Override toArray() for custom JSON structures:

   public function toArray(): array {
       return [
           'items' => $this->items,
           'pagination' => $this->getMeta(),
       ];
   }
   

3. Testing Mock Porpaginas in tests:

   $mock = Mockery::mock(Porpaginas::class)
       ->shouldReceive('toArray')
       ->andReturn(['data' => [], 'meta' => []])
       ->getMock();