Document new priority key for plugin route definitions - #651
Document new priority key for plugin route definitions#651promptless-for-oss wants to merge 1 commit into
Conversation
Config-declared routes now honor an optional integer 'priority' key that controls route match order. Documents it in the Route definitions reference table and points the existing route-order caveat to it. Source: mautic/mautic PR #17169
| * - ``priority`` | ||
| - no | ||
| - integer | ||
| - Sets the order in which Mautic registers the route, relative to other routes. Symfony matches higher-priority routes first, and routes with equal priority keep their definition order. Use this to resolve match-order conflicts between overlapping paths. Defaults to ``0`` when omitted. |
There was a problem hiding this comment.
CoreSubscriber::addRouteToCollection() reads $details['priority'], casts to int, defaults to 0 when absent, and passes it as the third ($priority) argument to Symfony RouteCollection::add(). This method is invoked from onBuildRoute() for every bundle returned by BundleHelper::getMauticBundles(true), which includes plugin bundles, so the priority key applies to plugin-declared routes as documented.
| .. warning:: Each route's name must be unique across all bundles and firewalls and paths must be unique within the same firewall. | ||
|
|
||
| .. warning:: Order of routes matters as Symfony uses the first route that matches the URL. | ||
| .. warning:: Order of routes matters as Symfony uses the first route that matches the URL. Set a route's ``priority`` to control this order. |
There was a problem hiding this comment.
Symfony routing docs: "Routes with higher priority are sorted before routes with lower priority. The default value when it is not defined is 0." Symfony evaluates routes in the order they are defined when priority is otherwise equal. Confirmed against symfony/routing RouteCollection::all()/add() source: ties are broken by original insertion (definition) order via a stable uksort fallback on $keysOrder.
Source: https://symfony.com/doc/current/routing.html#routing-priority-parameter
1 participant
Open in Promptless
Config-declared routes can now set an optional integer
prioritykey that controls the order in which Mautic registers a route, so plugin authors can resolve match-order conflicts between overlapping paths explicitly instead of relying on definition order. Symfony matches higher-priority routes first, routes with equal priority keep their definition order, and priority defaults to0when omitted, so existing plugin route configs are unaffected.This documents the key in the "Route definitions" reference table on the plugin Config file page and points the existing route-order caveat to it. It does not change the plugin routing config mechanism, which remains fully supported.
Trigger Events