feature #40799 [FrameworkBundle] Add AbstractController::handleForm() helper (dunglas)

This PR was squashed before being merged into the 5.3-dev branch.

Discussion
----------

[FrameworkBundle] Add AbstractController::handleForm() helper

| Q             | A
| ------------- | ---
| Branch?       | 5.x
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       | n/a
| License       | MIT
| Doc PR        | symfony/symfony-docs#15217

Some libraries such as Turbo require to strictly follow the HTTP specification (and especially to use proper status codes) to deal with forms.

In symfony/symfony#39843, I introduced a new `renderForm()` helper for this purpose. But I'm not very satisfied by it. The current approach has several problems:

1. It calls `$form->isValid()` two times, which may hurt performance
2. It sets the proper status code in case of validation error (422), but not for the redirection when the entity is created or updated (306). The user must do this manually (and so be aware of these HTTP subtleties).
3. It hides the verbosity of the Form component a bit, but I'm a sure that we can reduce it more

This PR proposes an alternative helper, `handleForm()`, which handles automatically 80% of the use cases, provide an extension point for the other 20%, and can also serve as a quick example for users to handle form in a custom way (by control-clicking on the function to see the code and copy/paste/adapt it).

* if the form is not submitted, the Twig template passed in $view is rendered and a 200 HTTP status code is set
* if the form is submitted but invalid, the Twig template passed in $view is rendered and 422 HTTP status code is set
* if the form is submitted and valid, the entity is saved (only if it is managed by Doctrine ORM), a 306 HTTP status code is set and the Location HTTP header is set to the value of $redirectUrl

Before (standard case):

```php
    #[Route('/{id}/edit', name: 'conference_edit', methods: ['GET', 'POST'])]
    public function edit(Request $request, Conference $conference): Response
    {
        $form = $this->createForm(ConferenceType::class, $conference);
        $form->handleRequest($request);

        $submitted = $form->isSubmitted();
        $valid = $submitted && $form->isValid();

        if ($valid) {
            $this->getDoctrine()->getManager()->flush();

            return $this->redirectToRoute('conference_index', [], Response::HTTP_SEE_OTHER);
        }

        $response = $this->render('conference/edit.html.twig', [
            'conference' => $conference,
            'form' => $form->createView(),
        ]);
        if ($submitted && !$valid) {
            $response->setStatusCode(Response::HTTP_UNPROCESSABLE_ENTITY);
        }

        return $response;
    }
```

With the new helper:

```php
    #[Route('/{id}/edit', name: 'conference_edit', methods: ['GET', 'POST'])]
    public function edit(Request $request, Conference $conference): Response
    {
        $form = $this->createForm(ConferenceType::class, $conference);
        return $this->handleForm(
            $request,
            $form,
            view: 'conference/edit.html.twig',
            redirectUrl: $this->generateUrl('conference_index')
        );
    }
```

Before (more advanced use case):

```php
    #[Route('/{id}/edit', name: 'conference_edit', methods: ['GET', 'POST'])]
    public function edit(Request $request, Conference $conference, HubInterface $hub): Response
    {
        $form = $this->createForm(ConferenceType::class, $conference);
        $form->handleRequest($request);

        $submitted = $form->isSubmitted();
        $valid = $submitted && $form->isValid();

        if ($valid) {
            $this->getDoctrine()->getManager()->flush();

            $hub->publish(
                new Update(
                    'conference:'.$conference->getId(),
                    $this->renderView('conference/edit.stream.html.twig', ['conference' => $conference])
                )
            );

            return $this->redirectToRoute('conference_index', [], Response::HTTP_SEE_OTHER);
        }

        $response = $this->render('conference/edit.html.twig', [
            'conference' => $conference,
            'form' => $form->createView(),
        ]);
        if ($submitted && !$valid) {
            $response->setStatusCode(Response::HTTP_UNPROCESSABLE_ENTITY);
        }

        return $response;
    }
```

