Doctrine Filter Paginator Laravel Package

Getting Started

Install via Composer: composer require verclam/doctrine-filter-paginator. Since this is the initial v0.0.1 release, start by reading the package's README and source (especially the service provider and paginator class) to understand the exposed API. The first use case is paginating Doctrine query results while preserving active Doctrine filters (e.g., soft‑delete, tenant, or custom SQL filters). Look for a paginator service or trait that wraps Doctrine's Paginator and applies registered filters. A minimal example likely involves injecting the paginator into a controller, passing a QueryBuilder, and rendering results with Laravel's pagination views.

Implementation Patterns

• Controller usage: inject the package's paginator (or resolve it from the container) and call a paginate() method on a Doctrine QueryBuilder. Combine with Laravel's request parameters (page, perPage) for standard pagination.
• Filter integration: register Doctrine filters (e.g., SoftDeleteFilter) in your Doctrine configuration, then use the package's paginator so filters are automatically applied before counting and fetching results. This avoids manually enabling filters per query.
• Custom filters: extend Doctrine's SQLFilter and register it; the paginator should respect the filter's parameters when building the count and limit queries.
• Workflow: define your entity repository/query builder → configure filters (globally or per query) → pass the builder to the paginator → return a paginated response (e.g., LengthAwarePaginator or a Doctrine‑backed paginator instance).
• Integration tips: use alongside laravel-doctrine/orm; ensure the Doctrine EntityManager is available. For API responses, convert the paginator result to a resource collection. If the package provides a Blade directive or JSON structure, leverage it to reduce boilerplate.

Gotchas and Tips

• Early release: v0.0.1 has no documented changelog beyond the commit link, so expect API instability. Pin the version and review source code before relying on it in production.
• Filter state: Doctrine filters are enabled per EntityManager or per query. Verify that the paginator enables filters at the right time—especially for count queries, which may bypass filters if not handled.
• Soft deletes: if using a soft‑delete filter, ensure the paginator's count query also excludes deleted rows; otherwise pagination totals will be wrong.
• Performance: filters can add SQL conditions; test with large datasets. Use $query->setMaxResults() and setFirstResult() carefully when the paginator also manipulates them.
• Debugging: enable Doctrine SQL logging (config/doctrine.php → sql_logger) to inspect the generated count and select queries. Check that filter parameters are bound correctly.
• Config quirks: the package may publish a config file for default page size or filter behaviour—publish it (php artisan vendor:publish) and review defaults. Watch for conflicts with Laravel's own pagination config.
• Extension points: look for interfaces or abstract classes for custom paginators or filter resolvers. If none exist yet, you can extend the package's paginator class and override query-building methods.