Introduce document classes

src/Core/Document.php

@@ -0,0 +1,115 @@
+<?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\Core;
+
+abstract class Document implements DocumentInterface
+{
+    private ?string $name       = null;
+    private ?bool $current      = null;
+    private ?bool $downloadable = null;
+    private ?bool $removable    = null;
+    private bool $validate      = false;
+
+    /**
+     * @var array<string, string>
+     */
+    private array $properties = [];
+
+    final public function setName(?string $name): self
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    final public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    final public function setCurrent(?bool $current): self
+    {
+        $this->current = $current;
+
+        return $this;
+    }
+
+    final public function isCurrent(): ?bool
+    {
+        return $this->current;
+    }
+
+    final public function setDownloadable(?bool $downloadable): Document
+    {
+        $this->downloadable = $downloadable;
+
+        return $this;
+    }
+
+    final public function isDownloadable(): ?bool
+    {
+        return $this->downloadable;
+    }
+
+    final public function setRemovable(?bool $removable): Document
+    {
+        $this->removable = $removable;
+
+        return $this;
+    }
+
+    final public function isRemovable(): ?bool
+    {
+        return $this->removable;
+    }
+
+    /**
+     * Add additional properties to the document. These will be passed to the BBB-Server as
+     * attributes at the documents' XML-node. Not needed on standard implementation of a
+     * BBB-Server, but might be needed on customized (adapted) BBB-Server implementations.
+     */
+    final public function addProperty(string $name, string $value): self
+    {
+        $this->properties[$name] = $value;
+
+        return $this;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    final public function getProperties(): array
+    {
+        return $this->properties;
+    }
+
+    public function setValidation(bool $validation): Document
+    {
+        $this->validate = $validation;
+
+        return $this;
+    }
+
+    public function getValidation(): bool
+    {
+        return $this->validate;
+    }
+}

src/Core/DocumentFile.php

@@ -0,0 +1,80 @@
+<?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\Core;
+
+class DocumentFile extends Document
+{
+    private string $filepath;
+
+    /** @deprecated only needed until DocumentTrait::addPresentation() has not been removed */
+    private ?string $fileContent = null;
+
+    public function __construct(string $filepath, string $name)
+    {
+        $this->setFilepath($filepath);
+        $this->setName($name);
+    }
+
+    public function setFilepath(string $filepath): self
+    {
+        $this->filepath = $filepath;
+
+        return $this;
+    }
+
+    public function getFilepath(): string
+    {
+        return $this->filepath;
+    }
+
+    /**
+     * @deprecated only needed until DocumentTrait::addPresentation() has not been removed
+     */
+    public function setFileContent(string $fileContent): self
+    {
+        $this->fileContent = $fileContent;
+
+        return $this;
+    }
+
+    /**
+     * @throws \Exception
+     */
+    public function getFileContent(): string
+    {
+        if ($this->fileContent) {
+            return $this->fileContent;
+        }
+
+        $fileContent = file_get_contents($this->filepath);
+
+        if (!$fileContent) {
+            throw new \Exception("Unable to read file at {$this->filepath}");
+        }
+
+        return $fileContent;
+    }
+
+    public function isValid(): bool
+    {
+        return file_exists($this->getFilepath());
+    }
+}

src/Core/DocumentInterface.php

@@ -0,0 +1,46 @@
+<?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\Core;
+
+interface DocumentInterface
+{
+    public function setName(?string $name): Document;
+
+    public function getName(): ?string;
+
+    public function setCurrent(?bool $current): Document;
+
+    public function isCurrent(): ?bool;
+
+    public function setDownloadable(?bool $downloadable): Document;
+
+    public function isDownloadable(): ?bool;
+
+    public function setRemovable(?bool $removable): Document;
+
+    public function isRemovable(): ?bool;
+
+    public function isValid(): bool;
+
+    public function setValidation(bool $validation): Document;
+
+    public function getValidation(): bool;
+}

src/Core/DocumentUrl.php

@@ -0,0 +1,100 @@
+<?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\Core;
+
+class DocumentUrl extends Document
+{
+    private string $url;
+
+    private int $timeout = 5;
+
+    public function __construct(string $url, ?string $name = null)
+    {
+        $this->setUrl($url);
+        $this->setName($name);
+    }
+
+    public function setUrl(string $url): self
+    {
+        $this->url = $url;
+
+        return $this;
+    }
+
+    public function getUrl(): string
+    {
+        return $this->url;
+    }
+
+    public function setTimeout(int $timeout): self
+    {
+        $this->timeout = $timeout;
+
+        return $this;
+    }
+
+    public function getTimeout(): int
+    {
+        return $this->timeout;
+    }
+
+    /**
+     * Checks the validity / existence of the provided URL. Pending on file size and server-performance
+     * the response could be slow.
+     *
+     * @experimental
+     */
+    public function isValid(): bool
+    {
+        return $this->urlExists($this->getUrl());
+    }
+
+    /**
+     * Checks the validity / existence of the provided URL. Pending on file size and server-performance
+     * the response could be slow.
+     *
+     * @experimental
+     */
+    private function urlExists(string $url): bool
+    {
+        $ch = curl_init($url);
+
+        if (!$ch) {
+            throw new \RuntimeException('Unhandled curl error!');
+        }
+
+        curl_setopt($ch, CURLOPT_TIMEOUT, $this->getTimeout());
+        curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $this->getTimeout());
+        curl_setopt($ch, CURLOPT_NOBODY, true);
+        curl_setopt($ch, CURLOPT_RETURNTRANSFER, false);
+
+        $data     = curl_exec($ch);
+        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+
+        curl_close($ch);
+
+        if ($httpCode >= 200 && $httpCode < 400) {
+            return true;
+        }
+
+        return false;
+    }
+}

src/Parameters/Config/DocumentOptions.php

@@ -22,6 +22,9 @@
 
 use BigBlueButton\Enum\DocumentOption;
 
+/**
+ * @deprecated Replaced by new Document-class, DocumentUrl-class and DocumentFile-class
+ */
 class DocumentOptions
 {
     /** @var array<string, bool> */

src/Parameters/CreateMeetingParameters.php

@@ -27,9 +27,9 @@ class CreateMeetingParameters extends MetaParameters
 {
     use DocumentableTrait;
 
-    private ?string $meetingId = null;
+    private string $meetingId;
 
-    private ?string $meetingName = null;
+    private string $meetingName;
 
     /**
      * @deprecated Password-string replaced by an Enum\Role-constant in JoinMeetingParameters::__construct()
@@ -179,19 +179,13 @@ class CreateMeetingParameters extends MetaParameters
 
     private ?string $presentationUploadExternalDescription = null;
 
-    /**
-     * CreateMeetingParameters constructor.
-     *
-     * @param mixed $meetingId
-     * @param mixed $meetingName
-     */
-    public function __construct($meetingId = null, $meetingName = null)
+    public function __construct(string $meetingId, string $meetingName)
     {
         $this->meetingId   = $meetingId;
         $this->meetingName = $meetingName;
     }
 
-    public function getMeetingId(): ?string
+    public function getMeetingId(): string
     {
         return $this->meetingId;
     }