Deprecated ref() in favor of service()

Author: javiereguiluz

components/dependency_injection.rst

@@ -303,10 +303,14 @@ config files:
             ;
 
             $services->set('newsletter_manager', 'NewsletterManager')
-                ->call('setMailer', [ref('mailer')])
+                ->call('setMailer', [service('mailer')])
             ;
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
 
 Learn More
 ----------

security/custom_authentication_provider.rst

@@ -433,17 +433,22 @@ to service ids that may not exist yet: ``App\Security\Authentication\Provider\Ws
             $services = $configurator->services();
 
             $services->set(WsseProvider::class)
-                ->arg('$cachePool', ref('cache.app'))
+                ->arg('$cachePool', service('cache.app'))
             ;
 
             $services->set(WsseListener::class)
                 ->args([
-                    ref('security.token_storage'),
-                    ref('security.authentication.manager'),
+                    service('security.token_storage'),
+                    service('security.authentication.manager'),
                 ])
             ;
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 Now that your services are defined, tell your security context about your
 factory in the kernel::
 

service_container.rst

@@ -526,10 +526,15 @@ parameter and in PHP config use the ``Reference`` class:
             $services = $configurator->services();
 
             $services->set(MessageGenerator::class)
-                ->args([ref('logger')])
+                ->args([service('logger')])
             ;
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 Working with container parameters is straightforward using the container's
 accessor methods for parameters::
 
@@ -633,7 +638,7 @@ But, you can control this and pass in a different logger:
 
             // explicitly configure the service
             $services->set(SiteUpdateManager::class)
-                ->arg('$logger', ref('monolog.logger.request'))
+                ->arg('$logger', service('monolog.logger.request'))
             ;
         };
 
@@ -738,15 +743,15 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type
 
                     // pass this service to any $requestLogger argument for any
                     // service that's defined in this file
-                    ->bind('$requestLogger', ref('monolog.logger.request'))
+                    ->bind('$requestLogger', service('monolog.logger.request'))
 
                     // pass this service for any LoggerInterface type-hint for any
                     // service that's defined in this file
-                    ->bind(LoggerInterface::class, ref('monolog.logger.request'))
+                    ->bind(LoggerInterface::class, service('monolog.logger.request'))
 
                     // optionally you can define both the name and type of the argument to match
                     ->bind('string $adminEmail', 'manager@example.com')
-                    ->bind(LoggerInterface::class.' $requestLogger', ref('monolog.logger.request'))
+                    ->bind(LoggerInterface::class.' $requestLogger', service('monolog.logger.request'))
                     ->bind('iterable $rules', tagged_iterator('app.foo.rule'))
             ;
 
@@ -1113,16 +1118,16 @@ admin email. In this case, each needs to have a unique service id:
                 ->autowire(false)
                 // manually wire all arguments
                 ->args([
-                    ref(MessageGenerator::class),
-                    ref('mailer'),
+                   service(MessageGenerator::class),
+                   service('mailer'),
                     'superadmin@example.com',
                 ]);
 
             $services->set('site_update_manager.normal_users', SiteUpdateManager::class)
                 ->autowire(false)
                 ->args([
-                    ref(MessageGenerator::class),
-                    ref('mailer'),
+                    service(MessageGenerator::class),
+                    service('mailer'),
                     'contact@example.com',
                 ]);
 

service_container/autowiring.rst

@@ -507,10 +507,15 @@ the injection::
 
                 // If you wanted to choose the non-default service and do not
                 // want to use a named autowiring alias, wire it manually:
-                //     ->arg('$transformer', ref(UppercaseTransformer::class))
+                //     ->arg('$transformer', service(UppercaseTransformer::class))
                 // ...
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 Thanks to the ``App\Util\TransformerInterface`` alias, any argument type-hinted
 with this interface will be passed the ``App\Util\Rot13Transformer`` service.
 If the argument is named ``$shoutyTransformer``,

service_container/calls.rst

@@ -72,9 +72,13 @@ To configure the container to call the ``setLogger`` method, use the ``calls`` k
             // ...
 
             $services->set(MessageGenerator::class)
-                ->call('setLogger', [ref('logger')]);
+                ->call('setLogger', [service('logger')]);
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
 
 To provide immutable services, some classes implement immutable setters.
 Such setters return a new instance of the configured class

service_container/configurators.rst

