Download the PHP package check24/apitk-url-bundle without Composer
On this page you can find all versions of the php package check24/apitk-url-bundle. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download check24/apitk-url-bundle
More information about check24/apitk-url-bundle
Files in check24/apitk-url-bundle
Package apitk-url-bundle
Short Description This bundle provides filter, sorting and pagination for RESTful API's
License MIT
Informations about the package apitk-url-bundle
apitk-url-bundle: Filter, Sorting and Pagination for RESTful API's
Installation
Install the package via composer:
Usage
Defining possible filers, sortings and pagination
Filtering
You can specify in the annotations of the action, which fields should be filterable by the client:
Limit the possibilities for the user with the allowedComparisons
and enum
option.
If you want to use the built in query builder applier and the entity field name differs from the
filter field name (f.e. because it's a field from a joined tabled with an alias) use the
queryBuilderName
option.
The client can now call your API endpoint with filter options like
GET /v1/users?filter[created][gt]=2018-01-01&filter[country][in]=DE,AT
. If the client specified
invalid filters (fields or comparisons you didn't configure/allow), the client will get a 400
response.
You can also use route parameters for filtering input. Just declare the filter with the same name the placeholder in the route is named:
Sorting
You can specify in the annotations of the action, which fields should be sortable by the client:
Limit the possibilities for the user with the allowedDirections
option (f.e. if you only want to
support ascending sorting).
If you want to use the built in query builder applier and the entity field name differs from the
sort field name (f.e. because it's a field from a joined tabled with an alias) use the
queryBuilderName
option.
The client can now call your API endpoint with sort options like
GET /v1/users?sort[zipcode]=asc&sort[username]=desc
. If the client specified invalid sorts
(fields or directions you didn't configure/allow), the client will get a 400 response.
Pagination
You can specify in the annotations of the action, if the result should be paginatable by the client:
If you want to limit the client, how many items per page he gets, you can specify the
maxEntries
option. But please only add one Pagination
annotation (not like in the example
above).
The client can now call your API endpoint with the limit option like
GET /v1/users?limit=10
(get the first 10 entries) or GET /v1/users?limit=30,10
(get the
10 entries with an offset of 30 (=4th page)). If the client tries to paginate when it isn't
enabled by you or he wants to get more items per page than specified by you, the client will
get a 400 response.
Also a new header x-apitk-pagination-total
is sent in the response containing the total
amount of entries, so the client can adjust his pagination buttons.
Accessing client input
Autoloading array through param converter
You can automatically get the entity result array of all your filters in the correct order and pagination subset easily injected into your action.
First set your default repository in your doctrine.yaml
to our ApiToolkitRepository
:
For all your custom repositories, extend them from the ApiToolkitRepository
(or if you want them to be injectable, from ApiToolkitServiceRepository
, which extends from the ServiceEntityRepository
, so be sure to implement the constructor the right way) so they also get the needed functionality.
After that, add a @ApiTK\Result
annotation to your controller action. The action parameter
will automatically gets filled with the filtered, sorted and paginated result set of the
given entity's repository:
If you need to filter/sort for fields in a joined entity, just define your own
findByRequest()
method in the custom entity's repository:
If you need to add different methods to your repository, that can be executed by the
Result
annotation, than you can add the methodName="findBySomethingElse"
parameter
to your annotation. It will then look for this method in your repository instead of
the default findByResult()
method. Be sure to accept as the sole parameter the ApiService
.
As a result, this is also possible:
Note: if the paginator was enabled in your annotations, the query will get
executed by the applyToQueryBuilder()
method in your repository to determine the
total count. Be sure to call the method at the end, after building the rest of your query.
You can specify the entity manager by adding a entityManager="foobar"
to your
annotation, if you need to use another entity manager / connection than the default one.
Manually accessing
If you have to implement custom logic with filtering, sorting and pagination,
you can also inject the ApiService
and use its methods:
Implementing only some filters manually
In case you have some "virtual" fields that need some custom logic, you can use applyToQueryBuilder and
still define your field by hand.
Let's say you want to implement a search parameter. This search looks into username and email.
For your parameter to be available, you need to register a new Filter
field. It is required to set
autoApply=false
for this filter, because there's no "search" field on the Entity and we want to assemble this
part of the query on our own.
applyToQueryBuilder
will skip our autoApply=false
field, so we can add it ourselves.
Important: When using also the paginator, call the $apiService->applyToQueryBuilder()
method AFTER your manual filtering, so the paginator can build the total count header on the filtered result. Otherwise you get incorrect values in your header.
Implementing a sort manually
Same as with manual filter properties, you can implement manual sorting like shown above:
For more advanced purposes, see refer to the "Manually accessing" section above.
Documentation
The defined filers, sorts and pagination will automatically get added to the NelmioApiDoc output (aka Swagger UI). You don't have to worry about that.
All versions of apitk-url-bundle with dependencies
symfony/config Version >=5.3 <6.0
symfony/dependency-injection Version >=5.3 <6.0
symfony/http-kernel Version >=5.3 <6.0
symfony/framework-bundle Version >=5.3 <6.0
doctrine/annotations Version ^1.8
nelmio/api-doc-bundle Version ^3.4
sensio/framework-extra-bundle Version ^5.1 || ^6.0
check24/apitk-common-bundle Version ^2.2 || ^3.0
check24/apitk-header-bundle Version ^2.2 || ^3.0