Merge pull request #226 from DigitalTimK/tests/hooks

Improving Hooks

Author: GhaziTriki

.env

@@ -1,5 +1,6 @@
-# Specify the Server Base URL of your BigBlueButton
+# Specify the URL and SECRET of your BigBlueButton-Server (check on your BBB-Server with command 'bbb-conf --secret')
 BBB_SERVER_BASE_URL="https://test-install.blindsidenetworks.com/bigbluebutton/"
+BBB_SECRET="8cd8ef52e8e101574e400365b55e11a6"
 
-# Specify the value of your BigBlueButton secret
-BBB_SECRET="8cd8ef52e8e101574e400365b55e11a6"
+# SET THE HASHING ALGORITHM FOR HOOKS (BBB-SERVER < 3.0 MUST USE 'sha_1')
+HASH_ALGO_FOR_HOOKS="sha1"

src/BigBlueButton.php

@@ -83,6 +83,7 @@ class BigBlueButton
     protected array $curlOpts = [];
     protected int $timeOut    = 10;
     protected string $jSessionId;
+
     private UrlBuilder $urlBuilder;
 
     /**
@@ -611,7 +612,7 @@ private function sendRequest(string $url, string $payload = '', string $contentT
      */
     private function processXmlResponse(string $url, string $payload = ''): \SimpleXMLElement
     {
-        $response = $this->sendRequest($url, $payload, $contentType);
+        $response = $this->sendRequest($url, $payload, 'application/xml');
 
         return new \SimpleXMLElement($response);
     }

src/Parameters/HooksCreateParameters.php

@@ -22,18 +22,20 @@
 
 class HooksCreateParameters extends BaseParameters
 {
-    private ?string $callbackUrl = null;
+    private string $callbackUrl;
 
     private ?string $meetingId = null;
 
+    private ?string $eventId = null;
+
     private ?bool $getRaw = null;
 
     public function __construct(string $callbackUrl)
     {
         $this->callbackUrl = $callbackUrl;
     }
 
-    public function getCallbackUrl(): ?string
+    public function getCallbackUrl(): string
     {
         return $this->callbackUrl;
     }
@@ -57,6 +59,18 @@ public function setMeetingId(string $meetingId): self
         return $this;
     }
 
