Merge pull request #809 from KnpLabs/update-alias

add new option to enhance first page link

README.md

@@ -18,7 +18,7 @@ For details regarding changes please read about the [releases](https://github.co
 
 ## Requirements:
 
-- Knp Pager component `>=2.0`.
+- Knp Pager component `>=4.4`.
 - KnpPaginatorBundle's master is compatible with Symfony `>=6.4` versions.
 - Twig `>=3.0` version is required if you use the Twig templating engine.
 
@@ -66,19 +66,23 @@ public function registerBundles()
 
 ### Configuration example
 
-You can configure default query parameter names and templates
+You can configure default query parameter names and templates, and a few other options:
 
 #### YAML:
 ```yaml
 knp_paginator:
+    convert_exception: false            # throw a 404 exception when an invalid page is requested
     page_range: 5                       # number of links shown in the pagination menu (e.g: you have 10 pages, a page_range of 3, on the 5th page you'll see links to page 4, 5, 6)
+    remove_first_page_param: false      # remove the page query parameter from the first page link
     default_options:
         page_name: page                 # page query parameter name
         sort_field_name: sort           # sort field query parameter name
         sort_direction_name: direction  # sort direction query parameter name
         distinct: true                  # ensure distinct results, useful when ORM queries are using GROUP BY statements
         filter_field_name: filterField  # filter field query parameter name
         filter_value_name: filterValue  # filter value query parameter name
+        page_out_of_range: ignore       # ignore, fix, or throwException when the page is out of range
+        default_limit: 10               # default number of items per page
     template:
         pagination: '@KnpPaginator/Pagination/sliding.html.twig'     # sliding pagination controls template
         rel_links: '@KnpPaginator/Pagination/rel_links.html.twig'    # <link rel=...> tags template
@@ -96,14 +100,18 @@ use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigura
 return static function (ContainerConfigurator $configurator): void
 {
     $configurator->extension('knp_paginator', [
+        'convert_exception' => false,             // throw a 404 exception when an invalid page is requested
         'page_range' => 5,                        // number of links shown in the pagination menu (e.g: you have 10 pages, a page_range of 3, on the 5th page you'll see links
+        'remove_first_page_param' => false,       // remove the page query parameter from the first page link
         'default_options' => [
             'page_name' => 'page',                // page query parameter name
             'sort_field_name' => 'sort',          // sort field query parameter name
             'sort_direction_name' => 'direction', // sort direction query parameter name
             'distinct' => true,                   // ensure distinct results, useful when ORM queries are using GROUP BY statements
             'filter_field_name' => 'filterField', // filter field query parameter name
             'filter_value_name' => 'filterValue'  // filter value query parameter name
+            'page_out_of_range' => 'ignore',      // ignore, fix, or throwException when the page is out of range
+            'default_limit' => 10                 // default number of items per page
         ],
         'template' => [
             'pagination' => '@KnpPaginator/Pagination/sliding.html.twig',     // sliding pagination controls template

config/paginator.xml

@@ -56,6 +56,8 @@
 
         <service id="Knp\Bundle\PaginatorBundle\Twig\Extension\PaginationRuntime">
             <argument type="service" id="knp_paginator.helper.processor" />
+            <argument type="string">%knp_paginator.page_name%</argument>
+            <argument>%knp_paginator.remove_first_page_param%</argument>
             <tag name="twig.runtime" />
         </service>
     </services>

src/DependencyInjection/Configuration.php

@@ -55,6 +55,9 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->booleanNode('convert_exception')
                 ->defaultFalse()
                 ->end()
+                ->booleanNode('remove_first_page_param')
+                ->defaultFalse()
+                ->end()
             ->end()
         ;
 

src/DependencyInjection/KnpPaginatorExtension.php

@@ -41,6 +41,8 @@ public function load(array $configs, ContainerBuilder $container): void
         $container->setParameter('knp_paginator.template.sortable', $config['template']['sortable']);
         $container->setParameter('knp_paginator.page_range', $config['page_range']);
         $container->setParameter('knp_paginator.page_limit', $config['page_limit']);
+        $container->setParameter('knp_paginator.page_name', $config['default_options']['page_name']);
+        $container->setParameter('knp_paginator.remove_first_page_param', $config['remove_first_page_param']);
 
         $paginatorDef = $container->getDefinition('knp_paginator');
         $paginatorDef->addMethodCall('setDefaultPaginatorOptions', [[

src/Helper/Processor.php

@@ -15,14 +15,10 @@
  */
 final class Processor
 {
-    private UrlGeneratorInterface $router;
-
-    private TranslatorInterface $translator;
-
-    public function __construct(UrlGeneratorInterface $router, TranslatorInterface $translator)
-    {
-        $this->router = $router;
-        $this->translator = $translator;
+    public function __construct(
+        private readonly UrlGeneratorInterface $router,
+        private readonly TranslatorInterface $translator
+    ) {
     }
 
     /**

src/Pagination/SlidingPagination.php

@@ -16,9 +16,6 @@ final class SlidingPagination extends AbstractPagination implements SlidingPagin
 {
     private ?string $route = null;
 
-    /** @var array<string, mixed> */
-    private array $params;
-
     private int $pageRange = 5;
 
     private ?int $pageLimit = null;
@@ -34,9 +31,8 @@ final class SlidingPagination extends AbstractPagination implements SlidingPagin
     /**
      * @param array<string, mixed> $params
      */
-    public function __construct(array $params)
+    public function __construct(private array $params)
     {
-        $this->params = $params;
     }
 
     public function setUsedRoute(?string $route): void

src/Subscriber/SlidingPaginationSubscriber.php

@@ -15,15 +15,11 @@ final class SlidingPaginationSubscriber implements EventSubscriberInterface
     /** @var array<string, mixed> */
     private array $params = [];
 
-    /** @var array<string, mixed> */
-    private array $options;
-
     /**
      * @param array<string, mixed> $options
      */
-    public function __construct(array $options)
+    public function __construct(private readonly array $options)
     {
-        $this->options = $options;
     }
 
     public function onKernelRequest(RequestEvent $event): void

src/Templating/PaginationHelper.php

@@ -16,14 +16,10 @@
  */
 final class PaginationHelper extends Helper
 {
-    protected PhpEngine $templating;
-
-    protected Processor $processor;
-
-    public function __construct(Processor $processor, PhpEngine $templating)
-    {
-        $this->processor = $processor;
-        $this->templating = $templating;
+    public function __construct(
+        private readonly Processor $processor,
+        private readonly PhpEngine $templating
+    ) {
     }
 
     /**

src/Twig/Extension/PaginationExtension.php

@@ -3,6 +3,7 @@
 namespace Knp\Bundle\PaginatorBundle\Twig\Extension;
 
 use Twig\Extension\AbstractExtension;
+use Twig\TwigFilter;
 use Twig\TwigFunction;
 
 final class PaginationExtension extends AbstractExtension
@@ -16,6 +17,7 @@ public function getFunctions(): array
             new TwigFunction('knp_pagination_rel_links', [PaginationRuntime::class, 'rel_links'], $options),
             new TwigFunction('knp_pagination_sortable', [PaginationRuntime::class, 'sortable'], $options),
             new TwigFunction('knp_pagination_filter', [PaginationRuntime::class, 'filter'], $options),
+            new TwigFunction('knp_pagination_query', [PaginationRuntime::class, 'getQueryParams']),
         ];
     }
 }

src/Twig/Extension/PaginationRuntime.php

@@ -9,11 +9,11 @@
 
 final class PaginationRuntime implements RuntimeExtensionInterface
 {
-    private Processor $processor;
-
-    public function __construct(Processor $processor)
-    {
-        $this->processor = $processor;
+    public function __construct(
+        private readonly Processor $processor,
+        private readonly string $pageName = 'page',
+        private readonly bool $skipFirstPageLink = false,
+    ) {
     }
 
     /**
@@ -107,4 +107,22 @@ public function filter(
             $this->processor->filter($pagination, $fields, $options ?? [], $params ?? [])
         );
     }
+
+    /**
+     * @param array<string, mixed> $query
+     * @param int $page
+     * @return array<string, mixed>
+     */
+    public function getQueryParams(array $query, int $page): array
+    {
+        if ($page === 1 && $this->skipFirstPageLink) {
+            if (isset($query[$this->pageName])) {
+                unset($query[$this->pageName]);
+            }
+
+            return $query;
+        }
+
+        return array_merge($query, [$this->pageName => $page]);
+    }
 }

templates/Pagination/bulma_pagination.html.twig

@@ -13,23 +13,23 @@
 {% if pageCount > 1 %}
     <nav class="{{ classes|join(' ') }}" role="navigation" aria-label="pagination">
         {% if previous is defined %}
-            <a rel="prev" class="pagination-previous" href="{{ path(route, query|merge({(pageParameterName): previous})) }}">{{ 'label_previous'|trans({}, 'KnpPaginatorBundle') }}</a>
+            <a rel="prev" class="pagination-previous" href="{{ path(route, knp_pagination_query(query, previous)) }}">{{ 'label_previous'|trans({}, 'KnpPaginatorBundle') }}</a>
         {% else %}
             <a class="pagination-previous" disabled>{{ 'label_previous'|trans({}, 'KnpPaginatorBundle') }}</a>
         {% endif %}
 
         {% if next is defined %}
-            <a rel="next" class="pagination-next" href="{{ path(route, query|merge({(pageParameterName): next})) }}">{{ 'label_next'|trans({}, 'KnpPaginatorBundle') }}</a>
+            <a rel="next" class="pagination-next" href="{{ path(route, knp_pagination_query(query, next)) }}">{{ 'label_next'|trans({}, 'KnpPaginatorBundle') }}</a>
         {% else %}
             <a class="pagination-next" disabled>{{ 'label_next'|trans({}, 'KnpPaginatorBundle') }}</a>
         {% endif %}
 
         <ul class="pagination-list">
             <li>
                 {% if current == first %}
-                    <a class="pagination-link is-current" aria-label="Page {{ current }}" aria-current="page" href="{{ path(route, query|merge({(pageParameterName): first})) }}">1</a>
+                    <a class="pagination-link is-current" aria-label="Page {{ current }}" aria-current="page" href="{{ path(route, knp_pagination_query(query, first)) }}">1</a>
                 {% else %}
-                    <a class="pagination-link" href="{{ path(route, query|merge({(pageParameterName): first})) }}">1</a>
+                    <a class="pagination-link" href="{{ path(route, knp_pagination_query(query, first)) }}">1</a>
                 {% endif %}
             </li>
 
@@ -43,9 +43,9 @@
                 {% if first != page and page != last %}
                     <li>
                         {% if page == current %}
-                            <a class="pagination-link is-current" aria-label="Page {{ current }}" aria-current="page" href="{{ path(route, query|merge({(pageParameterName): page})) }}">{{ page }}</a>
+                            <a class="pagination-link is-current" aria-label="Page {{ current }}" aria-current="page" href="{{ path(route, knp_pagination_query(query, page)) }}">{{ page }}</a>
                         {% else %}
-                            <a class="pagination-link" aria-label="Goto page {{ page }}" href="{{ path(route, query|merge({(pageParameterName): page})) }}">{{ page }}</a>
+                            <a class="pagination-link" aria-label="Goto page {{ page }}" href="{{ path(route, knp_pagination_query(query, page)) }}">{{ page }}</a>
                         {% endif %}
                     </li>
                 {% endif %}
@@ -59,9 +59,9 @@
 
             <li>
                 {% if current == last %}
-                    <a class="pagination-link is-current" aria-label="Page {{ current }}" aria-current="page" href="{{ path(route, query|merge({(pageParameterName): last})) }}">{{ last }}</a>
+                    <a class="pagination-link is-current" aria-label="Page {{ current }}" aria-current="page" href="{{ path(route, knp_pagination_query(query, last)) }}">{{ last }}</a>
                 {% else %}
-                    <a class="pagination-link" href="{{ path(route, query|merge({(pageParameterName): last})) }}">{{ last }}</a>
+                    <a class="pagination-link" href="{{ path(route, knp_pagination_query(query, last)) }}">{{ last }}</a>
                 {% endif %}
             </li>
         </ul>

templates/Pagination/foundation_v5_pagination.html.twig

@@ -21,7 +21,7 @@
     <ul class="pagination">
         {% if previous is defined %}
                  <li class="arrow">
-                     <a rel="prev" href="{{ path(route, query|merge({(pageParameterName): previous})) }}">&laquo; {{ 'label_previous'|trans({}, 'KnpPaginatorBundle') }}</a>
+                     <a rel="prev" href="{{ path(route, knp_pagination_query(query, previous)) }}">&laquo; {{ 'label_previous'|trans({}, 'KnpPaginatorBundle') }}</a>
                  </li>
         {% else %}
             <li class="arrow unavailable">
@@ -33,11 +33,11 @@
 
         {% if startPage > 1 %}
             <li>
-                <a href="{{ path(route, query|merge({(pageParameterName): 1})) }}">1</a>
+                <a href="{{ path(route, knp_pagination_query(query, 1)) }}">1</a>
             </li>
             {% if startPage == 3 %}
                 <li>
-                    <a href="{{ path(route, query|merge({(pageParameterName): 2})) }}">2</a>
+                    <a href="{{ path(route, knp_pagination_query(query, 2)) }}">2</a>
                 </li>
             {% elseif startPage != 2 %}
                 <li class="unavailable">
@@ -49,7 +49,7 @@
         {% for page in pagesInRange %}
             {% if page != current %}
                 <li>
-                    <a href="{{ path(route, query|merge({(pageParameterName): page})) }}">
+                    <a href="{{ path(route, knp_pagination_query(query, page)) }}">
                         {{ page }}
                     </a>
                 </li>
@@ -69,20 +69,20 @@
                     </li>
                 {% else %}
                     <li>
-                        <a href="{{ path(route, query|merge({(pageParameterName): (pageCount - 1)})) }}">
+                        <a href="{{ path(route, knp_pagination_query(query, (pageCount - 1))) }}">
                             {{ pageCount - 1 }}
                         </a>
                     </li>
                 {% endif %}
             {% endif %}
             <li>
-                <a href="{{ path(route, query|merge({(pageParameterName): pageCount})) }}">{{ pageCount }}</a>
+                <a href="{{ path(route, knp_pagination_query(query, pageCount)) }}">{{ pageCount }}</a>
             </li>
         {% endif %}
 
         {% if next is defined %}
             <li class="arrow">
-                <a rel="next" href="{{ path(route, query|merge({(pageParameterName): next})) }}">
+                <a rel="next" href="{{ path(route, knp_pagination_query(query, next)) }}">
                     {{ 'label_next'|trans({}, 'KnpPaginatorBundle') }} &nbsp;&raquo;
                 </a>
             </li>

templates/Pagination/foundation_v6_pagination.html.twig

@@ -5,7 +5,7 @@
 
             {% if previous is defined %}
                 <li class="pagination-previous">
-                    <a rel="prev" href="{{ path(route, query|merge({(pageParameterName): previous})) }}">
+                    <a rel="prev" href="{{ path(route, knp_pagination_query(query, previous)) }}">
                         {{ 'label_previous'|trans({}, 'KnpPaginatorBundle') }}
                     </a>
                 </li>
@@ -17,11 +17,11 @@
 
             {% if startPage > 1 %}
                 <li>
-                    <a href="{{ path(route, query|merge({(pageParameterName): 1})) }}">1</a>
+                    <a href="{{ path(route, knp_pagination_query(query, 1)) }}">1</a>
                 </li>
                 {% if startPage == 3 %}
                     <li>
-                        <a href="{{ path(route, query|merge({(pageParameterName): 2})) }}">2</a>
+                        <a href="{{ path(route, knp_pagination_query(query, 2)) }}">2</a>
                     </li>
                 {% elseif startPage != 2 %}
                     <li class="ellipsis"></li>
@@ -31,7 +31,7 @@
             {% for page in pagesInRange %}
                 {% if page != current %}
                     <li>
-                        <a href="{{ path(route, query|merge({(pageParameterName): page})) }}">
+                        <a href="{{ path(route, knp_pagination_query(query, page)) }}">
                             {{ page }}
                         </a>
                     </li>
@@ -46,20 +46,20 @@
                         <li class="ellipsis"></li>
                     {% else %}
                         <li>
-                            <a href="{{ path(route, query|merge({(pageParameterName): (pageCount - 1)})) }}">
+                            <a href="{{ path(route, knp_pagination_query(query, (pageCount - 1))) }}">
                                 {{ pageCount - 1 }}
                             </a>
                         </li>
                     {% endif %}
                 {% endif %}
                 <li>
-                    <a href="{{ path(route, query|merge({(pageParameterName): pageCount})) }}">{{ pageCount }}</a>
+                    <a href="{{ path(route, knp_pagination_query(query, pageCount)) }}">{{ pageCount }}</a>
                 </li>
             {% endif %}
 
             {% if next is defined %}
                 <li class="pagination-next">
-                    <a rel="next" href="{{ path(route, query|merge({(pageParameterName): next})) }}">
+                    <a rel="next" href="{{ path(route, knp_pagination_query(query, next)) }}">
                         {{ 'label_next'|trans({}, 'KnpPaginatorBundle') }}
                     </a>
                 </li>