Skip to content

Remove mentions of the deprecated XML format #21449

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: 8.0
Choose a base branch
from
+79 −11,589
Open

Remove mentions of the deprecated XML format #21449

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ most services will be configured automatically. However, in some edge cases
you'll need to configure services (or parts of them) manually.

YAML is the format recommended configuring services because it's friendly to
newcomers and concise, but Symfony also supports XML and PHP configuration.
newcomers and concise, but Symfony also supports PHP configuration.

Use Attributes to Define the Doctrine Entity Mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -238,7 +238,7 @@ Use Attributes to Configure Routing, Caching, and Security

Using attributes for routing, caching, and security simplifies
configuration. You don't need to browse several files created with different
formats (YAML, XML, PHP): all the configuration is just where you require it,
formats (YAML, PHP): all the configuration is just where you require it,
and it only uses one format.

Use Dependency Injection to Get Services
Expand Down
15 changes: 0 additions & 15 deletions bundles/best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -427,21 +427,6 @@ The end user can provide values in any configuration file:
parameters:
acme_blog.author.email: '[email protected]'

.. code-block:: xml

<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd"
>
<parameters>
<parameter key="acme_blog.author.email">[email protected]</parameter>
</parameters>

</container>

.. code-block:: php

// config/services.php
Expand Down
173 changes: 18 additions & 155 deletions bundles/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,23 +20,6 @@
framework:
form: true

.. code-block:: xml

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>
<framework:config>
<framework:form/>
</framework:config>
</container>

.. code-block:: php

// config/packages/framework.php
Expand Down Expand Up @@ -162,23 +145,6 @@
client_id: 123
client_secret: your_secret

.. code-block:: xml

<!-- config/packages/acme_social.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:acme-social="http://example.org/schema/dic/acme_social"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd"
>
<acme-social:config>
<acme-social:twitter client-id="123"
client-secret="your_secret"
/>
</acme-social:config>
</container>

.. code-block:: php

// config/packages/acme_social.php
Expand Down Expand Up @@ -228,7 +194,7 @@
Whenever a user includes the ``acme_social`` key (which is the DI alias) in a
configuration file, the configuration under it is added to an array of
configurations and passed to the ``load()`` method of your extension (Symfony
automatically converts XML and YAML to an array).
automatically converts the configuration to an array).

For the configuration example in the previous section, the array passed to your
``load()`` method will look like this::
Expand Down Expand Up @@ -304,7 +270,7 @@
.. seealso::

The ``Configuration`` class can be much more complicated than shown here,
supporting "prototype" nodes, advanced validation, XML-specific normalization
supporting "prototype" nodes, advanced validation, plural/singular normalization
and advanced merging. You can read more about this in
:doc:`the Config component documentation </components/config/definition>`. You
can also see it in action by checking out some core Configuration
Expand Down Expand Up @@ -333,35 +299,31 @@
Now, you can use the ``$config`` variable to modify a service provided by your bundle.
For example, imagine your bundle has the following example config:

.. code-block:: xml

<!-- src/config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd"
>
<services>
<service id="acme_social.twitter_client" class="Acme\SocialBundle\TwitterClient">
<argument></argument> <!-- will be filled in with client_id dynamically -->
<argument></argument> <!-- will be filled in with client_secret dynamically -->
</service>
</services>
</container>
.. code-block:: php

Check failure on line 302 in bundles/configuration.rst

View workflow job for this annotation

GitHub Actions / Lint (DOCtor-RST) 

Please do not use ".. code-block:: php", use "::" instead.

<!-- src/config/services.php -->

Check failure on line 304 in bundles/configuration.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[PHP syntax] Syntax error, unexpected T_DEC

Check failure on line 304 in bundles/configuration.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[PHP syntax] Syntax error, unexpected '/', expecting '[' or T_OBJECT_OPERATOR or T_NULLSAFE_OBJECT_OPERATOR or '{'

Check failure on line 304 in bundles/configuration.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[PHP syntax] Syntax error, unexpected '<'
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

Check failure on line 305 in bundles/configuration.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[PHP syntax] Namespace declaration statement has to be the very first statement in the script

use Acme\SocialBundle\TwitterClient;

return function (ContainerConfigurator $container) {
$container->services()
->set('acme_social.twitter_client', TwitterClient::class)
->args([abstract_arg('client_id'), abstract_arg('client_secret')]);
};

In your extension, you can load this and dynamically set its arguments::

// src/DependencyInjection/AcmeSocialExtension.php
namespace Acme\SocialBundle\DependencyInjection;

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;

public function load(array $configs, ContainerBuilder $container): void
{
$loader = new XmlFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
$loader->load('services.xml');
$loader = new PhpFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
$loader->load('services.php');

$configuration = new Configuration();
$config = $this->processConfiguration($configuration, $configs);
Expand Down Expand Up @@ -401,7 +363,7 @@
Using the Config component is fully optional. The ``load()`` method gets an
array of configuration values. You can instead parse these arrays yourself
(e.g. by overriding configurations and using :phpfunction:`isset` to check
for the existence of a value). Be aware that it'll be very hard to support XML::
for the existence of a value)::