+    public function getEventId(): ?string
+    {
+        return $this->eventId;
+    }
+
+    public function setEventId(string $eventId): self
+    {
+        $this->eventId = $eventId;
+
+        return $this;
+    }
+
     public function getRaw(): ?bool
     {
         return $this->getRaw;

src/Parameters/HooksDestroyParameters.php

@@ -22,19 +22,19 @@
 
 class HooksDestroyParameters extends BaseParameters
 {
-    private ?string $hookId = null;
+    private int $hookId;
 
-    public function __construct(string $hookId = null)
+    public function __construct(int $hookId)
     {
         $this->hookId = $hookId;
     }
 
-    public function getHookId(): ?string
+    public function getHookId(): int
     {
         return $this->hookId;
     }
 
-    public function setHookId(string $hookId): self
+    public function setHookId(int $hookId): self
     {
         $this->hookId = $hookId;
 

src/Responses/HooksCreateResponse.php

@@ -25,18 +25,39 @@
  */
 class HooksCreateResponse extends BaseResponse
 {
-    public function getHookId(): int
+    /**
+     * According to documentation the hookId that needs to be used in the "destroy" command musst be of type number.
+     * That is why the return here must be a number (= integer) too.
+     *
+     * But in the same time this property could be not part of the API-response in case the response failed. So it has
+     * to return NULL as well.
+     *
+     * @see https://docs.bigbluebutton.org/development/webhooks/#hooksdestroy
+     */
+    public function getHookId(): ?int
     {
+        if (!$this->rawXml->hookID) {
+            return null;
+        }
+
         return (int) $this->rawXml->hookID->__toString();
     }
 
-    public function isPermanentHook(): bool
+    public function isPermanentHook(): ?bool
     {
+        if (!$this->rawXml->permanentHook) {
+            return null;
+        }
+
         return 'true' === $this->rawXml->permanentHook->__toString();
     }
 
-    public function hasRawData(): bool
+    public function hasRawData(): ?bool
     {
+        if (!$this->rawXml->rawData) {
+            return null;
+        }
+
         return 'true' === $this->rawXml->rawData->__toString();
     }
 }

src/Responses/HooksDestroyResponse.php

@@ -25,8 +25,12 @@
  */
 class HooksDestroyResponse extends BaseResponse
 {
-    public function removed(): bool
+    public function removed(): ?bool
     {
+        if (!$this->rawXml->removed) {
+            return null;
+        }
+
         return 'true' === $this->rawXml->removed->__toString();
     }
 }

src/Util/UrlBuilder.php

@@ -21,6 +21,7 @@
 namespace BigBlueButton\Util;
 
 use BigBlueButton\Core\ApiMethod;
+use BigBlueButton\Enum\HashingAlgorithm;
 use BigBlueButton\Parameters\CreateMeetingParameters;
 use BigBlueButton\Parameters\DeleteRecordingsParameters;
 use BigBlueButton\Parameters\EndMeetingParameters;
@@ -85,6 +86,7 @@ public function getHashingAlgorithm(): string
     }
 
     // Basic functions
+
     /**
      * Builds an API method URL that includes the url + params + its generated checksum.
      */
@@ -169,18 +171,110 @@ public function getPutRecordingTextTrackUrl(PutRecordingTextTrackParameters $put
         return $this->buildUrl(ApiMethod::PUT_RECORDING_TEXT_TRACK, $putRecordingTextTrackParams->getHTTPQuery());
     }
 
+    /**
+     * BBB-Server < 3.0 can only use SHA1 in the handling with hooks.
+     * Please configure the HASH_ALGO_FOR_HOOKS environment variable in case SHA1 shall not be used.
+     *
+     * @see https://github.com/bigbluebutton/bbb-webhooks/issues/30
+     */
     public function getHooksCreateUrl(HooksCreateParameters $hookCreateParams): string
     {
-        return $this->buildUrl(ApiMethod::HOOKS_CREATE, $hookCreateParams->getHTTPQuery());
+        // store current hashing algorithm
+        $hashingAlgorithm = $this->getHashingAlgorithm();
+
+        // change hashing algorithm for hooks
+        $this->setHashingAlgorithm($this->getHashingAlgorithmForHooks());
+
+        // build URL
+        $url = $this->buildUrl(ApiMethod::HOOKS_CREATE, $hookCreateParams->getHTTPQuery());
+
+        // reset to 'normal' hashing algorithm
+        $this->setHashingAlgorithm($hashingAlgorithm);
+
+        return $url;
     }
 
+    /**
+     * BBB-Server < 3.0 can only use SHA1 in the handling with hooks.
+     * Please configure the HASH_ALGO_FOR_HOOKS environment variable in case SHA1 shall not be used.
+     *
+     * @see https://github.com/bigbluebutton/bbb-webhooks/issues/30
+     */
     public function getHooksListUrl(): string
     {
-        return $this->buildUrl(ApiMethod::HOOKS_LIST);
+        // store current hashing algorithm
+        $hashingAlgorithm = $this->getHashingAlgorithm();
+
+        // change hashing algorithm for hooks
+        $this->setHashingAlgorithm($this->getHashingAlgorithmForHooks());
+
+        // build URL
+        $url = $this->buildUrl(ApiMethod::HOOKS_LIST);
+
+        // reset to 'normal' hashing algorithm
+        $this->setHashingAlgorithm($hashingAlgorithm);
+
+        return $url;
     }
 
+    /**
+     * BBB-Server < 3.0 can only use SHA1 in the handling with hooks.
+     * Please configure the HASH_ALGO_FOR_HOOKS environment variable in case SHA1 shall not be used.
+     *
+     * @see https://github.com/bigbluebutton/bbb-webhooks/issues/30
+     */
     public function getHooksDestroyUrl(HooksDestroyParameters $hooksDestroyParams): string
     {
-        return $this->buildUrl(ApiMethod::HOOKS_DESTROY, $hooksDestroyParams->getHTTPQuery());
+        // store current hashing algorithm
+        $hashingAlgorithm = $this->getHashingAlgorithm();
+
+        // change hashing algorithm for hooks
+        $this->setHashingAlgorithm($this->getHashingAlgorithmForHooks());
+
+        // build URL
+        $url = $this->buildUrl(ApiMethod::HOOKS_DESTROY, $hooksDestroyParams->getHTTPQuery());
+
+        // reset to 'normal' hashing algorithm
+        $this->setHashingAlgorithm($hashingAlgorithm);
+
+        return $url;
+    }
+
+    /**
+     *  This function defines the algorithm to be used for hooks.
+     *
+     *  This function will evolve in phases:
+     *    - Phase 1: SHA1 as default                 (or superseded by environment-variable HASH_ALGO_FOR_HOOKS).
+     *    - Phase 2: same algo everywhere as default (or superseded by environment-variable HASH_ALGO_FOR_HOOKS and which will trigger in this case a deprecation-warning).
+     *    - Phase 3: removal of this function, adaptation of the other hook-functions in this class and remove the use of env-variable HASH_ALGO_FOR_HOOKS.
+     *
+     *  Background:
+     *  BB-Server below 3.0 are using SHA1-algorithm for hooks only, but allow higher algorithms for
+     *  other APIs. This is creating issues since the algorithm of choice is used in the urlBuilder-class
+     *  for the hashing of the checksum. This is resulting in denied requests for hooks if the algorithm
+     *  of choice is not SHA1.
+     *  The current planning for BBB-Server 3.0 (and on) is to align the hashing algorithm for hooks with
+     *  the rest of the system. Having this in mind two situations need to be covered:
+     *    - BBB-Server <  3.0 ==> SHA1 is default for hooks (even rest is using other algorithm)
+     *    - BBB-Server >= 3.0 ==> same algorithm everywhere (according to planning).
+     *
+     * @deprecated This function will evolve in phases and will later disappear
+     */
+    private function getHashingAlgorithmForHooks(): string
+    {
+        // ---------------------------------- phase 1 ----------------------------------
+        // in case this env-variable is not set, SHA1 shall be used as default (phase 1)
+        return getenv('HASH_ALGO_FOR_HOOKS') ?: HashingAlgorithm::SHA_1;
+        // ---------------------------------- phase 1 ----------------------------------
+
+        /* ---------------------------------- phase 2 ----------------------------------
+         * if (getenv('HASH_ALGO_FOR_HOOKS')) {
+         *   trigger_error('The environment variable HASH_ALGO_FOR_HOOKS will be removed soon. This will require you to run a BBB-Server 3.0 or higher!', E_USER_DEPRECATED);
+         * }
+         *
+         * // in case this env-variable is not set, the 'normal' algorithm shall be used as default (phase 2)
+         * return getenv('HASH_ALGO_FOR_HOOKS') ?: $this->getHashingAlgorithm();
+         *
+         * ---------------------------------- phase 2 ---------------------------------- */
     }
 }

tests/BigBlueButtonTest.php

@@ -26,6 +26,8 @@
 use BigBlueButton\Parameters\EndMeetingParameters;
 use BigBlueButton\Parameters\GetMeetingInfoParameters;
 use BigBlueButton\Parameters\GetRecordingsParameters;
+use BigBlueButton\Parameters\HooksCreateParameters;
+use BigBlueButton\Parameters\HooksDestroyParameters;
 use BigBlueButton\Parameters\IsMeetingRunningParameters;
 use BigBlueButton\Parameters\PublishRecordingsParameters;
 use BigBlueButton\Util\ParamsIterator;
@@ -60,8 +62,9 @@ public function tearDown(): void
 
         // close all existing meetings
         $meetingsResponse = $this->bbb->getMeetings();
-        $meetings         = $meetingsResponse->getMeetings();
+        $this->assertTrue($meetingsResponse->success(), $meetingsResponse->getMessage());
 
+        $meetings = $meetingsResponse->getMeetings();
         foreach ($meetings as $meeting) {
             $endMeetingParameters = new EndMeetingParameters($meeting->getMeetingId(), $meeting->getModeratorPassword());
             $endMeetingResponse   = $this->bbb->endMeeting($endMeetingParameters);
@@ -86,7 +89,7 @@ public function testApiVersion(): void
     // Create Meeting
 
     /**
-     * @deprecated Test will be removed together with the deprecated function from BigBlueButton::class
+     * @deprecated test will be removed together with the deprecated function from BigBlueButton::class
      *
      * Test create meeting URL
      */
@@ -176,7 +179,7 @@ public function testCreateMeetingWithMultiDocument(): void
     // Join Meeting
 
     /**
-     * @deprecated Test will be removed together with the deprecated function from BigBlueButton::class
+     * @deprecated test will be removed together with the deprecated function from BigBlueButton::class
      *
      * Test create join meeting URL
      */
@@ -230,7 +233,7 @@ public function testJoinMeeting(): void
     // End Meeting
 
     /**
-     * @deprecated Test will be removed together with the deprecated function from BigBlueButton::class
+     * @deprecated test will be removed together with the deprecated function from BigBlueButton::class
      *
      * Test generate end meeting URL
      */
@@ -400,6 +403,43 @@ public function testUpdateRecordings(): void
         $this->assertTrue($result->failed());
     }
 
+    // Hooks: create
+
+    public function testHooksCreate(): void
+    {
+        // create a hook
+        $hooksCreateParameters = new HooksCreateParameters($this->faker->url);
+        $hooksCreateResponse   = $this->bbb->hooksCreate($hooksCreateParameters);
+        $this->assertTrue($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
+    }
+
+    public function testHooksList(): void
+    {
+        // create a hook
+        $hooksListResponse = $this->bbb->hooksList();
+        $this->assertTrue($hooksListResponse->success(), $hooksListResponse->getMessage());
+    }
+
+    public function testHooksDestroy(): void
+    {
+        // create a hook
+        $hooksCreateParameters = new HooksCreateParameters($this->faker->url);
+        $hooksCreateResponse   = $this->bbb->hooksCreate($hooksCreateParameters);
+        $this->assertTrue($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
+        $hookId = $hooksCreateResponse->getHookId();
+        $this->assertNotNull($hookId);
+
+        // destroy existing hook
+        $hooksDestroyParameters = new HooksDestroyParameters($hookId);
+        $hooksCreateResponse    = $this->bbb->hooksDestroy($hooksDestroyParameters);
+        $this->assertTrue($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
+
+        // destroy non-existing hook
+        $hooksDestroyParameters = new HooksDestroyParameters($this->faker->numberBetween(10000, 99999));
+        $hooksCreateResponse    = $this->bbb->hooksDestroy($hooksDestroyParameters);
+        $this->assertFalse($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
+    }
+
     /**
      * @see https://github.com/vlucas/phpdotenv
      */

tests/Parameters/HooksCreateParametersTest.php

@@ -31,14 +31,23 @@ class HooksCreateParametersTest extends TestCase
 {
     public function testHooksCreateParameters(): void
     {
+        // create string of eventIds
+        $eventIds = [];
+        for ($i = 0; $i < $this->faker->numberBetween(1, 5); ++$i) {
+            $eventIds[] = $this->faker->uuid;
+        }
+        $eventIds = implode(',', $eventIds);
+
         $hooksCreateParameters = new HooksCreateParameters($callBackUrl = $this->faker->url);
 
         $this->assertEquals($callBackUrl, $hooksCreateParameters->getCallbackUrl());
 
         // Test setters that are ignored by the constructor
         $hooksCreateParameters->setMeetingId($meetingId = $this->faker->uuid);
         $hooksCreateParameters->setGetRaw($getRaw = $this->faker->boolean);
+        $hooksCreateParameters->setEventId($eventIds);
         $this->assertEquals($meetingId, $hooksCreateParameters->getMeetingId());
         $this->assertEquals($getRaw, $hooksCreateParameters->getRaw());
+        $this->assertEquals($eventIds, $hooksCreateParameters->getEventId());
     }
 }