Merge branch 'master' into tests/coverage

Author: DigitalTimK

.env

@@ -1,5 +1,6 @@
-# Specify the value of your BigBlueButton secret
+# 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 Server Base URL of your BigBlueButton
-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

@@ -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/HooksCreateParameters.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/Parameters/HooksDestroyParameters.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/HooksCreateResponse.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/Responses/HooksDestroyResponse.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;
@@ -36,46 +37,72 @@
 use BigBlueButton\Parameters\PutRecordingTextTrackParameters;
 use BigBlueButton\Parameters\UpdateRecordingsParameters;
 
-/**
- * Class UrlBuilder.
- */
 class UrlBuilder
 {
+    /** @deprecated Property will be private soon. Use setter/getter instead. */
     protected string $hashingAlgorithm;
 
-    private string $securitySalt;
+    private string $secret;
 
-    private string $bbbServerBaseUrl;
+    private string $baseUrl;
 
-    public function __construct(string $secret, string $serverBaseUrl, string $hashingAlgorithm)
+    public function __construct(string $secret, string $baseUrl, string $hashingAlgorithm)
     {
-        $this->securitySalt     = $secret;
-        $this->bbbServerBaseUrl = $serverBaseUrl;
-        $this->hashingAlgorithm = $hashingAlgorithm;
+        $this->setSecret($secret);
+        $this->setBaseUrl($baseUrl);
+        $this->setHashingAlgorithm($hashingAlgorithm);
     }
 
-    /**
-     * Sets the hashing algorithm.
-     */
-    public function setHashingAlgorithm(string $hashingAlgorithm): void
+    // Getters & Setters
+    public function setSecret(string $secret): self
+    {
+        $this->secret = $secret;
+
+        return $this;
+    }
+
+    public function setBaseUrl(string $baseUrl): self
+    {
+        // add tailing dir-separator if missing
+        if ('/' != mb_substr($baseUrl, -1)) {
+            $baseUrl .= '/';
+        }
+
+        $this->baseUrl = $baseUrl;
+
+        return $this;
+    }
+
+    public function setHashingAlgorithm(string $hashingAlgorithm): self
     {
         $this->hashingAlgorithm = $hashingAlgorithm;
+
+        return $this;
+    }
+
+    public function getHashingAlgorithm(): string
+    {
+        return $this->hashingAlgorithm;
     }
 
+    // Basic functions
+
     /**
      * Builds an API method URL that includes the url + params + its generated checksum.
      */
     public function buildUrl(string $method = '', string $params = '', bool $append = true): string
     {
-        return $this->bbbServerBaseUrl . 'api/' . $method . ($append ? '?' . $this->buildQs($method, $params) : '');
+        return $this->baseUrl . 'api/' . $method . ($append ? '?' . $this->buildQs($method, $params) : '');
     }
 
     /**
      * Builds a query string for an API method URL that includes the params + its generated checksum.
+     *
+     * @deprecated Function only used internal. Function will be private soon. No replacement.
      */
     public function buildQs(string $method = '', string $params = ''): string
     {
-        return $params . '&checksum=' . hash($this->hashingAlgorithm, $method . $params . $this->securitySalt);
+        return $params . '&checksum=' . hash($this->hashingAlgorithm, $method . $params . $this->secret);
     }
 
     // URL-Generators
@@ -144,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 ---------------------------------- */
     }
 }