With the new helper (more advanced case):

```php
    #[Route('/{id}/edit', name: 'conference_edit', methods: ['GET', 'POST'])]
    public function edit(Request $request, Conference $conference, HubInterface $hub): Response
    {
        $form = $this->createForm(ConferenceType::class, $conference);
        $response = $this->handleForm(
            $request,
            $form,
            view: 'conference/edit.html.twig',
            redirectUrl: $this->generateUrl('conference_index')
        );

        if ($response->isRedirection()) {
            $hub->publish(
                new Update(
                    'conference:' . $conference->getId(),
                    $this->renderView('conference/edit.stream.html.twig', ['conference' => $conference])
                )
            );
        }

        return $response;
    }
```

This also works without named parameters. I also considered passing a callback to be executed on success, but I'm happier with the current solution.

WDYT?

TODO:

* [x] update tests

Commits
-------

5228546066 [FrameworkBundle] Add AbstractController::handleForm() helper

Author: nicolas-grekas

CHANGELOG.md

@@ -7,7 +7,7 @@ CHANGELOG
  * Deprecate the `session.storage` alias and `session.storage.*` services, use the `session.storage.factory` alias and `session.storage.factory.*` services instead
  * Deprecate the `framework.session.storage_id` configuration option, use the `framework.session.storage_factory_id` configuration option instead
  * Deprecate the `session` service and the `SessionInterface` alias, use the `Request::getSession()` or the new `RequestStack::getSession()` methods instead
- * Added `AbstractController::renderForm()` to render a form and set the appropriate HTTP status code
+ * Added `AbstractController::handleForm()` to handle a form and set the appropriate HTTP status code
  * Added support for configuring PHP error level to log levels
  * Added the `dispatcher` option to `debug:event-dispatcher`
  * Added the `event_dispatcher.dispatcher` tag

Controller/AbstractController.php

@@ -291,15 +291,28 @@ protected function stream(string $view, array $parameters = [], StreamedResponse
     }
 
     /**
-     * Renders a form.
+     * Handles a form.
      *
-     * The FormView instance is passed to the template in a variable named "form".
-     * If the form is invalid, a 422 status code is returned.
+     * * if the form is not submitted, $render is called
+     * * if the form is submitted but invalid, $render is called and a 422 HTTP status code is set if the current status hasn't been customized
+     * * if the form is submitted and valid, $onSuccess is called, usually this method saves the data and returns a 303 HTTP redirection
+     *
+     * @param callable(FormInterface, mixed): Response $onSuccess
+     * @param callable(FormInterface, mixed): Response $render
      */