@@ -180,12 +180,17 @@ all the classes are already loaded as services. All you need to do is specify th
 
             // override the services to set the configurator
             $services->set(NewsletterManager::class)
-                ->configurator(ref(EmailConfigurator::class), 'configure');
+                ->configurator(service(EmailConfigurator::class), 'configure');
 
             $services->set(GreetingCardManager::class)
-                ->configurator(ref(EmailConfigurator::class), 'configure');
+                ->configurator(service(EmailConfigurator::class), 'configure');
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 .. _configurators-invokable:
 
 Services can be configured via invokable configurators (replacing the
@@ -250,10 +255,10 @@ routes can reference :ref:`invokable controllers <controller-service-invoke>`.
 
             // override the services to set the configurator
             $services->set(NewsletterManager::class)
-                ->configurator(ref(EmailConfigurator::class));
+                ->configurator(service(EmailConfigurator::class));
 
             $services->set(GreetingCardManager::class)
-                ->configurator(ref(EmailConfigurator::class));
+                ->configurator(service(EmailConfigurator::class));
         };
 
 That's it! When requesting the ``App\Mail\NewsletterManager`` or

service_container/factories.rst

@@ -158,9 +158,14 @@ Configuration of the service container then looks like this:
             // second, use the factory service as the first argument of the 'factory'
             // method and the factory method as the second argument
             $services->set(NewsletterManager::class)
-                ->factory([ref(NewsletterManagerFactory::class), 'createNewsletterManager']);
+                ->factory([service(NewsletterManagerFactory::class), 'createNewsletterManager']);
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 .. _factories-invokable:
 
 Invokable Factories
@@ -228,8 +233,8 @@ method name, just as routes can reference
             $services = $configurator->services();
 
             $services->set(NewsletterManager::class)
-                ->args([ref('templating')])
-                ->factory(ref(NewsletterManagerFactory::class));
+                ->args([service('templating')])
+                ->factory(service(NewsletterManagerFactory::class));
         };
 
 .. _factories-passing-arguments-factory-method:
@@ -289,8 +294,8 @@ previous examples takes the ``templating`` service as an argument:
             $services = $configurator->services();
 
             $services->set(NewsletterManager::class)
-                ->factory([ref(NewsletterManagerFactory::class), 'createNewsletterManager'])
-                ->args([ref('templating')])
+                ->factory([service(NewsletterManagerFactory::class), 'createNewsletterManager'])
+                ->args([service('templating')])
             ;
         };
 

service_container/injection_types.rst

@@ -77,9 +77,13 @@ service container configuration:
             $services = $configurator->services();
 
             $services->set(NewsletterManager::class)
-                ->args(ref('mailer'));
+                ->args(service('mailer'));
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
 
 .. tip::
 
@@ -270,7 +274,7 @@ that accepts the dependency::
             $services = $configurator->services();
 
             $services->set(NewsletterManager::class)
-                ->call('setMailer', [ref('mailer')]);
+                ->call('setMailer', [service('mailer')]);
         };
 
 This time the advantages are:
@@ -350,7 +354,7 @@ Another possibility is setting public fields of the class directly::
             $services = $configurator->services();
 
             $services->set('app.newsletter_manager', NewsletterManager::class)
-                ->property('mailer', ref('mailer'));
+                ->property('mailer', service('mailer'));
         };
 
 There are mainly only disadvantages to using property injection, it is similar

service_container/optional_dependencies.rst

@@ -42,9 +42,13 @@ if the service does not exist:
             $services = $configurator->services();
 
             $services->set(NewsletterManager::class)
-                ->args([ref('logger')->nullOnInvalid()]);
+                ->args([service('logger')->nullOnInvalid()]);
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
 
 .. note::
 
@@ -99,7 +103,7 @@ call if the service exists and remove the method call if it does not:
             $services = $configurator->services();
 
             $services->set(NewsletterManager::class)
-                ->call('setLogger', [ref('logger')->ignoreOnInvalid()])
+                ->call('setLogger', [service('logger')->ignoreOnInvalid()])
             ;
         };
 

service_container/parent_services.rst

@@ -128,8 +128,8 @@ duplicated service definitions:
 
             $services->set(BaseDoctrineRepository::class)
                 ->abstract()
