Download the PHP package knplabs/knp-paginator-bundle without Composer

Intro to KnpPaginatorBundle

Friendly Symfony paginator to paginate everything

Generally this bundle is based on Knp Pager component. This component introduces a different way of pagination handling. You can read more about the internal logic on the given documentation link.

Note: Keep knp-components in sync with this bundle. If you want to use older version of KnpPaginatorBundle - use v3.0 or v4.X tags in the repository which is suitable to paginate ODM MongoDB and ORM 2.0 queries

Latest updates

For notes about the latest changes please read CHANGELOG, for required changes in your code please read UPGRADE chapter of the documentation.

Requirements:

• Knp Pager component >=2.0.
• KnpPaginatorBundle's master is compatible with Symfony >=4.4 versions.
• Twig >=2.0 version is required if you use the Twig templating engine.

Features:

• Does not require initializing specific adapters.
• Can be customized in any way needed, etc.: pagination view, event subscribers.
• Possibility to add custom filtering, sorting functionality depending on request parameters.
• Separation of concerns, paginator is responsible for generating the pagination view only, pagination view - for representation purposes.

Note: using multiple paginators requires setting the alias in order to keep non conflicting parameters.

More detailed documentation:

• Creating custom pagination subscribers
• Extending pagination class (todo, may require some refactoring)
• Customizing view templates and arguments

Installation and configuration:

Pretty simple with Composer, run

Add PaginatorBundle to your application kernel

If you don't use flex (you should), you need to manually enable bundle:

Configuration example

You can configure default query parameter names and templates

YAML:

PHP:

Additional pagination templates

That could be used out of the box in knp_paginator.template.pagination key:

• @KnpPaginator/Pagination/sliding.html.twig (by default)
• @KnpPaginator/Pagination/bootstrap_v5_pagination.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_pagination.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v3_pagination.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_pagination.html.twig
• @KnpPaginator/Pagination/foundation_v6_pagination.html.twig
• @KnpPaginator/Pagination/foundation_v5_pagination.html.twig
• @KnpPaginator/Pagination/bulma_pagination.html.twig
• @KnpPaginator/Pagination/semantic_ui_pagination.html.twig
• @KnpPaginator/Pagination/materialize_pagination.html.twig
• @KnpPaginator/Pagination/tailwindcss_pagination.html.twig
• @KnpPaginator/Pagination/uikit_v3_pagination.html.twig

Sample rel link tag template

That could be used out of the box in knp_paginator.template.rel_links key:

• @KnpPaginator/Pagination/rel_links.html.twig (by default)

Additional sortable templates

That could be used out of the box in knp_paginator.template.sortable key:

• @KnpPaginator/Pagination/sortable_link.html.twig (by default)
• @KnpPaginator/Pagination/bootstrap_v5_bi_sortable_link.html.twig
• @KnpPaginator/Pagination/bootstrap_v5_fa_sortable_link.html.twig
• @KnpPaginator/Pagination/bootstrap_v5_md_sortable_link.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v3_sortable_link.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_font_awesome_sortable_link.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_material_design_icons_sortable_link.html.twig
• @KnpPaginator/Pagination/semantic_ui_sortable_link.html.twig
• @KnpPaginator/Pagination/uikit_v3_sortable.html.twig

Additional filtration templates

That could be used out of the box in knp_paginator.template.filtration key:

• @KnpPaginator/Pagination/filtration.html.twig (by default)
• @KnpPaginator/Pagination/bootstrap_v5_filtration.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_filtration.html.twig

Usage examples:

Controller

Currently paginator can paginate:

• array
• Doctrine\DBAL\Query\QueryBuilder
• Doctrine\ORM\Query
• Doctrine\ORM\QueryBuilder
• Doctrine\ODM\MongoDB\Query\Query
• Doctrine\ODM\MongoDB\Query\Builder
• Doctrine\ODM\PHPCR\Query\Query
• Doctrine\ODM\PHPCR\Query\Builder\QueryBuilder
• Doctrine\Common\Collection\ArrayCollection - any Doctrine relation collection including
• ModelCriteria - Propel ORM query
• array with Solarium_Client and Solarium_Query_Select as elements

View

In <head>:

In <body>:

Translation in view

For translating the following text:

• %foo% name with translation key table_header_name. The translation is in the domain messages.
• {0} No author|{1} Author|[2,Inf] Authors with translation key table_header_author. The translation is in the domain messages.

translationCount and translationParameters can be combined.

Adding translation files

You can also override translations by creating a translation file in the following name format: domain.locale.format. So, to create a translation file for this bundle you need to create for instance KnpPaginatorBundle.tr.yaml file under project_root/translations/ and add your translations there:

If you set default translation for configuration accordingly:

Symfony will pick it automatically.

Dependency Injection

You can automatically inject a paginator service into another service by using the knp_paginator.injectable DIC tag. The tag takes one optional argument paginator, which is the ID of the paginator service that should be injected. It defaults to knp_paginator.

The class that receives the KnpPaginator service must implement Knp\Bundle\PaginatorBundle\Definition\PaginatorAwareInterface. If you're too lazy you can also just extend the Knp\Bundle\PaginatorBundle\Definition\PaginatorAware base class.

⚠ Warning using PaginatorAwareInterface is discouraged, and could be removed in a future version. You should not rely on setter injection, but only on proper constructor injection. Using Symfony built-in autowiring mechanism is the suggested way to go.

Lazy service

The knp_paginator service will be created lazily if the package symfony/proxy-manager-bridge is installed.

For more information about lazy services, consult the Symfony documentation on dependency injection.

XML configuration example

Troubleshooting

• Make sure the translator is activated in your Symfony config:

• If your locale is not available, create your own translation file in translations/KnpPaginatorBundle.en.yml (substitute "en" for your own language code if needed). Then add these lines:

• Note that <rel> links are only meaningful when using pagination, they are not relevant to sorting or filtering.

Maintainers

Please read this post first.

This library is maintained by the following people (alphabetically sorted) :

• @garak
• @polc