From 46c970b3debb2ba76907b107d6d3d9a3ccd40b23 Mon Sep 17 00:00:00 2001 From: lacatoire Date: Thu, 5 Feb 2026 12:49:43 +0100 Subject: [PATCH 1/3] Clarify PREG_UNMATCHED_AS_NULL behavior for trailing groups Fixes #3483 --- reference/pcre/constants.xml | 6 +++-- reference/pcre/functions/preg-match-all.xml | 8 ++++-- reference/pcre/functions/preg-match.xml | 30 +++++++++++++++++++-- 3 files changed, 38 insertions(+), 6 deletions(-) diff --git a/reference/pcre/constants.xml b/reference/pcre/constants.xml index d3759e4a977b..269814f3a57c 100644 --- a/reference/pcre/constants.xml +++ b/reference/pcre/constants.xml @@ -94,8 +94,10 @@ This flag tells preg_match and preg_match_all to include unmatched subpatterns in - $matches as &null; values. Without this flag, unmatched - subpatterns are reported as empty strings, as if they were empty matches. + $matches as &null; values, including trailing + unmatched subpatterns. Without this flag, non-trailing unmatched + subpatterns are reported as empty strings, while trailing unmatched + subpatterns are omitted from the results entirely. Setting this flag allows to distinguish between these two cases. 7.2.0 diff --git a/reference/pcre/functions/preg-match-all.xml b/reference/pcre/functions/preg-match-all.xml index d5387b6952f1..df0f50a37275 100644 --- a/reference/pcre/functions/preg-match-all.xml +++ b/reference/pcre/functions/preg-match-all.xml @@ -243,8 +243,12 @@ Array PREG_UNMATCHED_AS_NULL - If this flag is passed, unmatched subpatterns are reported as &null;; - otherwise they are reported as an empty string. + If this flag is passed, unmatched subpatterns are reported as &null; + and are always included in the results (including trailing ones). + Without this flag, unmatched subpatterns that are followed by a + matched subpattern are reported as an empty string, + while trailing unmatched subpatterns are omitted from the results + entirely. diff --git a/reference/pcre/functions/preg-match.xml b/reference/pcre/functions/preg-match.xml index 11587ac3144e..527a464a538f 100644 --- a/reference/pcre/functions/preg-match.xml +++ b/reference/pcre/functions/preg-match.xml @@ -119,8 +119,12 @@ Array PREG_UNMATCHED_AS_NULL - If this flag is passed, unmatched subpatterns are reported as &null;; - otherwise they are reported as an empty string. + If this flag is passed, unmatched subpatterns are reported as &null; + and are always included in the results (including trailing ones). + Without this flag, unmatched subpatterns that are followed by a + matched subpattern are reported as an empty string, + while trailing unmatched subpatterns are omitted from the results + entirely. ]]> @@ -155,6 +165,22 @@ array(4) { [3]=> string(1) "c" } +array(2) { + [0]=> + string(1) "a" + [1]=> + string(1) "a" +} +array(4) { + [0]=> + string(1) "a" + [1]=> + string(1) "a" + [2]=> + NULL + [3]=> + NULL +} ]]> From b7a5ddd095faad5b0ae866e23ae6dda6b0a33dff Mon Sep 17 00:00:00 2001 From: lacatoire Date: Mon, 18 May 2026 21:10:16 +0200 Subject: [PATCH 2/3] Document PHP 7.4.0 change for trailing unmatched groups Add a 7.4.0 changelog entry to preg_match() and preg_match_all(): when PREG_UNMATCHED_AS_NULL is used, trailing unmatched capturing groups are now included in the result with the value null. They were previously omitted entirely (php-src bug #73948). --- reference/pcre/functions/preg-match-all.xml | 8 ++++++++ reference/pcre/functions/preg-match.xml | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/reference/pcre/functions/preg-match-all.xml b/reference/pcre/functions/preg-match-all.xml index df0f50a37275..7e2629b3a6b0 100644 --- a/reference/pcre/functions/preg-match-all.xml +++ b/reference/pcre/functions/preg-match-all.xml @@ -305,6 +305,14 @@ Array + + 7.4.0 + + When the PREG_UNMATCHED_AS_NULL flag is used, + trailing unmatched capturing groups are now also included in the + result with the value &null;. Previously, they were omitted. + + 7.2.0 diff --git a/reference/pcre/functions/preg-match.xml b/reference/pcre/functions/preg-match.xml index 527a464a538f..93f23f48d2a9 100644 --- a/reference/pcre/functions/preg-match.xml +++ b/reference/pcre/functions/preg-match.xml @@ -296,6 +296,14 @@ Array + + 7.4.0 + + When the PREG_UNMATCHED_AS_NULL flag is used, + trailing unmatched capturing groups are now also included in the + result with the value &null;. Previously, they were omitted. + + 7.2.0 From 80b0ee0b9243e840d71d9a432467ab4ec2d4e731 Mon Sep 17 00:00:00 2001 From: lacatoire Date: Sat, 23 May 2026 22:59:22 +0200 Subject: [PATCH 3/3] pcre: use simpara for PREG_UNMATCHED_AS_NULL description (style guide) --- reference/pcre/functions/preg-match-all.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/pcre/functions/preg-match-all.xml b/reference/pcre/functions/preg-match-all.xml index 7e2629b3a6b0..54ba7af38125 100644 --- a/reference/pcre/functions/preg-match-all.xml +++ b/reference/pcre/functions/preg-match-all.xml @@ -242,14 +242,14 @@ Array PREG_UNMATCHED_AS_NULL - + If this flag is passed, unmatched subpatterns are reported as &null; and are always included in the results (including trailing ones). Without this flag, unmatched subpatterns that are followed by a matched subpattern are reported as an empty string, while trailing unmatched subpatterns are omitted from the results entirely. - +