-                ->args([ref('doctrine.orm.entity_manager')])
-                ->call('setLogger', [ref('logger')])
+                ->args([service('doctrine.orm.entity_manager')])
+                ->call('setLogger', [service('logger')])
             ;
 
             $services->set(DoctrineUserRepository::class)
@@ -142,6 +142,11 @@ duplicated service definitions:
             ;
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 In this context, having a ``parent`` service implies that the arguments
 and method calls of the parent service should be used for the child services.
 Specifically, the ``EntityManager`` will be injected and ``setLogger()`` will
@@ -247,13 +252,13 @@ the child class:
 
                 // appends the '@app.username_checker' argument to the parent
                 // argument list
-                ->args([ref('app.username_checker')])
+                ->args([service('app.username_checker')])
             ;
 
             $services->set(DoctrinePostRepository::class)
                 ->parent(BaseDoctrineRepository::class)
 
                 # overrides the first argument
-                ->arg(0, ref('doctrine.custom_entity_manager'))
+                ->arg(0, service('doctrine.custom_entity_manager'))
             ;
         };

service_container/service_decoration.rst

@@ -172,14 +172,19 @@ automatically changed to ``'.inner'``):
             $services->set(DecoratingMailer::class)
                 ->decorate(Mailer::class)
                 // pass the old service as an argument
-                ->args([ref('.inner')]);
+                ->args([service('.inner')]);
         };
 
 .. versionadded:: 5.1
 
     The special ``.inner`` value was introduced in Symfony 5.1. In previous
     versions you needed to use: ``decorating_service_id + '.inner'``.
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 .. tip::
 
     The visibility of the decorated ``App\Mailer`` service (which is an alias
@@ -242,7 +247,7 @@ automatically changed to ``'.inner'``):
 
                 $services->set(DecoratingMailer::class)
                     ->decorate(Mailer::class, DecoratingMailer::class.'.wooz')
-                    ->args([ref(DecoratingMailer::class.'.wooz')]);
+                    ->args([service(DecoratingMailer::class.'.wooz')]);
             };
 
 Decoration Priority
@@ -303,11 +308,11 @@ the ``decoration_priority`` option. Its value is an integer that defaults to
 
             $services->set(Bar::class)
                 ->decorate(Foo::class, null, 5)
-                ->args([ref('.inner')]);
+                ->args([service('.inner')]);
 
             $services->set(Baz::class)
                 ->decorate(Foo::class, null, 1)
-                ->args([ref('.inner')]);
+                ->args([service('.inner')]);
         };
 
 
@@ -371,7 +376,7 @@ Three different behaviors are available:
 
             $services->set(Bar::class)
                 ->decorate(Foo::class, null, 0, ContainerInterface::IGNORE_ON_INVALID_REFERENCE)
-                ->args([ref('.inner')])
+                ->args([service('.inner')])
             ;
         };
 

service_container/service_subscribers_locators.rst

@@ -312,8 +312,8 @@ service definition to pass a collection of services to the service locator:
 
             $services->set('app.command_handler_locator', ServiceLocator::class)
                 ->args([[
-                    'App\FooCommand' => ref('app.command_handler.foo'),
-                    'App\BarCommand' => ref('app.command_handler.bar'),
+                    'App\FooCommand' => service('app.command_handler.foo'),
+                    'App\BarCommand' => service('app.command_handler.bar'),
                 ]])
                 // if you are not using the default service autoconfiguration,
                 // add the following tag to the service definition:
@@ -323,11 +323,16 @@ service definition to pass a collection of services to the service locator:
             // if the element has no key, the ID of the original service is used
             $services->set('app.another_command_handler_locator', ServiceLocator::class)
                 ->args([[
-                    ref('app.command_handler.baz'),
+                    service('app.command_handler.baz'),
                 ]])
             ;
         };
 
+.. deprecated:: 5.1
+
+    In Symfony 5.1, the ``ref()`` function used in the PHP service configuration
+    was deprecated in favor of the ``service()`` function.
+
 .. note::
 
     The services defined in the service locator argument must include keys,
@@ -372,7 +377,7 @@ Now you can use the service locator by injecting it in any other service:
             $services = $configurator->services();
 
             $services->set(CommandBus::class)
-                ->args([ref('app.command_handler_locator')]);
+                ->args([service('app.command_handler_locator')]);
         };
 
 In :doc:`compiler passes </service_container/compiler_passes>` it's recommended