From 7962f2e4bac2764e3d50cab606a36446f3f9fedf Mon Sep 17 00:00:00 2001
From: Kevin Pfeifer <kevin.pfeifer@sunlime.at>
Date: Mon, 20 Jul 2026 18:06:25 +0200
Subject: [PATCH] add missing docs for maskRegex and maskPartialRegex

---
 docs/en/appendices/5-4-migration-guide.md |  3 ++
 docs/en/core-libraries/text.md            | 54 +++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/docs/en/appendices/5-4-migration-guide.md b/docs/en/appendices/5-4-migration-guide.md
index 296ed8fcd4..0e331043f9 100644
--- a/docs/en/appendices/5-4-migration-guide.md
+++ b/docs/en/appendices/5-4-migration-guide.md
@@ -241,6 +241,9 @@ events are now registered while each plugin is bootstrapped.
   You can set `Security.encryptWithRawKey` to enable this behavior. See [here](https://github.com/cakephp/cakephp/pull/19325) for more details.
 - Added `Text::mask()` method which masks a portion of a string with a repeated character. See [Text Masking](../core-libraries/text.md#text-masking) for more details.
 - Added `Text::maskValue()` method which masks all occurrences of given substrings within a string using a repeated character. See [Text Masking](../core-libraries/text.md#text-masking) for more details.
+- Added `Text::maskRegex()` and `Text::maskPartialRegex()` methods for masking
+  regular expression matches. See [Text Masking](../core-libraries/text.md#text-masking)
+  for more details.
 
 ### View
 
diff --git a/docs/en/core-libraries/text.md b/docs/en/core-libraries/text.md
index ff8703372e..3ac39f5137 100644
--- a/docs/en/core-libraries/text.md
+++ b/docs/en/core-libraries/text.md
@@ -501,4 +501,58 @@ echo Text::maskValue('4111111111111234', ['411', '112'], '*');
 Output:
 
     ***11111111***34
+
+### Text::maskRegex()
+
+`method` Cake\\Utility\\Text::**maskRegex**(string $string, array|string $patterns, string $maskCharacter = '*'): string
+
+Masks all occurrences of given regular expression pattern(s) within a string
+using a repeated character. Each match is replaced by a sequence of the masking
+character with the same length as the match.
+
+The `$patterns` argument accepts a single regular expression or an array of
+regular expressions. Empty patterns are ignored. `$maskCharacter` must be a
+single character.
+
+```php
+// Called as TextHelper
+echo $this->Text->maskRegex('my pin is 1234', '/\d+/', '*');
+
+// Called as Text
+use Cake\Utility\Text;
+
+echo Text::maskRegex('token: abc123', '/[a-z0-9]+/', 'x');
+```
+
+Output:
+
+    my pin is ****
+    xxxxx: xxxxxx
+
+### Text::maskPartialRegex()
+
+`method` Cake\\Utility\\Text::**maskPartialRegex**(string $string, array|string $patterns, int $showLeading = 0, int $showTrailing = 0, string $maskCharacter = '*'): string
+
+Masks all occurrences of given regular expression pattern(s) within a string,
+while preserving a number of leading and trailing characters from each match.
+
+The `$showLeading` and `$showTrailing` arguments control how many characters at
+the start and end of each match are left unmasked. If their combined value is
+greater than or equal to the match length, the match is left unchanged. These
+values must be non-negative, and `$maskCharacter` must be a single character.
+
+```php
+// Called as TextHelper
+echo $this->Text->maskPartialRegex('card: 4242424242424242', '/\d{16}/', 0, 4);
+
+// Called as Text
+use Cake\Utility\Text;
+
+echo Text::maskPartialRegex('Secret Codeword', '/\b\w+\b/', 1, 1);
+```
+
+Output:
+
+    card: ************4242
+    S****t C******d
 <!-- end-text -->