From 498dc82731ec2b27ffe102e10146a230b71b6576 Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Tue, 18 Nov 2025 10:55:01 +0100
Subject: [PATCH] Docs for limitControl() enhancements.

---
 en/appendices/5-3-migration-guide.rst |  6 +++++
 en/views/helpers/paginator.rst        | 36 +++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/en/appendices/5-3-migration-guide.rst b/en/appendices/5-3-migration-guide.rst
index 00524b954a..88a5aff6a8 100644
--- a/en/appendices/5-3-migration-guide.rst
+++ b/en/appendices/5-3-migration-guide.rst
@@ -239,3 +239,9 @@ View
 
 - ``ViewBuilder::getConfigMergeStrategy()`` was added to retrieve the current merge
   strategy setting.
+
+- :php:meth:`PaginatorHelper::limitControl()` now automatically respects the
+  ``maxLimit`` configuration from the paginator, filtering out any limit options
+  that exceed it. A new ``steps`` option was added to automatically generate limit
+  options in multiples of a specific value (e.g., ``['steps' => 10]`` generates
+  10, 20, 30... up to maxLimit).
diff --git a/en/views/helpers/paginator.rst b/en/views/helpers/paginator.rst
index 19810632b6..7e6359d817 100644
--- a/en/views/helpers/paginator.rst
+++ b/en/views/helpers/paginator.rst
@@ -430,6 +430,42 @@ Create a dropdown control that changes the ``limit`` query parameter::
 
 The generated form and control will automatically submit on change.
 
+Automatic Limit Generation with Steps
+--------------------------------------
+
+Instead of manually defining limit options, you can use the ``steps`` option to
+automatically generate limits in multiples of a specific value::
+
+    // Generate limits in steps of 10 up to maxLimit
+    echo $this->Paginator->limitControl([], null, ['steps' => 10]);
+    // With maxLimit of 50, this generates: 10, 20, 30, 40, 50
+
+    // Steps of 25 up to maxLimit or 100 (whichever is lower)
+    echo $this->Paginator->limitControl([], null, ['steps' => 25]);
+
+When using ``steps``, you cannot also provide explicit limits in the ``$limits``
+parameter - you must use one or the other.
+
+Respecting maxLimit
+-------------------
+
+The ``limitControl()`` method automatically respects the ``maxLimit`` configuration
+from your paginator settings. Any limit options that exceed the ``maxLimit`` will
+be automatically filtered out::
+
+    // In your controller with maxLimit of 50
+    $this->paginate = [
+        'limit' => 20,
+        'maxLimit' => 50,
+    ];
+
+    // In your template - limits above 50 are filtered out
+    echo $this->Paginator->limitControl([20 => 20, 50 => 50, 100 => 100]);
+    // Only shows: 20, 50
+
+If all default or provided limits exceed the ``maxLimit``, the control will
+automatically use the ``maxLimit`` value as the only available option.
+
 Configuring Pagination Options
 ==============================