Download the PHP package ekrouzek/pagination-filters-bundle without Composer

Pagination and filters bundle

Symfony bundle that allows you to set paging, filtering and sorting for selected API endpoints.

1. Installation
2. Implementation
3. Usage
4. Testing

Installation

1. Download the bundle

To download the most up-to-date stable version of this bundle, open a command console, navigate to your project directory, and execute the following command:

2. Enable the bundle

If Flex is being used, the bundle will be automatically enabled. However, if Flex is not being used, manual enabling of the bundle is required by adding the following line to the config/bundles.php file in your project.

Implementation

Usage is shown on an example GET endpoint to get all the courses.

1. Header and ParamFetcher

First, it is necessary to specify the query parameters that we expect for the method:

Then you also need to add ParamFetcher to the function parameters:

2. Definition of filters

Subsequently, it is enough to add the definition of which data can be filtered and sorted according to which at the same time to the given method: addNumberField(), addTextField(), addDatetimeField(), addBooleanField(), addUuidField() methods are available. The first parameter of these functions is the key that will be presented to the outside - that is, which can be entered into the filter from the outside. The second parameter specifies to which attribute it is mapped in the specified DQL query (more below).

So for example:

3. Getting the QueryBuilder and the result

Instead of the already obtained result, it is necessary to pass the DQL QueryBuilder for evaluation. It is therefore necessary to create your own method in the repository for obtaining the query. The idea is the same as if you were to create your own method in the repository, however you don't call ->getQuery()->getResult() at the end, but you pass directly the QueryBuilder.

So for example:

Finally, you only create a method in the corresponding Service, which transfers the result of this method in the repository to the controller. To get the final result of the query, just call ->getPaginatedData($query) in the controller:

4. Sending the result

So the result just needs to be serialized and sent. To send the result with the _pagination header, just call the defined sendPaginatedResponse() method, which wraps the serialized data with a header with pagination information:

If you don't use FOSRestBundle's View and want to serialize the response yourself, call getPaginatedResponseData() instead to get the same _pagination/items structure as a plain array:

Usage

To use paging, filtering and paging, just add the corresponding GET parameters to the HTTP request.

Paging

• The page parameter can be used to specify how many pages from the server you want to return.
• The itemsPerPage parameter can be used to specify how many items you want on one page.

Filtering

• Filtering takes place via the filter parameter.
• The filter must consist of individual expressions. One expression looks like this: <method>:<field>:<value>.
• The method in the expression can be one of the following: eq, neq, like, not-like, lt, lte, gt, gte, in, not-in.
• For in and not-in, the value is a comma-separated list of values, e.g. in:id:1,2,3.
• Expressions can be combined into more complex constructions using logical conjunctions & (AND) and | (OR).
• You can also use parentheses in expressions: ( and ).
• So the filter can look, for example, like this:
  • ?filter=eq:id:1
  • ?filter=(eq:id:1 & like:name:"test") | gt:created:"2020-01-01 00:00:00"
  • ?filter=in:id:1,2,3
  • ?filter=not-in:name:"foo","bar"

Shifting

• Sorting takes place via the sort parameter.
• Can currently only be sorted by one attribute.
• The sort expression must look like this: <field>:[asc,desc].
• Sorting can therefore look, for example, like this:
  • ?sort=id:asc
  • ?sort=created:desc

Testing

Tests run via PHPUnit and don't need a Symfony application to run against — the filter/sort tests build a real Doctrine QueryBuilder against an in-memory SQLite database.

You don't need PHP or Composer installed locally; a Docker Compose setup is provided instead. From the project root:

The same composer test and composer phpstan commands also run in CI (see .github/workflows/ci.yml) before a tagged release is published to Packagist.