From ec8e5d4005fce2abfa8332f849a2528a999686af Mon Sep 17 00:00:00 2001
From: ADmad <admad.coder@gmail.com>
Date: Sun, 20 Oct 2024 08:46:39 +0530
Subject: [PATCH] Add docs for CounterCacheBehavior::updateCounterCache().

Refs cakephp/cakephp#17967
---
 en/appendices/5-2-migration-guide.rst |  7 +++++++
 en/orm/behaviors/counter-cache.rst    | 25 +++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/en/appendices/5-2-migration-guide.rst b/en/appendices/5-2-migration-guide.rst
index 57b11b0001..1cd9b80909 100644
--- a/en/appendices/5-2-migration-guide.rst
+++ b/en/appendices/5-2-migration-guide.rst
@@ -15,6 +15,13 @@ Behavior Changes
 New Features
 ============
 
+ORM
+---
+
+- ``CounterCacheBehavior::updateCounterCache()`` has been addded. This method
+  allows you to update the counter cache values for all records of the configured
+  associations.
+
 Error
 -----
 
diff --git a/en/orm/behaviors/counter-cache.rst b/en/orm/behaviors/counter-cache.rst
index ae87db1142..fd633ee6a3 100644
--- a/en/orm/behaviors/counter-cache.rst
+++ b/en/orm/behaviors/counter-cache.rst
@@ -162,3 +162,28 @@ with the same code as described above.::
     ]);
 
 Finally clear all caches with ``bin/cake cache clear_all`` and try it out.
+
+Manually updating counter caches
+================================
+
+.. php:method:: updateCounterCache(?string $assocName = null, int $limit = 100, ?int $page = null): void
+
+The ``updateCounterCache()`` method allows you to update the counter cache values
+for all records of one or all configured associations in batches. This can be useful,
+for example, to update the counter cache after importing data directly into the database.::
+
+    // Update the counter cache for all configured associations
+    $table->updateCounterCache();
+
+    // Update the counter cache for a specific association, 200 records per batch
+    $table->updateCounterCache('Articles', 200);
+
+    // Update only the first page of records
+    $table->updateCounterCache('Articles', page: 1);
+
+.. versionadded:: 5.2.0
+
+.. note::
+
+    This methods won't update the counter cache values for fields which are
+    configured to use a closure to get the count value.