服务容器（Service Container）

注解

As a rule, a PHP object is a service if it is used globally in your application. A single Mailer service is used globally to send email messages whereas the many Message objects that it delivers are not services. Similarly, a Product object is not a service, but an object that persists Product objects to a database is a service.

• YAML

  # app/config/config.yml
  services:
      my_mailer:
          class:        AcmeHelloBundleMailer
          arguments:    [sendmail]
  

• XML

  <!-- app/config/config.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
          http://symfony.com/schema/dic/services/services-1.0.xsd"
  >
      <services>
          <service id="my_mailer" class="AcmeHelloBundleMailer">
              <argument>sendmail</argument>
          </service>
      </services>
  </container>
  

• PHP

  // app/config/config.php
  use SymfonyComponentDependencyInjectionDefinition;
  
  $container->setDefinition('my_mailer', new Definition(
      'AcmeHelloBundleMailer',
      array('sendmail')
  ));
  

注解

When Symfony initializes, it builds the service container using the application configuration (app/config/config.yml by default). The exact file that’s loaded is dictated by the AppKernel::registerContainerConfiguration() method, which loads an environment-specific configuration file (e.g. config_dev.yml for the dev environment or config_prod.yml for prod).

注解

In this example, the controller extends Symfony’s base Controller, which gives you access to the service container itself. You can then use the get method to locate and retrieve the my_mailer service from the service container. You can also define your controllers as services. This is a bit more advanced and not necessary, but it allows you to inject only the services you need into your controller.

• YAML

  # app/config/config.yml
  parameters:
      my_mailer.transport:  sendmail
  
  services:
      my_mailer:
          class:        AcmeHelloBundleMailer
          arguments:    ["%my_mailer.transport%"]
  

• XML

  <!-- app/config/config.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
          http://symfony.com/schema/dic/services/services-1.0.xsd">
  
      <parameters>
          <parameter key="my_mailer.transport">sendmail</parameter>
      </parameters>
  
      <services>
          <service id="my_mailer" class="AcmeHelloBundleMailer">
              <argument>%my_mailer.transport%</argument>
          </service>
      </services>
  </container>
  

• PHP

  // app/config/config.php
  use SymfonyComponentDependencyInjectionDefinition;
  
  $container->setParameter('my_mailer.transport', 'sendmail');
  
  $container->setDefinition('my_mailer', new Definition(
      'AcmeHelloBundleMailer',
      array('%my_mailer.transport%')
  ));
  

注解

If you want to use a string that starts with an @ sign as a parameter value (e.g. a very safe mailer password) in a YAML file, you need to escape it by adding another @ sign (this only applies to the YAML format):

# app/config/parameters.yml
parameters:
    # This will be parsed as string "@securepass"
    mailer_password: "@@securepass"

注解

The percent sign inside a parameter or argument, as part of the string, must be escaped with another percent sign:

<argument type="string">http://symfony.com/?foo=%%s&bar=%%d</argument>

数组类型参数¶

Parameters can also contain array values. See Array Parameters.

小技巧

In this section, service configuration files are referred to as resources. This is to highlight the fact that, while most configuration resources will be files (e.g. YAML, XML, PHP), Symfony is so flexible that configuration could be loaded from anywhere (e.g. a database or even via an external web service).

使用 imports 导入¶

So far, you’ve placed your my_mailer service container definition directly in the application configuration file (e.g. app/config/config.yml). Of course, since the Mailer class itself lives inside the AcmeHelloBundle, it makes more sense to put the my_mailer container definition inside the bundle as well.

First, move the my_mailer container definition into a new container resource file inside AcmeHelloBundle. If the Resources or Resources/config directories don’t exist, create them.

The definition itself hasn’t changed, only its location. Of course the service container doesn’t know about the new resource file. Fortunately, you can easily import the resource file using the imports key in the application configuration.

The imports directive allows your application to include service container configuration resources from any other location (most commonly from bundles). The resource location, for files, is the absolute path to the resource file. The special @AcmeHelloBundle syntax resolves the directory path of the AcmeHelloBundle bundle. This helps you specify the path to the resource without worrying later if you move the AcmeHelloBundle to a different directory.

使用Container扩展导入配置¶

When developing in Symfony, you’ll most commonly use the imports directive to import container configuration from the bundles you’ve created specifically for your application. Third-party bundle container configuration, including Symfony core services, are usually loaded using another method that’s more flexible and easy to configure in your application.

