minor #6714 Added some missing deprecations related to referrer URLs (javiereguiluz)

This PR was squashed before being merged into the 4.x branch.

Discussion
----------

Added some missing deprecations related to referrer URLs

While removing these features in 5.x branch (see #6712) I realized that we were missing some deprecation messages related to referrer URLs.

Commits
-------

cfd639c Added some missing deprecations related to referrer URLs

Author: javiereguiluz

UPGRADE.md

@@ -1,6 +1,25 @@
 Upgrade between EasyAdmin 4.x versions
 ======================================
 
+EasyAdmin 4.22.0
+----------------
+
+The `referrerUrl` property and the `getReferrerUrl()` method of `BatchActionDto`
+are deprecated. This is similar to the rest of deprecations of features related
+to the "referrer URL".
+
+The referrer URL is now handled automatically inside EasyAdmin. In your own
+batch actions, you can redirect to a specific URL (built with the `AdminUrlGenerator`)
+or get the referrer URL from the HTTP headers provided by browsers:
+
+```php
+// Before
+return $this->redirect($batchActionDto->getReferrer());
+
+// After
+return $this->redirect($adminContext->getRequest()->headers->get('referer'));
+```
+
 EasyAdmin 4.20.0
 ----------------
 

doc/actions.rst

@@ -537,7 +537,7 @@ If you do that, EasyAdmin will inject a DTO with all the batch action data::
 
             $entityManager->flush();
 
-            return $this->redirect($batchActionDto->getReferrerUrl());
+            return $this->redirectToRoute('admin_user_index');
         }
     }
 

src/ArgumentResolver/BatchActionDtoResolver.php

@@ -41,7 +41,8 @@ public function resolve(Request $request, ArgumentMetadata $argument): iterable
                 $context->getRequest()->request->all()[EA::BATCH_ACTION_ENTITY_IDS] ?? [],
                 $context->getRequest()->request->get(EA::ENTITY_FQCN),
                 $this->getReferrerUrl($context, $request),
-                $context->getRequest()->request->get(EA::BATCH_ACTION_CSRF_TOKEN)
+                $context->getRequest()->request->get(EA::BATCH_ACTION_CSRF_TOKEN),
+                false
             );
         }
 
@@ -95,7 +96,8 @@ public function resolve(Request $request, ArgumentMetadata $argument): iterable
                 $context->getRequest()->request->all()[EA::BATCH_ACTION_ENTITY_IDS] ?? [],
                 $context->getRequest()->request->get(EA::ENTITY_FQCN),
                 $this->getReferrerUrl($context, $request),
-                $context->getRequest()->request->get(EA::BATCH_ACTION_CSRF_TOKEN)
+                $context->getRequest()->request->get(EA::BATCH_ACTION_CSRF_TOKEN),
+                false
             );
         }
 

src/Contracts/Context/AdminContextInterface.php

