Add new UX Pagination component

[smnandre]

Q	A
Bug fix?	no
New feature?	yes
Deprecations?	no
Documentation?	yes
Issues	Fix #...
License	MIT

This PR adds symfony/ux-pagination, an experimental bundle that provides
cursor and numbered pagination behind one request-aware PaginatorInterface
service.

PHP owns the query. Twig renders accessible navigation. The browser
follows ordinary links: no JavaScript, no Stimulus, no Turbo required.

$pagination = $paginator
    ->cursor($events->createQueryBuilder('event'))
    ->orderBy(['createdAt', 'id'], 'DESC')
    ->perPage(20)
    ->paginate();

{% for event in pagination %}
    <article>{{ event.name }}</article>
{% endfor %}

{{ ux_pagination(pagination) }}

What is included

• One PaginatorInterface entry point: paginate(), query(), cursor(),
  and fromCallbacks(), plus named paginator profiles injectable by
  argument name, #[Target], or service id.
• Three strategies: numbered, lookahead (no COUNT query), and bidirectional
  cursor.
• Adapters for arrays, Doctrine ORM 3, Doctrine DBAL 4.4+, and callbacks.
  Custom adapters register through one interface and a service tag.
• Immutable builders for page size, ordering, and URL composition: route,
  path, query-string policy, fragment, and lazy application-provided totals.
• The ux_pagination() Twig function and the <twig:ux:pagination>
  component, with default, Bootstrap, and Tailwind themes, structural
  blocks, validated attribute hooks, and accessible markup: nav landmark,
  aria-current, rel prev/next, translated labels.
• Translations in ten locales. Message ids are natural English sentences,
  like core validators: without symfony/translation, the identity
  translator renders readable English, %count% pluralization included.
• JSON serialization with stable prev/next links.
• Optional LiveComponent integration through ComponentWithPaginationTrait:
  one createPagination() method to implement, real-link fallback, URL
  synchronization that follows the configured page parameter (path mapping
  included), and link URLs that stay on the page route during re-renders,
  never on the internal component endpoint.
• Test\PaginatorFactory for deterministic application tests, including
  signed-cursor round trips.

Design decisions reviewers may want to check

• Experimental: the bundle ships under the usual UX experimental notice.
• count($pagination) returns the items on the current page, not the
  total. This matches iteration; getTotalItems() returns the total. The
  method documents it.
• The cursor signing secret defaults to %kernel.secret%, like
  LiveComponent. Offset pagination works without any secret: the codec is a
  lazy proxy that fails only when signing is needed.
• The result interfaces stay small. Serialization shapes (getMetadata(),
  getLinks()) and URL conveniences live on the concrete classes only.
• Cursor tokens are signed, not encrypted: boundary values are readable.

[github-actions]

📊 Packages dist files size difference

Thanks for the PR! Here is the difference in size of the packages dist files between the base branch and the PR.
Please review the changes and make sure they are expected.

File	Before (Size / Gzip)	After (Size / Gzip)
Pagination
style.min.css	Added	1.86 kB / 626 B

[Kocal]

Except minor comments and types-hardening suggestions, it looks fine to me. Symfony will finally have built-in Pagination :D

[Kocal]

Sshipping default styles is indeed super useful, but I'm a little worried about what will happen when users want to make more significant changes to styles. What if users use CSS layers, etc..

This is also a subject of BC.

I'm not sure if we should ship default styles like that or not, what about moving it in a dedicated Flex recipe?

[smnandre]

Having one is like having a default theme, it allows to work out of the box, but this is clearly documented to be something user would need/want to override or probably even rewrite themselves...

Here it's really about "plug and play and basic working behaviour".

Problem with a recipe is also it cannot differenciate "first install" and update, so it would bring the same problems (if not worst, as we cannot control we does or does not its recipe:updates out there)...

Maybe though this is something we can solve later on, providing URL / commands to get theme from ux toolkit or something ?

[Kocal]

Does symfony.com documentation supports diagram? Like mermaid syntax?

[smnandre]

You really should watch the repository I suggested you to watch 😆

[Kocal]

Remember to ping Fabien for creating the repo on GitHub/Packagist

[seb-jean]

In the three templates under src/Pagination/templates/theme/*.html.twig, some variables are written in camelCase (linkClass, userClass, rootAttributes, userNavigationClass and navigationAttributes) These should use snake_case instead (link_class, user_class, root_attributes, user_navigation_class, navigation_attributes), to stay consistent with the usual Twig naming convention : https://twig.symfony.com/doc/3.x/coding_standards.html.

Example:

{% set linkClass = 'px-3 py-2 text-sm font-medium rounded-lg text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-800 border border-gray-300 dark:border-gray-600 hover:bg-gray-50 dark:hover:bg-gray-700 focus:ring-2 focus:ring-blue-500 transition-colors duration-150' %}
{% set userClass = attributes.class|default('') %}
{% set rootAttributes = {
    'aria-label': 'Pagination'|trans({}, 'UXPaginationBundle'),
}|merge(attributes)|merge({
    class: ('ux-pagination-tailwind ' ~ userClass)|trim,
}) %}
{% set userNavigationClass = navigationAttributes.class|default('') %}
{% set navigationAttributes = navigationAttributes|merge({
    class: ('flex flex-wrap items-center justify-center gap-1 sm:gap-2 ' ~ userNavigationClass)|trim,
}) %}

[ker0x]

Doctrine 3.7 will be release with a new CursorPaginator

[seb-jean]

Doctrine 3.7 will be release with a new CursorPaginator

Yes, but there's currently a blocking issue for the release of cursor-based pagination in Doctrine ORM 3.7.

[smnandre]

Doctrine 3.7 will be release with a new CursorPaginator

Great, and as I see it some of this PR API inspired some changes on Doctrine PR.. and this is why I love Open Source ! 🤝

[Kocal]

LGTM, waiting for your PR on ux.symfony.com :D

[smnandre]

Thank you very much for the review @Kocal !