From 7960d2803d76f7496c001c5eb97b9291b81b25b9 Mon Sep 17 00:00:00 2001
From: Josh Cummings <3627351+jzheaux@users.noreply.github.com>
Date: Thu, 10 Jul 2025 14:53:39 -0600
Subject: [PATCH] Add Migration Steps for PathMatcher Usage

Issue gh-17509
---
 .../ROOT/pages/migration-7/messaging.adoc     | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/modules/ROOT/pages/migration-7/messaging.adoc b/docs/modules/ROOT/pages/migration-7/messaging.adoc
index c60dcec29d..68e9373723 100644
--- a/docs/modules/ROOT/pages/migration-7/messaging.adoc
+++ b/docs/modules/ROOT/pages/migration-7/messaging.adoc
@@ -38,3 +38,49 @@ Xml::
 ======
 
 This will tell the Spring Security DSL to use `PathPatternMessageMatcher` for all message matchers that it constructs.
+
+Use of `PathMatcher` is no longer supported in 7.
+If you are using `PathMatcher` to change the path separator or to change case sensitivity for message matching, you can configure the `PathPatternParser` to do this instead like so:
+
+[tabs]
+======
+Java::
++
+[source,java,role="primary"]
+----
+@Bean
+PathPatternMessageMatcherBuilderFactoryBean messageMatcherBuilder() {
+	PathPatternParser pathPatternParser = new PathPatternParser();
+	pathPatternParser.setCaseSensitive(false);
+	// use . as path separator
+	pathPatternParser.setPathOptions(PathContainer.Options.MESSAGE_ROUTE);
+	return new PathPatternMessageMatcherBuilderFactoryBean(pathPatternParser);
+}
+----
+
+Kotlin::
++
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun messageMatcherBuilder(): PathPatternMessageMatcherBuilderFactoryBean {
+    val pathPatternParser = PathPatternParser()
+	pathPatternParser.setCaseSensitive(false)
+    // use . as path separator
+	pathPatternParser.setPathOptions(PathContainer.Options.MESSAGE_ROUTE)
+    return PathPatternMessageMatcherBuilderFactoryBean(pathPatternParser)
+}
+----
+
+Xml::
++
+[source,xml,role="secondary"]
+----
+<b:bean class="org.springframework.web.util.pattern.PathPatternParser">
+    <b:property name="caseSensitive" value="false"/>
+    <!-- use . as path separator -->
+    <b:property name="pathOptions" value="#{T(org.springframework.http.server.PathContainer.Options).MESSAGE_ROUTE"/>
+</b:bean>
+<b:bean class="org.springframework.security.config.web.messaging.PathPatternMessageMatcherBuilderFactoryBean"/>
+----
+======