Prepare transition from XML- to PHP-based routing configuration (#43)

XML-based routing configuration has been deprecated in Symfony 7.4.

To provide a way forward, this PR adds a PHP-based routing
configuration. The XML file will include the PHP version, and a
deprecation notice will be triggered to remind users that they need to
update their configuration.

The XML file will be removed in the future.

Author: mpdude

CHANGELOG.md

@@ -5,7 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased 2.1]
+## Version 2.1.0
+
+- XML-based routing configuration has been deprecated in Symfony 7.4. Switch to PHP-based routing configuration by including
+  `guide-routing.php` instead of `guide-routing.xml`. A deprecation notice will be triggered.
 
 ## Version 2.0.0
 

README.md

@@ -101,17 +101,17 @@ By default, the `RemoveWrappingParagraphElementsEventHandler` contained in this
 
 ## Activating the Shortcode Guide
 
-The optional Shortcode Guide is a controller providing an overview page of all configured shortcodes. For every shortcode, there is also a detail page including a rendered example. 
+The optional Shortcode Guide is a controller providing an overview page of all configured shortcodes. For every shortcode, there is also a detail page including a rendered example.
 
-To use the Shortcode Guide, include the routing configuration from `@WebfactoryShortcodeBundle/Resources/config/guide-routing.xml`.
+To use the Shortcode Guide, include the routing configuration from `@WebfactoryShortcodeBundle/Resources/config/guide-routing.php`.
 
 ⚠️ You probably want to do this only for your Symfony `dev` and/or `test` environment, and possibly restrict access in your security configuration in addition to that.
 
 ```yaml
 # src/routing.yml
 _shortcode-guide:
     prefix: /shortcodes
-    resource: "@WebfactoryShortcodeBundle/Resources/config/guide-routing.xml"
+    resource: "@WebfactoryShortcodeBundle/Resources/config/guide-routing.php"
 ```
 
 With the route prefix defined as above, visit `/shortcodes/` to see a list of all defined shortcodes. If you want to add descriptions to shortcodes and/or provide the example shortcode that shall be rendered on the detail page, you can add this information when configuring shortcodes:
@@ -241,6 +241,5 @@ Assuming that your application configuration registers a handler for the `text`
 This bundle was started at webfactory GmbH, Bonn.
 
 - <https://www.webfactory.de>
-- <https://twitter.com/webfactory>
 
-Copyright 2018-2023 webfactory GmbH, Bonn. Code released under [the MIT license](LICENSE).
+Copyright 2018-2025 webfactory GmbH, Bonn. Code released under [the MIT license](LICENSE).

composer.json

@@ -14,6 +14,7 @@
         "symfony/form": "^5.4|^6.0|^7.0",
         "symfony/http-foundation": "^5.4|^6.0|^7.0",
         "symfony/http-kernel": "^5.4|^6.0|^7.0",
+        "symfony/routing": "^5.4|^6.0|^7.0",
         "thunderer/shortcode": "^0.6.5|^0.7",
         "twig/twig": "^2.0|^3.0"
     },
@@ -25,7 +26,6 @@
         "symfony/expression-language": "^5.4|^6.0|^7.0",
         "symfony/framework-bundle": "^5.4|^6.0|^7.0",
         "symfony/phpunit-bridge": ">= 6.0",
-        "symfony/routing": "^5.4|^6.0|^7.0",
         "symfony/twig-bundle": "^5.4|^6.0|^7.0",
         "symfony/yaml": "^5.4|^6.0|^7.0"
     },

src/Resources/config/guide-routing.php

@@ -0,0 +1,23 @@
+<?php
+
+use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+use Symfony\Component\Routing\Loader\XmlFileLoader;
+use Webfactory\ShortcodeBundle\Controller\GuideController;
+
+return static function (RoutingConfigurator $routes): void {
+    foreach (debug_backtrace() as $trace) {
+        if (isset($trace['object']) && $trace['object'] instanceof XmlFileLoader && 'doImport' === $trace['function']) {
+            if (__DIR__ === dirname(realpath($trace['args'][3]))) {
+                trigger_deprecation('webfactory/shortcode-bundle', '2.7', 'The "guide-routing.xml" routing configuration file is deprecated, import "guide-routing.php" instead.');
+
+                break;
+            }
+        }
+    }
+
+    $routes->add('webfactory.shortcode.guide-list', '/')
+        ->controller([GuideController::class, 'listAction']);
+
+    $routes->add('webfactory.shortcode.guide-detail', '/{shortcode}/')
+        ->controller([GuideController::class, 'detailAction']);
+};

src/Resources/config/guide-routing.xml

@@ -4,12 +4,6 @@
         xsi:schemaLocation="http://symfony.com/schema/routing
         http://symfony.com/schema/routing/routing-1.0.xsd">
 
-    <route id="webfactory.shortcode.guide-list" path="/">
-        <default key="_controller">Webfactory\ShortcodeBundle\Controller\GuideController::listAction</default>
-    </route>
-
-    <route id="webfactory.shortcode.guide-detail" path="/{shortcode}/">
-        <default key="_controller">Webfactory\ShortcodeBundle\Controller\GuideController::detailAction</default>
-    </route>
+    <import resource="guide-routing.php" />
 
 </routes>