Merge pull request #8134 from cakephp/5.next-limit

Docs for limitControl() enhancements.

Author: othercorey

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).

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
 ==============================