Merge branch 'develop' into enhancement/nativeEnums

# Conflicts:
#	composer.json
#	src/Parameters/CreateMeetingParameters.php
#	src/Parameters/JoinMeetingParameters.php
#	tests/BigBlueButtonTest.php
#	tests/Parameters/CreateMeetingParametersTest.php

Author: GhaziTriki

composer.json

@@ -14,6 +14,11 @@
       "name": "Ghazi Triki",
       "email": "ghazi.triki@riadvice.tn",
       "role": "Developer"
+    },
+    {
+      "name": "Tim Korn",
+      "email": "korn@aufKurs.de",
+      "role": "Developer"
     }
   ],
   "repositories": {
@@ -25,24 +30,24 @@
   "require": {
     "php": ">=8.1",
     "ext-curl": "*",
-    "ext-simplexml": "*",
+    "ext-json": "*",
     "ext-mbstring": "*",
-    "ext-json": "*"
+    "ext-simplexml": "*"
   },
   "require-dev": {
-    "phpunit/phpunit": "^10.5",
+    "bmitch/churn-php": "^1.7",
+    "captainhook/captainhook": "^5.23",
+    "captainhook/hook-installer": "^1.0",
     "fakerphp/faker": "^1.23",
     "friendsofphp/php-cs-fixer": "^3.54",
-    "squizlabs/php_codesniffer": "^3.9",
     "nunomaduro/phpinsights": "^2.11",
-    "bmitch/churn-php": "^1.7",
-    "wapmorgan/php-deprecation-detector": "^2.0",
     "phpstan/phpstan": "^1.10",
+    "phpunit/php-code-coverage": "^10.1",
+    "phpunit/phpunit": "^10.5",
+    "squizlabs/php_codesniffer": "^3.9",
     "tracy/tracy": "^2.10",
     "vlucas/phpdotenv": "^5.6",
-    "phpunit/php-code-coverage": "^10.1",
-    "captainhook/captainhook": "^5.23",
-    "captainhook/hook-installer": "^1.0"
+    "wapmorgan/php-deprecation-detector": "^2.0"
   },
   "scripts": {
     "code-check": "./vendor/bin/phpstan analyse",
@@ -70,6 +75,7 @@
     }
   },
   "config": {
+    "sort-packages": true,
     "allow-plugins": {
       "dealerdirect/phpcodesniffer-composer-installer": true,
       "captainhook/captainhook-phar": true,

phpunit.xml.dist

@@ -22,6 +22,11 @@
       <directory>tests</directory>
     </testsuite>
   </testsuites>
+  <groups>
+    <exclude>
+      <group>ignore</group>
+    </exclude>
+  </groups>
   <source>
     <include>
       <directory suffix=".php">src</directory>

src/Attribute/ApiParameterMapper.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * BigBlueButton open source conferencing system - https://www.bigbluebutton.org/.
+ *
+ * Copyright (c) 2016-2024 BigBlueButton Inc. and by respective authors (see below).
+ *
+ * This program is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation; either version 3.0 of the License, or (at your option) any later
+ * version.
+ *
+ * BigBlueButton is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License along
+ * with BigBlueButton; if not, see <https://www.gnu.org/licenses/>.
+ */
+
+namespace BigBlueButton\Attribute;
+
+#[\Attribute(\Attribute::TARGET_METHOD)]
+class ApiParameterMapper
+{
+    private string $attributeName;
+
+    public function __construct(string $attributeName)
+    {
+        $this->attributeName = $attributeName;
+    }
+
+    public function getAttributeName(): string
+    {
+        return $this->attributeName;
+    }
+}

src/BigBlueButton.php

@@ -94,13 +94,13 @@ public function __construct(?string $baseUrl = null, ?string $secret = null, ?ar
     {
         // Provide an early error message if configuration is wrong
         if (is_null($baseUrl) && false === getenv('BBB_SERVER_BASE_URL')) {
-            throw new \RuntimeException('No BBB-Server-Url found! Please provide it either in constructor ' .
-                "(1st argument) or by environment variable 'BBB_SERVER_BASE_URL'!");
+            throw new \RuntimeException('No BBB-Server-Url found! Please provide it either in constructor '
+                . "(1st argument) or by environment variable 'BBB_SERVER_BASE_URL'!");
         }
 
         if (is_null($secret) && false === getenv('BBB_SECRET') && false === getenv('BBB_SECURITY_SALT')) {
-            throw new \RuntimeException('No BBB-Secret (or BBB-Salt) found! Please provide it either in constructor ' .
-                "(2nd argument) or by environment variable 'BBB_SECRET' (or 'BBB_SECURITY_SALT')!");
+            throw new \RuntimeException('No BBB-Secret (or BBB-Salt) found! Please provide it either in constructor '
+                . "(2nd argument) or by environment variable 'BBB_SECRET' (or 'BBB_SECURITY_SALT')!");
         }
 
         // Keeping backward compatibility with older deployed versions
@@ -302,11 +302,9 @@ public function getRecordingsUrl(GetRecordingsParameters $recordingsParams): str
     }
 
     /**
-     * @param mixed $recordingParams
-     *
      * @throws BadResponseException|\RuntimeException
      */
-    public function getRecordings($recordingParams): GetRecordingsResponse
+    public function getRecordings(GetRecordingsParameters $recordingParams): GetRecordingsResponse
     {
         $xml = $this->processXmlResponse($this->getUrlBuilder()->getRecordingsUrl($recordingParams));
 
@@ -414,11 +412,9 @@ public function getHooksCreateUrl(HooksCreateParameters $hookCreateParams): stri
     }
 
     /**
-     * @param mixed $hookCreateParams
-     *
      * @throws BadResponseException
      */
-    public function hooksCreate($hookCreateParams): HooksCreateResponse
+    public function hooksCreate(HooksCreateParameters $hookCreateParams): HooksCreateResponse
     {
         $xml = $this->processXmlResponse($this->getUrlBuilder()->getHooksCreateUrl($hookCreateParams));
 
@@ -452,11 +448,9 @@ public function getHooksDestroyUrl(HooksDestroyParameters $hooksDestroyParams):
     }
 
     /**
-     * @param mixed $hooksDestroyParams
-     *
      * @throws BadResponseException
      */
-    public function hooksDestroy($hooksDestroyParams): HooksDestroyResponse
+    public function hooksDestroy(HooksDestroyParameters $hooksDestroyParams): HooksDestroyResponse
     {
         $xml = $this->processXmlResponse($this->getUrlBuilder()->getHooksDestroyUrl($hooksDestroyParams));
 
@@ -538,10 +532,9 @@ private function sendRequest(string $url, string $payload = '', string $contentT
         $ch         = curl_init();
         $cookieFile = tmpfile();
 
-        if (!$ch) {  // @phpstan-ignore-line
-            throw new \RuntimeException('Unhandled curl error: ' . curl_error($ch));
+        if (false === $ch) {
+            throw new \RuntimeException('Failed to initialize cURL');
         }
-
         // JSESSIONID
         if ($cookieFile) {
             $cookieFilePath = stream_get_meta_data($cookieFile)['uri'];
@@ -550,26 +543,34 @@ private function sendRequest(string $url, string $payload = '', string $contentT
             curl_setopt($ch, CURLOPT_COOKIEFILE, $cookieFilePath);
             curl_setopt($ch, CURLOPT_COOKIEJAR, $cookieFilePath);
 
-            if ($cookies) {
-                if (false !== mb_strpos($cookies, 'JSESSIONID')) {
-                    preg_match('/(?:JSESSIONID\s*)(?<JSESSIONID>.*)/', $cookies, $output_array);
-                    $this->setJSessionId($output_array['JSESSIONID']);
+            if ($cookies && false !== mb_strpos($cookies, 'JSESSIONID')) {
+                if (preg_match('/JSESSIONID\s*(?<JSESSIONID>[^;\s]*)/', $cookies, $output_array)) {
+                    // No need for isset() - we know JSESSIONID exists if preg_match returns true
+                    $this->setJSessionId(mb_trim($output_array['JSESSIONID']));
+                } else {
+                    throw new \RuntimeException('JSESSIONID found but could not be extracted');
                 }
             }
         }
 
+        // Initialise headers array with mandatory Content-type
+        $headers = [
+            'Content-type: ' . $contentType,
+        ];
+
         // PAYLOAD
         if (!empty($payload)) {
             curl_setopt($ch, CURLOPT_HEADER, 0);
             curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
             curl_setopt($ch, CURLOPT_POST, 1);
             curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
-            curl_setopt($ch, CURLOPT_HTTPHEADER, [
-                'Content-type: ' . $contentType,
-                'Content-length: ' . strlen($payload),
-            ]);
+            // Add Content-length header if payload is present
+            $headers[] = 'Content-length: ' . strlen($payload);
         }
 
+        // Set HTTP headers
+        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
+
         // OTHERS
         foreach ($this->curlOpts as $opt => $value) {
             curl_setopt($ch, $opt, $value);

src/Core/Track.php

@@ -35,10 +35,7 @@ class Track
 
     private string $source;
 
-    /**
-     * @param mixed $track
-     */
-    public function __construct($track)
+    public function __construct(mixed $track)
     {
         $this->href   = $track->href;
         $this->kind   = $track->kind;

src/Parameters/BaseParameters.php

@@ -20,18 +20,128 @@
 
 namespace BigBlueButton\Parameters;
 
+use BigBlueButton\Attribute\ApiParameterMapper;
+
 /**
  * Class BaseParameters.
  */
 abstract class BaseParameters
 {
-    abstract public function getHTTPQuery(): string;
+    public function getHTTPQuery(): string
+    {
+        $apiData = $this->toApiDataArray();
+
+        // No need for null checks anymore since toApiDataArray() filters them out
+        foreach ($apiData as $value) {
+            if (!is_string($value)) {
+                throw new \RuntimeException(sprintf(
+                    'Invalid API parameter type: %s',
+                    gettype($value)
+                ));
+            }
+        }
+
+        return $this->buildHTTPQuery($apiData);
+    }
+
+    /**
+     * @return array<string, null|string> // Keys are strings, values are strings or null
+     */
+    public function toApiDataArray(): array
+    {
+        $result          = [];
+        $classReflection = new \ReflectionClass($this);
+
+        foreach ($classReflection->getMethods() as $method) {
+            foreach ($method->getAttributes(ApiParameterMapper::class) as $attribute) {
+                /** @var ApiParameterMapper $attributeObject */
+                $attributeObject = $attribute->newInstance();
+                $key             = $attributeObject->getAttributeName();
+                $value           = $this->strictConvertToApiValue($this->{$method->getName()}());
+
+                // Only include non-null values
+                if (null !== $value) {
+                    $result[$key] = $value;
+                }
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * @param array<string, null|string> $array // Keys and values are both strings
+     */
+    protected function buildHTTPQuery(array $array): string
+    {
+        return str_replace(
+            ['%20', '!', "'", '(', ')', '*'],
+            ['+', '%21', '%27', '%28', '%29', '%2A'],
+            http_build_query($array, '', '&', \PHP_QUERY_RFC3986)
+        );
+    }
 
     /**
-     * @param mixed $array
+     * Converts any value to API string format with strict type enforcement.
+     *
+     * @param mixed $value
      */
-    protected function buildHTTPQuery($array): string
+    private function strictConvertToApiValue($value): ?string
     {
-        return str_replace(['%20', '!', "'", '(', ')', '*'], ['+', '%21', '%27', '%28', '%29', '%2A'], http_build_query(array_filter($array), '', '&', \PHP_QUERY_RFC3986));
+        if (null === $value) {
+            return null;
+        }
+
+        // Handle BackedEnum cases
+        if ($value instanceof \BackedEnum) {
+            $enumValue = $value->value;
+            if (!is_scalar($enumValue)) {
+                throw new \RuntimeException(sprintf(
+                    'Enum value for %s must be scalar, got %s',
+                    get_class($value),
+                    gettype($enumValue)
+                ));
+            }
+
+            return (string) $enumValue;
+        }
+
+        // Handle arrays
+        if (is_array($value)) {
+            return $this->convertArrayToApiString($value);
+        }
+
+        // Handle all other cases with strict string conversion
+        if (is_bool($value)) {
+            return $value ? 'true' : 'false';
+        }
+
+        if (is_object($value)) {
+            throw new \RuntimeException(sprintf(
+                'Cannot convert object of type %s to API value',
+                get_class($value)
+            ));
+        }
+
+        // Force string conversion for all scalar values
+        return (string) $value;
+    }
+
+    /**
+     * Converts array values to comma-separated string with strict typing.
+     *
+     * @param array<mixed> $values // Array of mixed values that will be converted
+     */
+    private function convertArrayToApiString(array $values): string
+    {
+        $converted = [];
+        foreach ($values as $item) {
+            $convertedItem = $this->strictConvertToApiValue($item);
+            if (null !== $convertedItem) {
+                $converted[] = $convertedItem;
+            }
+        }
+
+        return implode(',', $converted);
     }
 }