-    public function renderForm(string $view, FormInterface $form, array $parameters = [], Response $response = null): Response
+    public function handleForm(FormInterface $form, Request $request, callable $onSuccess, callable $render): Response
     {
-        $response = $this->render($view, ['form' => $form->createView()] + $parameters, $response);
-        if ($form->isSubmitted() && !$form->isValid()) {
+        $form->handleRequest($request);
+
+        $submitted = $form->isSubmitted();
+
+        $data = $form->getData();
+        if ($submitted && $form->isValid()) {
+            return $onSuccess($form, $data);
+        }
+
+        $response = $render($form, $data);
+        if ($submitted && 200 === $response->getStatusCode()) {
             $response->setStatusCode(Response::HTTP_UNPROCESSABLE_ENTITY);
         }
 

Tests/Controller/AbstractControllerTest.php

@@ -23,7 +23,6 @@
 use Symfony\Component\Form\FormConfigInterface;
 use Symfony\Component\Form\FormFactoryInterface;
 use Symfony\Component\Form\FormInterface;
-use Symfony\Component\Form\FormView;
 use Symfony\Component\HttpFoundation\BinaryFileResponse;
 use Symfony\Component\HttpFoundation\File\Exception\FileNotFoundException;
 use Symfony\Component\HttpFoundation\File\File;
@@ -425,50 +424,70 @@ public function testStreamTwig()
         $this->assertInstanceOf(StreamedResponse::class, $controller->stream('foo'));
     }
 
-    public function testRenderFormTwig()
+    public function testHandleFormNotSubmitted()
     {
-        $formView = new FormView();
-
         $form = $this->createMock(FormInterface::class);
-        $form->expects($this->once())->method('createView')->willReturn($formView);
-
-        $twig = $this->createMock(Environment::class);
-        $twig->expects($this->once())->method('render')->with('foo', ['form' => $formView, 'bar' => 'bar'])->willReturn('bar');
-
-        $container = new Container();
-        $container->set('twig', $twig);
+        $form->expects($this->once())->method('isSubmitted')->willReturn(false);
 
         $controller = $this->createController();
-        $controller->setContainer($container);
-
-        $response = $controller->renderForm('foo', $form, ['bar' => 'bar']);
+        $response = $controller->handleForm(
+            $form,
+            Request::create('https://example.com'),
+            function (FormInterface $form, $data): Response {
+                return new RedirectResponse('https://example.com/redir', Response::HTTP_SEE_OTHER);
+            },
+            function (FormInterface $form, $data): Response {
+                return new Response('rendered');
+            }
+        );
 
         $this->assertTrue($response->isSuccessful());
-        $this->assertSame('bar', $response->getContent());
+        $this->assertSame('rendered', $response->getContent());
     }
 
-    public function testRenderInvalidFormTwig()
+    public function testHandleFormInvalid()
     {
-        $formView = new FormView();
-
         $form = $this->createMock(FormInterface::class);
-        $form->expects($this->once())->method('createView')->willReturn($formView);
         $form->expects($this->once())->method('isSubmitted')->willReturn(true);
         $form->expects($this->once())->method('isValid')->willReturn(false);
 
-        $twig = $this->createMock(Environment::class);
-        $twig->expects($this->once())->method('render')->with('foo', ['form' => $formView, 'bar' => 'bar'])->willReturn('bar');
+        $controller = $this->createController();
+        $response = $controller->handleForm(
+            $form,
+            Request::create('https://example.com'),
+            function (FormInterface $form): Response {
+                return new RedirectResponse('https://example.com/redir', Response::HTTP_SEE_OTHER);
+            },
+            function (FormInterface $form): Response {
+                return new Response('rendered');
+            }
+        );
 
-        $container = new Container();
-        $container->set('twig', $twig);
+        $this->assertSame(Response::HTTP_UNPROCESSABLE_ENTITY, $response->getStatusCode());
+        $this->assertSame('rendered', $response->getContent());
+    }
 
-        $controller = $this->createController();
-        $controller->setContainer($container);
+    public function testHandleFormValid()
+    {
+        $form = $this->createMock(FormInterface::class);
+        $form->expects($this->once())->method('isSubmitted')->willReturn(true);
+        $form->expects($this->once())->method('isValid')->willReturn(true);
 
-        $response = $controller->renderForm('foo', $form, ['bar' => 'bar']);
+        $controller = $this->createController();
+        $response = $controller->handleForm(
+            $form,
+            Request::create('https://example.com'),
+            function (FormInterface $form): Response {
+                return new RedirectResponse('https://example.com/redir', Response::HTTP_SEE_OTHER);
+            },
+            function (FormInterface $form): Response {
+                return new Response('rendered');
+            }
+        );
 
-        $this->assertSame(Response::HTTP_UNPROCESSABLE_ENTITY, $response->getStatusCode());
-        $this->assertSame('bar', $response->getContent());
+        $this->assertInstanceOf(RedirectResponse::class, $response);
+        $this->assertSame(Response::HTTP_SEE_OTHER, $response->getStatusCode());
+        $this->assertSame('https://example.com/redir', $response->getTargetUrl());
     }
 
     public function testRedirectToRoute()