10000 [DependencyInjection] Enable deprecating parameters by alexandre-daubois · Pull Request #17750 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

[DependencyInjection] Enable deprecating parameters #17750

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 10000

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

Merged
merged 1 commit into from
Jan 17, 2023
Merged

[DependencyInjection] Enable deprecating parameters #17750

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
[DependencyInjection] Enable deprecating parameters
  • Loading branch information
@alexandre-daubois
alexandre-daubois committed Jan 15, 2023
commit 978d0e82feb63ea8c1b67ac9c5f70e35e7af989f
33 changes: 32 additions & 1 deletion components/dependency_injection/compilation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,37 @@ file but also load a secondary one only if a certain parameter is set::
}
}

You are also able to deprecate container parameters in your extension to warn
to not use a specific parameter anymore. This is particularly useful to help
developers with the migration process across major versions of an extension.
The deprecation can be done thanks to the ``ContainerBuilder::deprecateParameter``
method. This can only be achieved when configuring an extension with PHP, as this is
not possible to do it with other configuration formats (YAML, XML). Let's define a
parameter in our extension that will be declared as deprecated::

public function load(array $configs, ContainerBuilder $containerBuilder)
{
// ...

$containerBuilder->setParameter('acme_demo.database_user', $configs['db_user']);

$containerBuilder->deprecateParameter(
'acme_demo.database_user',
'acme/database-package',
'1.3',
// optionally you can set a custom deprecation message
'"acme_demo.database_user" is deprecated, you should configure database credentials with the "acme_demo.database_dsn" parameter instead.'
);
}

The parameter being deprecated must be set before being declared as deprecated. Otherwise
a :class:`Symfony\\Component\\DependencyInjection\\Exception\\ParameterNotFoundException` exception
will be thrown.

.. versionadded:: 6.3

The ``ContainerBuilder::deprecateParameter`` method was introduced in Symfony 6.3.

.. note::

Just registering an extension with the container is not enough to get
Expand Down Expand Up @@ -478,7 +509,7 @@ serves at dumping the compiled container::
the :ref:`dumpFile() method <filesystem-dumpfile>` from Symfony Filesystem
component or other methods provided by Symfony (e.g. ``$containerConfigCache->write()``)
which are atomic.

``ProjectServiceContainer`` is the default name given to the dumped container
class. However, you can change this with the ``class`` option when you
dump it::
Expand Down
0