How to Define Controllers as Services

Using the #[Route] Attribute

When using the #[Route] attribute to define routes on any PHP class, Symfony automatically applies the controller.service_arguments tag to it. As explained above, this registers the class as a public, non-lazy service and enables service argument injection.

This is the simplest and recommended way to register controllers as services when not extending the base controller class.

Using the #[AsController] Attribute

If you prefer, you can use the #[AsController] PHP attribute to automatically apply the controller.service_arguments tag to your controller services. The end result is the same as with #[Route]: the class becomes a public, non-lazy service with service argument injection enabled on its action methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// src/Controller/HelloController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
class HelloController
{
    #[Route('/hello', name: 'hello', methods: ['GET'])]
    public function index(): Response
    {
        // ...
    }
}

Using the controller.service_arguments Service Tag

If your controllers don't extend the AbstractController class and you don't use the #[AsController] or #[Route] attributes, you must register the controllers as public services manually and apply the controller.service_arguments service tag to enable service injection in controller actions:

1
2
3
4
5
6
7

# config/services.yaml

# controllers are imported separately to make sure services can be injected
# as action arguments even if you don't extend any base controller class
App\Controller\:
   resource: '../src/Controller/'
   tags: ['controller.service_arguments']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# config/services.yaml

# this extended configuration is only required when not using autowiring/autoconfiguration,
# which is uncommon and not recommended

abstract_controller.locator:
    class: Symfony\Component\DependencyInjection\ServiceLocator
    arguments:
        -
            router: '@router'
            request_stack: '@request_stack'
            http_kernel: '@http_kernel'
            session: '@session'
            parameter_bag: '@parameter_bag'
            # you can add more services here as you need them (e.g. the `serializer`
            # service) and have a look at the AbstractController class to see
            # which services are defined in the locator

App\Controller\:
    resource: '../src/Controller/'
    tags: ['controller.service_arguments']
    calls:
        - [setContainer, ['@abstract_controller.locator']]

Registering your controller as a service is the first step, but you also need to update your routing config to reference the service properly, so that Symfony knows to use it.

Use the service_id::method_name syntax to refer to the controller method. If the service id is the fully-qualified class name (FQCN) of your controller, as Symfony recommends, then the syntax is the same as if the controller was not a service like: App\Controller\HelloController::index:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// src/Controller/HelloController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class HelloController
{
    #[Route('/hello', name: 'hello', methods: ['GET'])]
    public function index(): Response
    {
        // ...
    }
}

1
2
3
4
5

# config/routes.yaml
hello:
    path:       /hello
    controller: App\Controller\HelloController::index
    methods:    GET

1
2
3
4
5
6
7
8
9
10
11
12

// config/routes.php
namespace Symfony\Component\Routing\Loader\Configurator;

use App\Controller\HelloController;

return Routes::config([
    'hello' => [
        'path' => '/hello',
        'controller' => [HelloController::class, 'index'],
        'methods' => ['GET'],
    ],
]);

Invokable Controllers

Any controller (whether or not it is registered as a service) can also define a single action using the __invoke() method, which is a common practice when following the ADR pattern (Action-Domain-Responder). When the class is registered as a service (for example via #[Route] on the class, as shown below), the __invoke() method benefits from service argument injection just like any other action method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// src/Controller/HelloController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/hello/{name}', name: 'hello')]
class HelloController
{
    public function __invoke(string $name = 'World'): Response
    {
        return new Response(sprintf('Hello %s!', $name));
    }
}

1
2
3
4

# config/routes.yaml
hello:
    path:       /hello/{name}
    controller: App\Controller\HelloController

1
2
3
4
5
6
7
8
9
10
11

// config/routes.php
namespace Symfony\Component\Routing\Loader\Configurator;

use App\Controller\HelloController;

return Routes::config([
    'hello' => [
        'path' => '/hello/{name}',
        'controller' => [HelloController::class, 'index'],
    ],
]);

Alternatives to base Controller Methods

When using a controller defined as a service, you can still extend the AbstractController base controller and use its shortcuts. But, you don't need to! You can choose to extend nothing, and use dependency injection to access different services.

The base Controller class source code is a great way to see how to accomplish common tasks. For example, $this->render() is usually used to render a Twig template and return a Response. But, you can also do this directly:

In a controller that's defined as a service, you can instead inject the twig service and use it directly:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/Controller/HelloController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Twig\Environment;

class HelloController
{
    public function __construct(
        private Environment $twig,
    ) {
    }

    public function index(string $name): Response
    {
        $content = $this->twig->render(
            'hello/index.html.twig',
            ['name' => $name]
        );

        return new Response($content);
    }
}

You can also use a special action-based dependency injection to receive services as arguments to your controller action methods.

Controller Allowlist

For security reasons, Symfony maintains an allowlist of controllers that are permitted to handle requests. Controllers that are not in this list will be rejected when Symfony needs to verify their legitimacy (e.g. when rendering ESI fragments or using the fragment renderer).

The following controllers are automatically allowed:

• Classes using the #[AsController] attribute;
• Classes extending AbstractController;
• The built-in TemplateController;
• All services tagged with controller.service_arguments.

If you use the #[Route] attribute on a class, Symfony already registers it as a service with the controller.service_arguments tag, so it is automatically allowed.

For bundle authors or advanced use cases where a controller does not match any of these criteria, call the allowControllers() method on the controller_resolver service to register additional controller types or attributes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/DependencyInjection/MyBundleExtension.php
namespace App\DependencyInjection;

use App\Controller\CustomFragmentController;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\Extension;

class MyBundleExtension extends Extension
{
    public function load(array $configs, ContainerBuilder $container): void
    {
        $container->getDefinition('controller_resolver')
            ->addMethodCall('allowControllers', [[CustomFragmentController::class]]);
    }
}

The allowControllers() method accepts two arguments: an array of class names ($types) and an array of attribute class names ($attributes). A controller is allowed if it is an instance of one of the given types or if its class has one of the given attributes.