…from `AbstractController` as a standalone service (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[FrameworkBundle] Add `ControllerHelper`; the helpers from `AbstractController` as a standalone service

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

This PR is a follow up of #16863 by `@derrabus` almost 10 years ago 😱, which was seeking for a solution to reuse helpers provided by `AbstractController` that'd be free from coupling by inheritance and that'd allow for more granular cherry-picking of the desired helpers.

At the time, granular traits were proposed as the reusability unit.

In this PR, I'm proposing to add a `ControllerHelper` class that'd allow achieving both goals using functions as the reusability unit instead.

To achieve true decoupling and granular helper injection, one would have to use the `#[AutowireMethodOf]` attribute (see #54016).

Here is the chain of thoughts and concepts that underpin the proposal. It should be noted that this reasoning should be read as an example that could be extended to any helper-like class, e.g it fits perfectly for cherry-picking query functions from entity repositories.

So, here is the chain for controllers:

 1. The Problem: The Monolithic Base Class

    Symfony's `AbstractController` offers a convenient set of helper methods for common controller tasks. However, by relying on inheritance, our controllers become tightly coupled to the framework. This can make them more difficult to test in isolation and provides them with a broad set of methods, even when only a few are needed.

 2. The Initial Goal: Reusability without Inheritance

    The long-standing goal has been to decouple controllers from this base class while retaining easy access to its valuable helper methods. The ideal solution would allow for a more granular, "à la carte" selection of these helpers.

 3. The Path Not Taken: Granular Traits

    The original proposal in PR #16863 explored the use of granular traits (e.g., `RenderTrait`, `RedirectTrait`). This was a step towards greater modularity, allowing a developer to use only the necessary functionalities. However, a trait-based approach has its own set of challenges:
      - Implicit Dependencies: The services required by the traits (like the templating engine or the router) are not explicitly declared as dependencies of the controller.
      - A Different Form of Coupling: While avoiding vertical inheritance, traits introduce a form of horizontal coupling.

 4. A More Modern Approach: The Injectable Helper Service

    This PR introduces a `ControllerHelper` service. This class extends `AbstractController` to leverage its existing, battle-tested logic but exposes all of its protected methods as public ones. This aligns with modern dependency injection principles, where services are explicitly injected rather than inherited. A controller can now inject the `ControllerHelper` and access the helper methods through it.

 5. The Final Step: True Granularity with `#[AutowireMethodOf]`

    While injecting the entire `ControllerHelper` is a significant improvement, it still provides the controller with access to all helper methods. The introduction of the `#[AutowireMethodOf]` attribute (see #54016) is the final piece of the puzzle, enabling the ultimate goal of using individual functions as the unit of reuse.

    With `#[AutowireMethodOf]`, we can inject just the specific helper method we need as a callable:

    ```php
    class MyController
    {
        public function __construct(
            #[AutowireMethodOf(ControllerHelper::class)]
            private \Closure $render,
            #[AutowireMethodOf(ControllerHelper::class)]
            private \Closure $redirectToRoute,
        ) {
        }

        public function showProduct(int $id): Response
        {
            if (!$id) {
                return ($this->redirectToRoute)('product_list');
            }

            return ($this->render)('product/show.html.twig', ['product_id' => $id]);
        }
    }
    ```

    This solution provides numerous benefits:
      - Maximum Decoupling: The controller has no direct dependency on `AbstractController` or even the `ControllerHelper` class in its methods. It only depends on the injected callables.
      - Explicit and Granular Dependencies: The controller's constructor clearly and precisely declares the exact functions it needs to operate.
      - Improved Testability (less relevant for controllers but quite nice for dependents of e.g. entity repositories): Mocking the injected callables in unit tests is straightforward and clean.

 6. Bonus: Auto-generated Adapters for Functional Interfaces

    For even better type-safety and application-level contracts, `#[AutowireMethodOf]` can generate adapters for functional interfaces. One can define an interface within their application's domain to achieve better type-coverage without any new coupling:

    ```php
    interface RenderInterface
    {
        public function __invoke(string $view, array $parameters = [], ?Response $response = null): Response;
    }
    ```

    Then update the previous controller example to use this interface:
    ```diff
             #[AutowireMethodOf(ControllerHelper::class)]
    -        private \Closure $render,
    +        private RenderInterface $render,
    ````

    Symfony's DI container will automatically create an adapter that implements `RenderInterface` and whose `__invoke` method calls the `render` method of the `ControllerHelper`. This gives full static analysis and autocompletion benefits with zero extra boilerplate code.

This pull request, therefore, not only provides a solution to a long-standing desire for more reusable controller logic but does so in a way that is modern, flexible, and fully embraces the power of Symfony's dependency injection container (while still preserving really good usability when the DIC is not used, as is the case when unit testing.)

Commits
-------

c2020bb [FrameworkBundle] Add `ControllerHelper`; the helpers from AbstractController as a standalone service

…from `AbstractController` as a standalone service (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[FrameworkBundle] Add `ControllerHelper`; the helpers from `AbstractController` as a standalone service

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

This PR is a follow up of symfony/symfony#16863 by `@derrabus` almost 10 years ago 😱, which was seeking for a solution to reuse helpers provided by `AbstractController` that'd be free from coupling by inheritance and that'd allow for more granular cherry-picking of the desired helpers.

At the time, granular traits were proposed as the reusability unit.

In this PR, I'm proposing to add a `ControllerHelper` class that'd allow achieving both goals using functions as the reusability unit instead.

To achieve true decoupling and granular helper injection, one would have to use the `#[AutowireMethodOf]` attribute (see symfony/symfony#54016).

Here is the chain of thoughts and concepts that underpin the proposal. It should be noted that this reasoning should be read as an example that could be extended to any helper-like class, e.g it fits perfectly for cherry-picking query functions from entity repositories.

So, here is the chain for controllers:

 1. The Problem: The Monolithic Base Class

    Symfony's `AbstractController` offers a convenient set of helper methods for common controller tasks. However, by relying on inheritance, our controllers become tightly coupled to the framework. This can make them more difficult to test in isolation and provides them with a broad set of methods, even when only a few are needed.

 2. The Initial Goal: Reusability without Inheritance

    The long-standing goal has been to decouple controllers from this base class while retaining easy access to its valuable helper methods. The ideal solution would allow for a more granular, "à la carte" selection of these helpers.

 3. The Path Not Taken: Granular Traits

    The original proposal in PR #16863 explored the use of granular traits (e.g., `RenderTrait`, `RedirectTrait`). This was a step towards greater modularity, allowing a developer to use only the necessary functionalities. However, a trait-based approach has its own set of challenges:
      - Implicit Dependencies: The services required by the traits (like the templating engine or the router) are not explicitly declared as dependencies of the controller.
      - A Different Form of Coupling: While avoiding vertical inheritance, traits introduce a form of horizontal coupling.

 4. A More Modern Approach: The Injectable Helper Service

    This PR introduces a `ControllerHelper` service. This class extends `AbstractController` to leverage its existing, battle-tested logic but exposes all of its protected methods as public ones. This aligns with modern dependency injection principles, where services are explicitly injected rather than inherited. A controller can now inject the `ControllerHelper` and access the helper methods through it.

 5. The Final Step: True Granularity with `#[AutowireMethodOf]`

    While injecting the entire `ControllerHelper` is a significant improvement, it still provides the controller with access to all helper methods. The introduction of the `#[AutowireMethodOf]` attribute (see #54016) is the final piece of the puzzle, enabling the ultimate goal of using individual functions as the unit of reuse.

    With `#[AutowireMethodOf]`, we can inject just the specific helper method we need as a callable:

    ```php
    class MyController
    {
        public function __construct(
            #[AutowireMethodOf(ControllerHelper::class)]
            private \Closure $render,
            #[AutowireMethodOf(ControllerHelper::class)]
            private \Closure $redirectToRoute,
        ) {
        }

        public function showProduct(int $id): Response
        {
            if (!$id) {
                return ($this->redirectToRoute)('product_list');
            }

            return ($this->render)('product/show.html.twig', ['product_id' => $id]);
        }
    }
    ```

    This solution provides numerous benefits:
      - Maximum Decoupling: The controller has no direct dependency on `AbstractController` or even the `ControllerHelper` class in its methods. It only depends on the injected callables.
      - Explicit and Granular Dependencies: The controller's constructor clearly and precisely declares the exact functions it needs to operate.
      - Improved Testability (less relevant for controllers but quite nice for dependents of e.g. entity repositories): Mocking the injected callables in unit tests is straightforward and clean.

 6. Bonus: Auto-generated Adapters for Functional Interfaces

    For even better type-safety and application-level contracts, `#[AutowireMethodOf]` can generate adapters for functional interfaces. One can define an interface within their application's domain to achieve better type-coverage without any new coupling:

    ```php
    interface RenderInterface
    {
        public function __invoke(string $view, array $parameters = [], ?Response $response = null): Response;
    }
    ```

    Then update the previous controller example to use this interface:
    ```diff
             #[AutowireMethodOf(ControllerHelper::class)]
    -        private \Closure $render,
    +        private RenderInterface $render,
    ````

    Symfony's DI container will automatically create an adapter that implements `RenderInterface` and whose `__invoke` method calls the `render` method of the `ControllerHelper`. This gives full static analysis and autocompletion benefits with zero extra boilerplate code.

This pull request, therefore, not only provides a solution to a long-standing desire for more reusable controller logic but does so in a way that is modern, flexible, and fully embraces the power of Symfony's dependency injection container (while still preserving really good usability when the DIC is not used, as is the case when unit testing.)

Commits
-------

c2020bb3a6c [FrameworkBundle] Add `ControllerHelper`; the helpers from AbstractController as a standalone service