Adding return URL parameter into extension URL generator endpoint.

Author: krulis-martin

app/V1Module/presenters/ExtensionsPresenter.php

@@ -60,8 +60,9 @@ public function checkUrl(string $extId, string $instanceId)
      * Return URL refering to the extension with properly injected temporary JWT token.
      * @GET
      * @Param(type="query", name="locale", required=false, validation="string:2")
+     * @Param(type="query", name="return", required=false, validation="string")
      */
-    public function actionUrl(string $extId, string $instanceId, ?string $locale)
+    public function actionUrl(string $extId, string $instanceId, ?string $locale, ?string $return)
     {
         $user = $this->getCurrentUser();
         $extension = $this->extensions->getExtension($extId);
@@ -78,7 +79,7 @@ public function actionUrl(string $extId, string $instanceId, ?string $locale)
             $locale = $this->getCurrentUserLocale();
         }
 
-        $this->sendSuccessResponse($extension->getUrl($token, $locale));
+        $this->sendSuccessResponse($extension->getUrl($token, $locale, $return ?? ''));
     }
 
     public function checkToken(string $extId)

app/V1Module/presenters/NotificationsPresenter.php

@@ -103,10 +103,14 @@ public function checkCreate()
 
     /**
      * Create notification with given attributes
-     * @Param(type="post", name="groupsIds", validation="array", description="Identification of groups")
-     * @Param(type="post", name="visibleFrom", validation="timestamp", description="Date from which is notification visible")
-     * @Param(type="post", name="visibleTo", validation="timestamp", description="Date to which is notification visible")
-     * @Param(type="post", name="role", validation="string:1..", description="Users with this role and its children can see notification")
+     * @Param(type="post", name="groupsIds", validation="array",
+     *        description="Identification of groups")
+     * @Param(type="post", name="visibleFrom", validation="timestamp",
+     *        description="Date from which is notification visible")
+     * @Param(type="post", name="visibleTo", validation="timestamp",
+     *        description="Date to which is notification visible")
+     * @Param(type="post", name="role", validation="string:1..",
+     *        description="Users with this role and its children can see notification")
      * @Param(type="post", name="type", validation="string", description="Type of the notification (custom)")
      * @Param(type="post", name="localizedTexts", validation="array", description="Text of notification")
      * @POST
@@ -218,9 +222,12 @@ public function checkUpdate(string $id)
      * @POST
      * @param string $id
      * @Param(type="post", name="groupsIds", validation="array", description="Identification of groups")
-     * @Param(type="post", name="visibleFrom", validation="timestamp", description="Date from which is notification visible")
-     * @Param(type="post", name="visibleTo", validation="timestamp", description="Date to which is notification visible")
-     * @Param(type="post", name="role", validation="string:1..", description="Users with this role and its children can see notification")
+     * @Param(type="post", name="visibleFrom", validation="timestamp",
+     *        description="Date from which is notification visible")
+     * @Param(type="post", name="visibleTo", validation="timestamp",
+     *        description="Date to which is notification visible")
+     * @Param(type="post", name="role", validation="string:1..",
+     *        description="Users with this role and its children can see notification")
      * @Param(type="post", name="type", validation="string", description="Type of the notification (custom)")
      * @Param(type="post", name="localizedTexts", validation="array", description="Text of notification")
      * @throws NotFoundException

app/config/config.local.neon.example

@@ -80,7 +80,8 @@ parameters:
       caption:  # to be displayed in UI; could be also single string (for all localizations)
         cs: "Český popisek"
         en: "English Caption"
-      url: "https://extetrnal.domain.com/recodex/extension?token={token}&locale={locale}"  # '{token}' and '{locale}' are placeholders
+      # in URL, '{*}' are placeholders for auth token, locale (en/cs), and return URL
+      url: "https://extetrnal.domain.com/recodex/extension?token={token}&locale={locale}&return={return}"
       urlTokenExpiration: 60  # [s] how long a temporary url token lasts
       token:  # generated from tmp tokens passed via URL so the ext. tool can access ReCodEx API
         expiration: 86400  # [s] how long a full token lasts

app/helpers/Extensions/ExtensionConfig.php

@@ -31,6 +31,7 @@ class ExtensionConfig
      * URL template for the external service. The template may hold the following placeholders:
      * - {token} - will be replaced with URL-encoded temporary token
      * - {locale} - will be replaced with a language identifier ('en', 'cs', ...) based on currently selected language
+     * - {return} - will be replaced with a return URL (so the user can be returned back from the ext to the same page)
      */
     private string $url;
 
@@ -118,16 +119,18 @@ public function getCaption(): string|array
     }
 
     /**
-     * Get formatted URL. A template is injected a token and current locale.
+     * Get formatted URL. A template is injected a token, current locale, and return URL.
      * @param string $token already serialized JWT
      * @param string $locale language identification ('en', 'cs', ...)
+     * @param string $return URL to which the user should return from the extension
      * @return string an instantiated URL template
      */
-    public function getUrl(string $token, string $locale): string
+    public function getUrl(string $token, string $locale = '', string $return = ''): string
     {
         $url = $this->url;
         $url = str_replace('{token}', urlencode($token), $url);
         $url = str_replace('{locale}', urlencode($locale), $url);
+        $url = str_replace('{return}', urlencode($return), $url);
         return $url;
     }
 

tests/Presenters/ExtensionsPresenter.phpt

@@ -86,18 +86,19 @@ class TestExtensionsPresenter extends Tester\TestCase
         $currentUser = PresenterTestHelper::getUser($this->container, "submitUser1@example.com");
         $instanceId = $currentUser->getInstances()->first()->getId();
 
-        $this->injectExtension('test', 'Test', 'https://test.example.com/{token}/{locale}');
+        $this->injectExtension('test', 'Test', 'https://test.example.com/{token}/{locale}?return={return}');
+        $returnUrl = 'http://back.com?foo=bar';
 
         $payload = PresenterTestHelper::performPresenterRequest(
             $this->presenter,
             'V1:Extensions',
             'GET',
-            ['action' => 'url', 'extId' => 'test', 'instanceId' => $instanceId, 'locale' => 'de']
+            ['action' => 'url', 'extId' => 'test', 'instanceId' => $instanceId, 'locale' => 'de', 'return' => $returnUrl]
         );
 
         Assert::type('string', $payload);
         Assert::true(str_starts_with($payload, 'https://test.example.com/'));
-        Assert::true(str_ends_with($payload, '/de'));
+        Assert::true(str_ends_with($payload, '/de?return=' . urlencode($returnUrl)));
         $tokens = explode('/', $payload);
         Assert::count(5, $tokens);
         $token = $this->accessManager->decodeToken($tokens[3]);

tests/Presenters/NotificationsPresenter.phpt

@@ -75,13 +75,13 @@ class TestNotificationsPresenter extends Tester\TestCase
         PresenterTestHelper::loginDefaultAdmin($this->container);
         // Demo group does not have notification,
         // so only one global should be returned
-        $group = current(
-            $this->presenter->groups->findFiltered(
-                null,
-                null,
-                "Demo group"
-            )
+        $groups = $this->presenter->groups->findFiltered(
+            null,
+            null,
+            "Demo group"
         );
+        Assert::count(1, $groups);
+        $group = current($groups);
 
         $request = new Nette\Application\Request(
             "V1:Notifications",