@@ -18,6 +18,9 @@ interface AdminContextInterface
 {
     public function getRequest(): Request;
 
+    /**
+     * @deprecated since 4.8.11, will be removed in 5.0. Use $context->getRequest()->headers->get('referer') or redirect to some specific URL
+     */
     public function getReferrer(): ?string;
 
     public function getI18n(): I18nDto;

src/Dto/BatchActionDto.php

@@ -13,13 +13,32 @@ class BatchActionDto
     private string $referrerUrl;
     private string $csrfToken;
 
-    public function __construct(string $name, array $entityIds, string $entityFqcn, string $referrerUrl, string $csrfToken)
+    public function __construct(string $name, array $entityIds, string $entityFqcn, string $referrerUrl, string $csrfToken /* , bool $triggerDeprecation = true */)
     {
         $this->name = $name;
         $this->entityIds = $entityIds;
         $this->entityFqcn = $entityFqcn;
-        $this->referrerUrl = $referrerUrl;
-        $this->csrfToken = $csrfToken;
+
+        // the $referrerUrl argument is deprecated; instead of removing it, do this:
+        //   * if the user pass 5 arguments to the constructor, trigger a deprecation message
+        //     and assign the 4th argument to referrerUrl and the fifth to csrfToken;
+        //   * if the user passes 4 arguments, skip the referrer and assign the 4th to csrfToken
+        if (\func_num_args() > 4) {
+            // the sixth unofficial argument allows to skip deprecations when using this method by our own code
+            if (5 === \func_num_args() || (6 === \func_num_args() && false !== func_get_arg(5))) {
+                trigger_deprecation(
+                    'easycorp/easyadmin-bundle',
+                    '4.22.0',
+                    'Passing the referrer URL to the "%s" constructor is deprecated. The referrer URL will now be determined automatically based on the current request.',
+                    self::class
+                );
+            }
+
+            $this->referrerUrl = $referrerUrl;
+            $this->csrfToken = $csrfToken;
+        } else {
+            $this->csrfToken = $referrerUrl;
+        }
     }
 
     public function getName(): string
@@ -39,6 +58,12 @@ public function getEntityFqcn(): string
 
     public function getReferrerUrl(): string
     {
+        trigger_deprecation(
+            'easycorp/easyadmin-bundle',
+            '4.22.0',
+            'The referrer of batch action DTOs is deprecated and it will be removed in 5.0.0. Use $adminContext->getRequest()->headers->get(\'referer\') or redirect to some specific URL.',
+        );
+
         return $this->referrerUrl;
     }
 

src/Factory/ActionFactory.php

@@ -134,7 +134,7 @@ private function processAction(string $pageName, ActionDto $actionDto, ?EntityDt
 
         if (Action::DELETE === $actionDto->getName()) {
             $actionDto->addHtmlAttributes([
-                'formaction' => $this->adminUrlGenerator->setController($adminContext->getCrud()->getControllerFqcn())->setAction(Action::DELETE)->setEntityId($entityDto->getPrimaryKeyValue())->removeReferrer()->generateUrl(),
+                'formaction' => $this->adminUrlGenerator->setController($adminContext->getCrud()->getControllerFqcn())->setAction(Action::DELETE)->setEntityId($entityDto->getPrimaryKeyValue())->generateUrl(),
                 'data-bs-toggle' => 'modal',
                 'data-bs-target' => '#modal-delete',
             ]);

src/Provider/AdminContextProvider.php

@@ -55,6 +55,13 @@ public function getRequest(): Request
 
     public function getReferrer(): ?string
     {
+        trigger_deprecation(
+            'easycorp/easyadmin-bundle',
+            '4.8.11',
+            'EasyAdmin URLs no longer include the referrer URL. If you still need it, you can get the referrer provided by browsers via $context->getRequest()->headers->get(\'referer\').',
+            __METHOD__,
+        );
+
         return $this->getContext(true)->getReferrer();
     }
 

src/Router/AdminUrlGenerator.php

@@ -159,6 +159,12 @@ public function includeReferrer(): AdminUrlGeneratorInterface
 
     public function removeReferrer(): AdminUrlGeneratorInterface
     {
+        trigger_deprecation(
+            'easycorp/easyadmin-bundle',
+            '4.9.0',
+            'Removing the referrer argument in the admin URLs via the AdminUrlGenerator::removeReferrer() method is deprecated and it will be removed in 5.0.0. The referrer will now be determined automatically based on the current request.',
+        );
+
         if (false === $this->isInitialized) {
             $this->initialize();
         }

src/Router/AdminUrlGeneratorInterface.php

@@ -32,10 +32,19 @@ public function unsetAll(): self;
 
     public function unsetAllExcept(string ...$namesOfParamsToKeep): self;
 
+    /**
+     * @deprecated since 4.9.0, will be removed in 5.0.0. The referrer will now be determined automatically based on the current request.
+     */
     public function includeReferrer(): self;
 
+    /**
+     * @deprecated since 4.9.0, will be removed in 5.0.0. The referrer will now be determined automatically based on the current request.
+     */
     public function removeReferrer(): self;
 
+    /**
+     * @deprecated since 4.9.0, will be removed in 5.0.0. The referrer will now be determined automatically based on the current request.
+     */
     public function setReferrer(string $referrer): self;
 
     public function addSignature(bool $addSignature = true): self;

tests/Context/AdminContextTest.php

@@ -17,6 +17,9 @@
 
 class AdminContextTest extends TestCase
 {
+    /**
+     * @group legacy
+     */
     public function testGetReferrerEmptyString()
     {
         $request = $this->createMock(Request::class);