add new option to enhance first page link

Author: garak

README.md

@@ -22,7 +22,7 @@ chapter of the documentation.
 
 ## 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.
 
@@ -71,19 +71,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
@@ -101,14 +105,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]);
+    }
 }