Skip to content

Feature Implementation Plan: Add Pagination to Varieties and Processing Methods

📋 Todo Checklist

  • [ ] Add pagination to the /api/varieties endpoint.
  • [ ] Add pagination to the /api/processing-methods endpoint.
  • [ ] Update the VarietyRepository to support pagination.
  • [ ] Update the ProcessingMethodRepository to support pagination.
  • [ ] Update OpenAPI documentation for both endpoints.
  • [ ] Write unit and integration tests for the new pagination logic.
  • [ ] Final Review and Testing

🔍 Analysis & Investigation

Codebase Structure

  • Endpoints: The plan targets two endpoints: /api/varieties (in VarietyController) and /api/processing-methods (in ProcessingMethodController).
  • Repositories: The corresponding repositories (VarietyRepository and ProcessingMethodRepository) will be modified to handle paginated queries.

Current Architecture

Both endpoints currently fetch all results from their respective repository methods and return them as a flat JSON array. The plan is to introduce a consistent pagination structure that is already in use in other parts of the API (e.g., /api/locations/regions). This involves: 1. Accepting page and limit query parameters in the controller. 2. Passing limit and offset to the repository. 3. Using Doctrine's Paginator in the repository to fetch the data. 4. Wrapping the response in a structure that includes the items and pagination metadata.

Dependencies & Integration Points

  • NelmioApiDocBundle: The OpenAPI annotations for both endpoints will be updated to document the new page and limit parameters and the new paginated response structure.
  • Doctrine ORM: Doctrine's Paginator class will be used to implement the pagination logic efficiently.

Considerations & Challenges

  • Breaking Change: This is a breaking change for both endpoints. The response format will change from a simple array [] to an object {"items": [], "pagination": {}}. This will require coordination with the frontend team.
  • Consistency: The implementation should be consistent with other paginated endpoints in the application to ensure a predictable API.

📝 Implementation Plan

Prerequisites

  • No new external dependencies are required.

Step-by-Step Implementation

  1. Paginate the Varieties Endpoint

    • Files to modify: src/Controller/Api/VarietyController.php, src/Repository/VarietyRepository.php
    • VarietyController.php Changes:
      • In getVarieties, accept page and limit query parameters with default values.
      • Calculate the offset.
      • Call a new repository method findWithFiltersAndPagination, passing the filters, limit, and offset.
      • Construct the paginated JSON response, wrapping the results in an items array and adding a pagination object.
      • Update the #[OA\Get] and #[OA\Parameter] annotations to reflect the new parameters and response structure.
    • VarietyRepository.php Changes:
      • Create a new method findWithFiltersAndPagination(array $criteria = [], int $limit = 20, int $offset = 0): Paginator.
      • Move the query builder logic from the existing findWithFilters method into this new one.
      • Apply the setMaxResults($limit) and setFirstResult($offset) methods to the query builder.
      • Return a new Paginator object.
      • Keep the old findWithFilters method for internal use or deprecate it if it's no longer needed.

  2. Paginate the Processing Methods Endpoint

    • Files to modify: src/Controller/Api/ProcessingMethodController.php, src/Repository/ProcessingMethodRepository.php
    • ProcessingMethodController.php Changes:
      • In getProcessingMethods, accept page and limit parameters.
      • Calculate the offset.
      • Call a new repository method findByFiltersWithPagination, passing the search term, limit, and offset.
      • Construct the paginated JSON response.
      • Update the #[OA\Get] and #[OA\Parameter] annotations.
    • ProcessingMethodRepository.php Changes:
      • Create a new method findByFiltersWithPagination(?string $search = null, int $limit = 20, int $offset = 0): Paginator.
      • Create a query builder that can handle an optional search term.
      • Apply pagination using setMaxResults and setFirstResult.
      • Return a new Paginator object.

Testing Strategy

  • Unit Tests:
    • Write unit tests for the new findWithFiltersAndPagination method in VarietyRepository.
    • Write unit tests for the new findByFiltersWithPagination method in ProcessingMethodRepository.
  • Integration Tests:
    • Update the integration tests for /api/varieties to check for the new paginated response structure. Test the page and limit parameters.
    • Write new integration tests for /api/processing-methods to verify the pagination and the new response structure.
    • For both endpoints, ensure that existing filters (like search) continue to work correctly with pagination.

🎯 Success Criteria

  • The /api/varieties endpoint returns a paginated list of varieties.
  • The /api/processing-methods endpoint returns a paginated list of processing methods.
  • Both endpoints accept page and limit query parameters.
  • The response format for both endpoints is {"items": [...], "pagination": {...}}.
  • The OpenAPI documentation is updated for both endpoints.
  • All changes are covered by tests.