public function load(array $configs, ContainerBuilder $container): void
{
Expand Down Expand Up @@ -435,105 +397,6 @@
:method:`Extension::getConfiguration() <Symfony\\Component\\DependencyInjection\\Extension\\Extension::getConfiguration>`
method and return an instance of your ``Configuration``.

Supporting XML
--------------

Symfony allows people to provide the configuration in three different formats:
Yaml, XML and PHP. Both Yaml and PHP use the same syntax and are supported by
default when using the Config component. Supporting XML requires you to do some
more things. But when sharing your bundle with others, it is recommended that
you follow these steps.

Make your Config Tree ready for XML
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Config component provides some methods by default to allow it to correctly
process XML configuration. See ":ref:`component-config-normalization`" of the
component documentation. However, you can do some optional things as well, this
will improve the experience of using XML configuration:

Choosing an XML Namespace
~~~~~~~~~~~~~~~~~~~~~~~~~

In XML, the `XML namespace`_ is used to determine which elements belong to the
configuration of a specific bundle. The namespace is returned from the
:method:`Extension::getNamespace() <Symfony\\Component\\DependencyInjection\\Extension\\Extension::getNamespace>`
method. By convention, the namespace is a URL (it doesn't have to be a valid
URL nor does it need to exist). By default, the namespace for a bundle is
``http://example.org/schema/dic/DI_ALIAS``, where ``DI_ALIAS`` is the DI alias of
the extension. You might want to change this to a more professional URL::

// src/DependencyInjection/AcmeHelloExtension.php
namespace Acme\HelloBundle\DependencyInjection;

// ...
class AcmeHelloExtension extends Extension
{
// ...

public function getNamespace(): string
{
return 'http://acme_company.com/schema/dic/hello';
}
}

Providing an XML Schema
~~~~~~~~~~~~~~~~~~~~~~~

XML has a very useful feature called `XML schema`_. This allows you to
describe all possible elements and attributes and their values in an XML Schema
Definition (an XSD file). This XSD file is used by IDEs for auto completion and
it is used by the Config component to validate the elements.

In order to use the schema, the XML configuration file must provide an
``xsi:schemaLocation`` attribute pointing to the XSD file for a certain XML
namespace. This location always starts with the XML namespace. This XML
namespace is then replaced with the XSD validation base path returned from
:method:`Extension::getXsdValidationBasePath() <Symfony\\Component\\DependencyInjection\\Extension\\ExtensionInterface::getXsdValidationBasePath>`
method. This namespace is then followed by the rest of the path from the base
path to the file itself.

By convention, the XSD file lives in ``config/schema/`` directory, but you
can place it anywhere you like. You should return this path as the base path::

// src/DependencyInjection/AcmeHelloExtension.php
namespace Acme\HelloBundle\DependencyInjection;

// ...
class AcmeHelloExtension extends Extension
{
// ...

public function getXsdValidationBasePath(): string
{
return __DIR__.'/../config/schema';
}
}

Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be
``https://acme_company.com/schema/dic/hello/hello-1.0.xsd``:

.. code-block:: xml

<!-- config/packages/acme_hello.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:acme-hello="http://acme_company.com/schema/dic/hello"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://acme_company.com/schema/dic/hello
https://acme_company.com/schema/dic/hello/hello-1.0.xsd"
>
<acme-hello:config>
<!-- ... -->
</acme-hello:config>

<!-- ... -->
</container>

.. _`FrameworkBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php
.. _`TwigBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php
.. _`XML namespace`: https://en.wikipedia.org/wiki/XML_namespace
.. _`XML schema`: https://en.wikipedia.org/wiki/XML_schema
.. _`snake case`: https://en.wikipedia.org/wiki/Snake_case
16 changes: 8 additions & 8 deletions bundles/extension.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ method to load service definitions from configuration files::
{
public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
{
// load an XML, PHP or YAML file
$container->import('../config/services.xml');
// load a PHP or YAML file
$container->import('../config/services.php');

// you can also add or replace parameters and services
$container->parameters()
Expand Down Expand Up @@ -143,25 +143,25 @@ container.

In the ``load()`` method, you can use PHP code to register service definitions,
but it is more common if you put these definitions in a configuration file
(using the YAML, XML or PHP format).
(using the YAML or PHP format).

For instance, assume you have a file called ``services.xml`` in the
For instance, assume you have a file called ``services.php`` in the
``config/`` directory of your bundle, your ``load()`` method looks like::

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;

// ...
public function load(array $configs, ContainerBuilder $container): void
{
$loader = new XmlFileLoader(
$loader = new PhpFileLoader(
$container,
new FileLocator(__DIR__.'/../../config')
);
$loader->load('services.xml');
$loader->load('services.php');
}

The other available loaders are ``YamlFileLoader`` and ``PhpFileLoader``.
The other available loader is ``YamlFileLoader``.

Using Configuration to Change the Services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
26 changes: 0 additions & 26 deletions bundles/prepend_extension.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,32 +108,6 @@ registered and the ``entity_manager_name`` setting for ``acme_hello`` is set to
# ...
use_acme_goodbye: false

.. code-block:: xml

<!-- config/packages/acme_something.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:acme-something="http://example.org/schema/dic/acme_something"
xmlns:acme-other="http://example.org/schema/dic/acme_other"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://example.org/schema/dic/acme_something
https://example.org/schema/dic/acme_something/acme_something-1.0.xsd
http://example.org/schema/dic/acme_other
https://example.org/schema/dic/acme_something/acme_other-1.0.xsd"
>
<acme-something:config use-acme-goodbye="false">
<!-- ... -->
<acme-something:entity-manager-name>non_default</acme-something:entity-manager-name>
</acme-something:config>

<acme-other:config use-acme-goodbye="false">
<!-- ... -->
</acme-other:config>

</container>

.. code-block:: php

// config/packages/acme_something.php
Expand Down
Loading
Loading