Deprecate modifying class parameters

[franmomu]

Ref https://github.com/doctrine/DoctrineMongoDBBundle/pull/810#discussion_r1425609444

@GromNaN do you mean something like this?

[GromNaN]

Just noted that we can deprecate parameters.

You can also deprecate container parameters in your extension to warn users about not using them anymore. This helps with the migration across major versions of an extension. Deprecation is only possible when using PHP to configure the extension, not when using XML or YAML. Use the ContainerBuilder::deprecateParameter() method to provide the deprecation details:

   $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.'
   );

[franmomu]

Just noted that we can deprecate parameters.

You can also deprecate container parameters in your extension to warn users about not using them anymore. This helps with the migration across major versions of an extension. Deprecation is only possible when using PHP to configure the extension, not when using XML or YAML. Use the ContainerBuilder::deprecateParameter() method to provide the deprecation details:

   $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.'
   );

I didn't know about that, but apparently it's only available since 6.3: https://github.com/symfony/symfony/pull/47719

[GromNaN]

Ok, so we can detect if method_exists($containerBuilder, 'deprecateParameter') and add the deprecation in that case. Developers who want to upgrade to DoctrineMongoDBBundle 5 should update to Symfony 6.4+ before.

That would be more simple than the conditional warning added in this PR.

[malarzm]

ContainerBuilder::deprecateParameter() sounds awesome :) I'd suggest adding an additional note in UPGRADE file and we should be good.

Developers who want to upgrade to DoctrineMongoDBBundle 5 should update to Symfony 6.4+ before.

This is a good point 👍

[franmomu]

After trying this, not sure if we can use ContainerBuilder::deprecateParameter() because we are still using these parameters so apparently we cannot deprecate them with this method without triggering deprecations 😞

[malarzm]

Weird, how Symfony suggests to use this deprecation then?

[GromNaN]

Weird, how Symfony suggests to use this deprecation then?

Maybe we can deprecate the parameters only in the next major version, once they are no longer used.

[GromNaN]

Thank you @franmomu