Here’s how it works. Internally, each bundle defines its services very much like you’ve seen so far. Namely, a bundle uses one or more configuration resource files (usually XML) to specify the parameters and services for that bundle. However, instead of importing each of these resources directly from your application configuration using the imports directive, you can simply invoke a service container extension inside the bundle that does the work for you. A service container extension is a PHP class created by the bundle author to accomplish two things:

• import all service container resources needed to configure the services for the bundle;
• provide semantic, straightforward configuration so that the bundle can be configured without interacting with the flat parameters of the bundle’s service container configuration.

In other words, a service container extension configures the services for a bundle on your behalf. And as you’ll see in a moment, the extension provides a sensible, high-level interface for configuring the bundle.

Take the FrameworkBundle - the core Symfony framework bundle - as an example. The presence of the following code in your application configuration invokes the service container extension inside the FrameworkBundle:

When the configuration is parsed, the container looks for an extension that can handle the framework configuration directive. The extension in question, which lives in the FrameworkBundle, is invoked and the service configuration for the FrameworkBundle is loaded. If you remove the framework key from your application configuration file entirely, the core Symfony services won’t be loaded. The point is that you’re in control: the Symfony framework doesn’t contain any magic or perform any actions that you don’t have control over.

Of course you can do much more than simply “activate” the service container extension of the FrameworkBundle. Each extension allows you to easily customize the bundle, without worrying about how the internal services are defined.

In this case, the extension allows you to customize the error_handler, csrf_protection, router configuration and much more. Internally, the FrameworkBundle uses the options specified here to define and configure the services specific to it. The bundle takes care of creating all the necessary parameters and services for the service container, while still allowing much of the configuration to be easily customized. As a bonus, most service container extensions are also smart enough to perform validation - notifying you of options that are missing or the wrong data type.

When installing or configuring a bundle, see the bundle’s documentation for how the services for the bundle should be installed and configured. The options available for the core bundles can be found inside the Reference Guide.

If you want to expose user friendly configuration in your own bundles, read the “如何在Bundle内部载入Service配置” cookbook recipe.

• YAML

  # src/Acme/HelloBundle/Resources/config/services.yml
  services:
      my_mailer:
          # ...
  
      newsletter_manager:
          class:     AcmeHelloBundleNewsletterNewsletterManager
          arguments: ["@my_mailer"]
  

• XML

  <!-- src/Acme/HelloBundle/Resources/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
          http://symfony.com/schema/dic/services/services-1.0.xsd">
  
      <services>
          <service id="my_mailer">
          <!-- ... -->
          </service>
  
          <service id="newsletter_manager" class="AcmeHelloBundleNewsletterNewsletterManager">
              <argument type="service" id="my_mailer"/>
          </service>
      </services>
  </container>
  

• PHP

  // src/Acme/HelloBundle/Resources/config/services.php
  use SymfonyComponentDependencyInjectionDefinition;
  use SymfonyComponentDependencyInjectionReference;
  
  $container->setDefinition('my_mailer', ...);
  
  $container->setDefinition('newsletter_manager', new Definition(
      'AcmeHelloBundleNewsletterNewsletterManager',
      array(new Reference('my_mailer'))
  ));
  

使用表达式¶

The service container also supports an “expression” that allows you to inject very specific values into a service.

For example, suppose you have a third service (not shown here), called mailer_configuration, which has a getMailerMethod() method on it, which will return a string like sendmail based on some configuration. Remember that the first argument to the my_mailer service is the simple string sendmail:

But instead of hardcoding this, how could we get this value from the getMailerMethod() of the new mailer_configuration service? One way is to use an expression:

To learn more about the expression language syntax, see The Expression Syntax.

In this context, you have access to 2 functions:

• service
• Returns a given service (see the example above).
• parameter
• Returns a specific parameter value (syntax is just like service).

You also have access to the ContainerBuilder via a container variable. Here’s another example:

Expressions can be used in arguments, properties, as arguments with configurator and as arguments to calls (method calls).

可选依赖：使用Setter方式注入¶

Injecting dependencies into the constructor in this manner is an excellent way of ensuring that the dependency is available to use. If you have optional dependencies for a class, then “setter injection” may be a better option. This means injecting the dependency using a method call rather than through the constructor. The class would look like this:

