Skip to content

Feature Implementation Plan: Update Regions and Varieties Filters

📋 Todo Checklist

  • [ ] Update the /api/locations/regions endpoint to accept countryIds[].
  • [ ] Update the RegionRepository to filter by multiple country IDs.
  • [ ] Update the /api/varieties endpoint to accept speciesIds[].
  • [ ] Update the VarietyRepository to filter by multiple species IDs.
  • [ ] Update OpenAPI documentation for both endpoints.
  • [ ] Write unit and integration tests for the new filtering logic.
  • [ ] Final Review and Testing

🔍 Analysis & Investigation

Codebase Structure

  • Regions Endpoint: The logic is handled by src/Controller/Api/LocationController.php and src/Repository/RegionRepository.php. The controller is responsible for parsing request parameters, and the repository handles the database query.
  • Varieties Endpoint: The logic is handled by src/Controller/Api/VarietyController.php and src/Repository/VarietyRepository.php. The structure is similar to the regions endpoint.

Current Architecture

The API follows a consistent pattern: controllers receive HTTP requests, extract filter parameters, and pass them to a repository method that builds and executes a Doctrine query. The plan will follow this existing pattern to ensure consistency. The changes are localized to the respective controllers and repositories, making them low-risk.

Dependencies & Integration Points

  • NelmioApiDocBundle: The OpenAPI annotations in the controllers will need to be updated to reflect the new array-based parameters (countryIds[] and speciesIds[]).
  • Doctrine: The Doctrine Query Builder will be used to add WHERE IN (...) clauses to the repository queries.

Considerations & Challenges

  • API Change: Replacing the single country parameter with countryIds[] is a breaking change for the /api/locations/regions endpoint. This will require coordination with the frontend team.
  • Parameter Validation: The incoming UUIDs in the arrays must be validated to prevent errors and ensure data integrity.

📝 Implementation Plan

Prerequisites

  • No new external dependencies are required.

Step-by-Step Implementation

  1. Update Regions Filtering

    • Files to modify: src/Controller/Api/LocationController.php, src/Repository/RegionRepository.php
    • LocationController.php Changes:
      • In getRegions, remove the logic for the old country parameter.
      • Add logic to check for the new countryIds parameter. If it exists, extract it as an array.
      • Validate that each item in the array is a valid UUID.
      • Pass the array to the regionRepository->findByFiltersWithPagination method.
      • Replace the #[OA\Parameter] for country with one for countryIds[], changing the type to an array of strings and updating the description.
    • RegionRepository.php Changes:
      • In the applyFilters method, replace the country filter logic.
      • If countryIds is present in the $filters array and is not empty, use $qb->andWhere('r.country IN (:countryIds)').
      • Bind the array to the :countryIds parameter.

  2. Update Varieties Filtering

    • Files to modify: src/Controller/Api/VarietyController.php, src/Repository/VarietyRepository.php
    • VarietyController.php Changes:
      • In getVarieties, add logic to check for and extract the new speciesIds array parameter.
      • Validate each UUID in the array.
      • Pass the array to the varietyRepository->findWithFilters method.
      • Add a new #[OA\Parameter] annotation for speciesIds[] to the method's docblock.
    • VarietyRepository.php Changes:
      • In the findWithFilters method, add a new condition.
      • If speciesIds is present in the $criteria array and is not empty, add $qb->andWhere('v.species IN (:speciesIds)').
      • Bind the array to the :speciesIds parameter.

Testing Strategy

  • Unit Tests:
    • Update unit tests for RegionRepository to assert that the correct WHERE IN clause is added when countryIds are provided.
    • Add unit tests for VarietyRepository to assert that the correct WHERE IN clause is added when speciesIds are provided.
  • Integration Tests:
    • Write an integration test for the /api/locations/regions endpoint that passes multiple countryIds and asserts that only regions from those countries are returned.
    • Write an integration test for the /api/varieties endpoint that passes multiple speciesIds and asserts that only varieties of those species are returned.
    • Ensure that the search parameter continues to work in conjunction with the new array-based filters for both endpoints.

🎯 Success Criteria

  • The /api/locations/regions endpoint correctly filters regions by an array of country IDs.
  • The /api/varieties endpoint correctly filters varieties by an array of species IDs.
  • The OpenAPI documentation for both endpoints is updated to reflect the new parameters.
  • The new filtering logic is covered by tests.