From 64c30da9266bf3aec686f4436a80827a3012d578 Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Mon, 20 Oct 2025 11:57:20 +0200 Subject: [PATCH] Remove mentions of XML and Config Builders in Getting started guides XML is deprecated in 7.4. We should not advocate it anymore and people are on their own when they wish to still use it. For now, I suggest keeping the code examples (except from the Quick tour) to help in migration and developers inherting apps using XML. --- configuration.rst | 96 +++++---------------------------- page_creation.rst | 2 +- quick_tour/the_architecture.rst | 23 -------- routing.rst | 10 ++-- service_container.rst | 3 +- 5 files changed, 22 insertions(+), 112 deletions(-) diff --git a/configuration.rst b/configuration.rst index 4b1e75dcabe..5da003c739f 100644 --- a/configuration.rst +++ b/configuration.rst @@ -53,7 +53,7 @@ Configuration Formats ~~~~~~~~~~~~~~~~~~~~~ Unlike other frameworks, Symfony doesn't impose a specific format on you to -configure your applications, but lets you choose between YAML, XML and PHP. +configure your applications, but lets you choose between YAML and PHP. Throughout the Symfony documentation, all configuration examples will be shown in these three formats. @@ -66,20 +66,18 @@ readable. These are the main advantages and disadvantages of each format: * **YAML**: simple, clean and readable, but not all IDEs support autocompletion and validation for it. :doc:`Learn the YAML syntax `; -* **XML**: autocompleted/validated by most IDEs and is parsed natively by PHP, - but sometimes it generates configuration considered too verbose. `Learn the XML syntax`_; * **PHP**: very powerful and it allows you to create dynamic configuration with - arrays or a :ref:`ConfigBuilder `. + arrays, and benefits from auto completion and static analysis using + array shapes. -.. note:: +.. deprecated:: 7.4 + + The XML and Config Builder formats are deprecated in Symfony 7.4 and + will be removed in Symfony 8.0. - By default Symfony loads the configuration files defined in YAML and PHP - formats. If you define configuration in XML format, update the - :method:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait::configureContainer` - and/or - :method:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait::configureRoutes` - methods in the ``src/Kernel.php`` file to add support for the ``.xml`` file - extension. +.. versionadded:: 7.4 + + Array shapes were introduced in Symfony 7.4. Importing Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -100,9 +98,9 @@ configuration files, even if they use a different format: - { resource: '/etc/myapp/*.yaml' } # ignore_errors: not_found silently discards errors if the loaded file doesn't exist - - { resource: 'my_config_file.xml', ignore_errors: not_found } + - { resource: 'my_config_file.php', ignore_errors: not_found } # ignore_errors: true silently discards all errors (including invalid code and not found) - - { resource: 'my_other_config_file.xml', ignore_errors: true } + - { resource: 'my_other_config_file.php', ignore_errors: true } # ... @@ -267,27 +265,6 @@ reusable configuration value. By convention, parameters are defined under the // ... -.. warning:: - - By default and when using XML configuration, the values between ```` - tags are not trimmed. This means that the value of the following parameter will be - ``'\n something@example.com\n'``: - - .. code-block:: xml - - - something@example.com - - - If you want to trim the value of your parameter, use the ``trim`` attribute. - When using it, the value of the following parameter will be ``something@example.com``: - - .. code-block:: xml - - - something@example.com - - Once defined, you can reference this parameter value from any other configuration file using a special syntax: wrap the parameter name in two ``%`` (e.g. ``%app.admin_email%``): @@ -331,7 +308,7 @@ configuration file using a special syntax: wrap the parameter name in two ``%`` 'email_address' => param('app.admin_email'), // ... but if you prefer it, you can also pass the name as a string - // surrounded by two % (same as in YAML and XML formats) and Symfony will + // surrounded by two % (same as in the YAML format) and Symfony will // replace it by that parameter value 'email_address' => '%app.admin_email%', ]); @@ -1302,52 +1279,6 @@ parameters at once by type-hinting any of its constructor arguments with the } } -.. _config-config-builder: - -Using PHP ConfigBuilders ------------------------- - -Writing PHP config is sometimes difficult because you end up with large nested -arrays and you have no autocompletion help from your favorite IDE. A way to -address this is to use "ConfigBuilders". They are objects that will help you -build these arrays. - -Symfony generates the ConfigBuilder classes automatically in the -:ref:`kernel build directory ` for all the -bundles installed in your application. By convention they all live in the -namespace ``Symfony\Config``:: - - // config/packages/security.php - use Symfony\Config\SecurityConfig; - - return static function (SecurityConfig $security): void { - $security->firewall('main') - ->pattern('^/*') - ->lazy(true) - ->security(false); - - $security - ->roleHierarchy('ROLE_ADMIN', ['ROLE_USER']) - ->roleHierarchy('ROLE_SUPER_ADMIN', ['ROLE_ADMIN', 'ROLE_ALLOWED_TO_SWITCH']) - ->accessControl() - ->path('^/user') - ->roles('ROLE_USER'); - - $security->accessControl(['path' => '^/admin', 'roles' => 'ROLE_ADMIN']); - }; - -.. note:: - - Only root classes in the namespace ``Symfony\Config`` are ConfigBuilders. - Nested configs (e.g. ``\Symfony\Config\Framework\CacheConfig``) are regular - PHP objects which aren't autowired when using them as an argument type. - -.. note:: - - In order to get ConfigBuilders autocompletion in your IDE/editor, make sure - to not exclude the directory where these classes are generated (by default, - in ``var/cache/dev/Symfony/Config/``). - Keep Going! ----------- @@ -1369,7 +1300,6 @@ And all the other topics related to configuration: configuration/* -.. _`Learn the XML syntax`: https://en.wikipedia.org/wiki/XML .. _`environment variables`: https://en.wikipedia.org/wiki/Environment_variable .. _`symbolic links`: https://en.wikipedia.org/wiki/Symbolic_link .. _`utilities to manage env vars`: https://symfony.com/doc/current/cloud/env.html diff --git a/page_creation.rst b/page_creation.rst index d7833b84bee..c4aa0cfc856 100644 --- a/page_creation.rst +++ b/page_creation.rst @@ -87,7 +87,7 @@ try it out by going to: http://localhost:8000/lucky/number Symfony recommends defining routes as attributes to have the controller code and its route configuration at the same location. However, if you prefer, you can - :doc:`define routes in separate files ` using YAML, XML and PHP formats. + :doc:`define routes in separate files ` using the YAML or PHP formats. If you see a lucky number being printed back to you, congratulations! But before you run off to play the lottery, check out how this works. Remember the two steps diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst index 3b66570b3d3..c942c917a01 100644 --- a/quick_tour/the_architecture.rst +++ b/quick_tour/the_architecture.rst @@ -243,29 +243,6 @@ using the special ``when@`` keyword: router: strict_requirements: null - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/routing.rst b/routing.rst index 753b4d4719d..43e267698c7 100644 --- a/routing.rst +++ b/routing.rst @@ -12,12 +12,16 @@ provides other useful features, like generating SEO-friendly URLs (e.g. Creating Routes --------------- -Routes can be configured in YAML, XML, PHP or using attributes. -All formats provide the same features and performance, so choose -your favorite. +Routes can be configured in YAML, PHP or using attributes. All formats +provide the same features and performance, so choose your favorite. :ref:`Symfony recommends attributes ` because it's convenient to put the route and controller in the same place. +.. deprecated:: 7.4 + + The XML format to configure routes is deprecated in Symfony 7.4 and + will be removed in Symfony 8.0. + .. _routing-route-attributes: Creating Routes as Attributes diff --git a/service_container.rst b/service_container.rst index 8b86d06a833..ed621943c1a 100644 --- a/service_container.rst +++ b/service_container.rst @@ -704,8 +704,7 @@ all their types (string, boolean, array, binary and PHP constant parameters). However, there is another type of parameter related to services. In YAML config, any string which starts with ``@`` is considered as the ID of a service, instead -of a regular string. In XML config, use the ``type="service"`` type for the -parameter and in PHP config use the ``service()`` function: +of a regular string. In PHP config use the ``service()`` function: .. configuration-block::