namespace AcmeHelloBundleNewsletter;

use AcmeHelloBundleMailer;

class NewsletterManager
{
    protected $mailer;

    public function setMailer(Mailer $mailer)
    {
        $this->mailer = $mailer;
    }

    // ...
}

Injecting the dependency by the setter method just needs a change of syntax:

注入Request¶

As of Symfony 2.4, instead of injecting the request service, you should inject the request_stack service and access the Request by calling the getCurrentRequest() method:

namespace AcmeHelloBundleNewsletter;

use SymfonyComponentHttpFoundationRequestStack;

class NewsletterManager
{
    protected $requestStack;

    public function __construct(RequestStack $requestStack)
    {
        $this->requestStack = $requestStack;
    }

    public function anyMethod()
    {
        $request = $this->requestStack->getCurrentRequest();
        // ... do something with the request
    }

    // ...
}

Now, just inject the request_stack, which behaves like any normal service:

• YAML

  # src/Acme/HelloBundle/Resources/config/services.yml
  services:
      newsletter_manager:
          class:     AcmeHelloBundleNewsletterNewsletterManager
          arguments: ["@?my_mailer"]
  

• XML

  <!-- src/Acme/HelloBundle/Resources/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
          http://symfony.com/schema/dic/services/services-1.0.xsd">
  
      <services>
          <service id="my_mailer">
          <!-- ... -->
          </service>
  
          <service id="newsletter_manager" class="AcmeHelloBundleNewsletterNewsletterManager">
              <argument type="service" id="my_mailer" on-invalid="ignore" />
          </service>
      </services>
  </container>
  

• PHP

  // src/Acme/HelloBundle/Resources/config/services.php
  use SymfonyComponentDependencyInjectionDefinition;
  use SymfonyComponentDependencyInjectionReference;
  use SymfonyComponentDependencyInjectionContainerInterface;
  
  $container->setDefinition('my_mailer', ...);
  
  $container->setDefinition('newsletter_manager', new Definition(
      'AcmeHelloBundleNewsletterNewsletterManager',
      array(
          new Reference(
              'my_mailer',
              ContainerInterface::IGNORE_ON_INVALID_REFERENCE
          )
      )
  ));
  

• YAML

  # src/Acme/HelloBundle/Resources/config/services.yml
  services:
      newsletter_manager:
          class:     AcmeHelloBundleNewsletterNewsletterManager
          arguments: ["@mailer", "@templating"]
  

• XML

  <!-- src/Acme/HelloBundle/Resources/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
          http://symfony.com/schema/dic/services/services-1.0.xsd">
  
      <service id="newsletter_manager" class="AcmeHelloBundleNewsletterNewsletterManager">
          <argument type="service" id="mailer"/>
          <argument type="service" id="templating"/>
      </service>
  </container>
  

• PHP

  // src/Acme/HelloBundle/Resources/config/services.php
  $container->setDefinition('newsletter_manager', new Definition(
      'AcmeHelloBundleNewsletterNewsletterManager',
      array(
          new Reference('mailer'),
          new Reference('templating'),
      )
  ));
  

小技巧

Be sure that the swiftmailer entry appears in your application configuration. As was mentioned in 使用Container扩展导入配置, the swiftmailer key invokes the service extension from the SwiftmailerBundle, which registers the mailer service.

• YAML

  # app/config/services.yml
  services:
      foo.twig.extension:
          class: AcmeHelloBundleExtensionFooExtension
          public: false
          tags:
              -  { name: twig.extension }
  

• XML

  <!-- app/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
          http://symfony.com/schema/dic/services/services-1.0.xsd">
  
      <service
          id="foo.twig.extension"
          class="AcmeHelloBundleExtensionFooExtension"
          public="false">
  
          <tag name="twig.extension" />
      </service>
  </container>
  

• PHP

  // app/config/services.php
  use SymfonyComponentDependencyInjectionDefinition;
  
  $definition = new Definition('AcmeHelloBundleExtensionFooExtension');
  $definition->setPublic(false);
  $definition->addTag('twig.extension');
  $container->setDefinition('foo.twig.extension', $definition);
  

2.6 新版功能: Prior to Symfony 2.6, this command was called container:debug.

注解

If a private service is only used as an argument to just one other service, it won’t be displayed by the debug:container command, even when using the --show-private option. See Inline Private Services for more details.