README

这是非官方且最易使用的 PHP 的 BigBlueButton API，使开发者更容易使用 BigBlueButton API v2.2+，适用于 PHP 8.1+。

此 API 使用 BigBlueButton，并由 BigBlueButton Inc. neither endorsed nor certified. BigBlueButton 和 BigBlueButton Logo 是 BigBlueButton Inc. 的商标。

❓ 为什么我应该使用分支？

为了解释为什么你应该使用分支，我们必须解释我们为什么创建了自己的分支。虽然 BigBlueButton 是一款优秀的产品，但作为外部开发者的贡献通常很繁琐。错误修复和功能没有被合并。现代增强功能被推迟或不允许。因此，来自不同公司和大学的 4 个人决定创建一个对现有 PHP API 开放的替代品。虽然我们仍然保持向后兼容，但此分支具有以下优点

不需要不安全的环境变量
测试被分为单元测试和集成测试，因此可以正常工作
通过 git 钩子和贡献者指南简化了开发
文档是最新和完整的
API 已固定并扩展以充分利用其潜力
需要至少 PHP 8.1，这可以使代码更高效和可读

⚙️ 安装和使用

需求

为了使用此库，您必须确保满足以下要求

PHP 8.1 或更高版本。
安装了 curl 库。
安装了 mbstring 库。
安装了 xml 库。

安装

我们使用 composer 来管理和安装所有库，因此您也需要使用它。如果您为项目设置了 composer，您只需通过以下方式将此 API 添加到您的需求部分：

composer require littleredbutton/bigbluebutton-api-php

基本使用

为了向您的 BigBlueButton 实例发出任何请求，您必须创建一个 API 对象

use BigBlueButton\BigBlueButton;

$bbb = new BigBlueButton($apiUrl, $apiSecret);

如果您之前没有使用过 composer，请确保包含 vendor/autoload.php。

通常，使用方式与官方 API 描述非常相似。这意味着要创建一个房间，您必须创建一个 CreateMeetingParameters 对象并通过相关的设置方法设置所有必需的参数。

测试 API URL 和密钥是否有效

use BigBlueButton\Parameters\IsMeetingRunningParameters;

$meetingParams = new IsMeetingRunningParameters('foobar');

try {
	$response = $bbb->isMeetingRunning($meetingParams);

	if (!$response->success() && !$response->failed()) {
		// invalid url
	}

	if (!$response->success()) {
		// invalid secret
	}

	// url and secret are valid
} catch (\Exception $e) {
	// invalid url
}

📕 文档

管理

获取 API 版本

$version = $bbb->getApiVersion()->getVersion();

创建会议

use BigBlueButton\Parameters\CreateMeetingParameters;

$createMeetingParams = new CreateMeetingParameters($meetingID, $meetingName);

$createMeetingResponse = $bbb->createMeeting($createMeetingParams);

if ($createMeetingResponse->success()) {
    // process after room created
}

实验性功能

⚠️ bbb 不提供官方支持

访客策略 除了始终接受、始终拒绝和询问主持人等访客策略外，还有始终接受认证的选项。源代码

ASK_MODERATOR 正在请求主持人接受或拒绝用户或访客的加入。在使用我们的API时，访客用户默认标记为“未授权”用户。

使用 ALWAYS_ACCEPT_AUTH 选项，所有授权用户（非访客）可以直接加入会议，而仅需要对未授权用户（如访客）需要主持人的批准。

$createMeetingParams->setGuestPolicyAlwaysAcceptAuth();

加入会议

use BigBlueButton\Parameters\JoinMeetingParameters;
use BigBlueButton\Enum\Role;

$joinMeetingParams = new JoinMeetingParameters($room->uid, $displayname, Role::VIEWER);
$joinMeetingParams->setCreateTime($createMeetingResponse->getCreationTime());
$joinMeetingParams->setRedirect(true);

$joinUrl = $bbb->getJoinMeetingURL($joinMeetingParams);

// e.g. header('Location:' . $joinUrl);

结束会议

use BigBlueButton\Parameters\EndMeetingParameters;

$endMeetingParams = new EndMeetingParameters($meetingID);
$response = $bbb->endMeeting($endMeetingParams);

监控

获取会议列表

$response = $bbb->getMeetings();

if ($response->failed()) {
    // error handling
}

$meetings = $response->getMeetings();

// e.g. $meetings[0]->getMeetingName();

会议是否正在运行？

use BigBlueButton\Parameters\IsMeetingRunningParameters;

$isMeetingRunningParams = new IsMeetingRunningParameters($meetingId);

$response = $bbb->isMeetingRunning($isMeetingRunningParams);

if ($response->success() && $response->isRunning()) {
    // meeting is running
}

获取会议信息

use BigBlueButton\Parameters\GetMeetingInfoParameters;

$getMeetingInfoParams = new GetMeetingInfoParameters($meetingID);

$response = $bbb->getMeetingInfo($getMeetingInfoParams);

if ($response->failed()) {
    // error handling
}

// process $response->getRawXml();

录音

获取录音

use BigBlueButton\Parameters\GetRecordingsParameters;

$recordingParams = new GetRecordingsParameters();
$recordingParams->setRecordID($recordId); // omit to get a list of all recordings
$recordingParams->setState('any');

$response = $bbb->getRecordings($recordingParams);

if (!$response->success()) {
    // handle error
}

$records = $response->getRecords();

// e.g. $records[0]->getParticipantCount();

发布录音

use BigBlueButton\Parameters\PublishRecordingsParameters;

$publishRecordingsParams = new PublishRecordingsParameters($recordingId, $publish);

$response = $bbb->publishRecordings($publishRecordingsParams);

if ($response->success() && $response->isPublished()) {
    // record was published
}

删除录音

use BigBlueButton\Parameters\DeleteRecordingsParameters;

$deleteRecordingsParams= new DeleteRecordingsParameters($recordingID);

$response = $bbb->deleteRecordings($deleteRecordingsParams);

if ($response->success()) {
    // meeting was deleted
}

使用HTTP传输

此库允许您用所谓的 HTTP传输 替换与BigBlueButton通信时使用的完整HTTP传输层。

如果您想在发送到BigBlueButton之前操纵HTTP请求，或者在此库上执行不需要实际HTTP请求的集成测试，这将很有用。

此外，传输允许详细地调整底层后端选项。

可用转发

CurlTransport (默认)

CurlTransport 使用PHP的纯 curl 扩展，除了扩展之外不需要额外的库。如果没有在构造API对象时配置显式传输，将使用一些推荐的默认选项创建 CurlTransport。

尽管如此，可能有创建CurlTransport手动的原因。例如，为了设置自定义cURL选项。以下是一些示例用法

这将创建与内部默认选项相同的 CurlTransport，如果未提供传输

use BigBlueButton\BigBlueButton;
use BigBlueButton\Http\Transport\CurlTransport;

$transport = CurlTransport::createWithDefaultOptions();
$bbb = new BigBlueButton('https://bbb.example.com/bigbluebutton/', 'S3cr3t', $transport);
// [...]

要设置自定义cURL选项 - 如要发送的附加HTTP头和自定义超时

use BigBlueButton\BigBlueButton;
use BigBlueButton\Http\Transport\CurlTransport;

$transport = CurlTransport::createWithDefaultOptions([
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'X-Custom-Header: custom-header-value',
    ],
]);
$bbb = new BigBlueButton('https://bbb.example.com/bigbluebutton/', 'S3cr3t', $transport);
// [...]

有关cURL选项的完整列表，请参阅 PHP文档

⚠️ 请避免使用 new CurlTransport(); 直接创建 CurlTransport，除非您确切知道自己在做什么。这将完全避免添加推荐的默认cURL选项。

PsrHttpClientTransport

此传输允许您使用基于 PSR-7、PSR-17 和 PSR-18 的任何HTTP客户端。由于PSR-17特别以工厂驱动为主，因此此传输需要一个请求工厂和一个流工厂。

此传输需要手动安装 composer 包 psr/http-client、psr/http-factory 和 psr/http-message。这几乎会通过要求提供PSR-7、PSR-17和PSR-18的包来完成。

要发现适当的包，请参阅 packagist.org

以下是一个使用 Symfony HTTP客户端 PSR-18适配器和 nyholm/psr7 的快速示例。

use BigBlueButton\BigBlueButton;
use BigBlueButton\Http\Transport\Bridge\PsrHttpClient\PsrHttpClientTransport;
use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\HttpClient\Psr18Client;

$psr18Client = new Psr18Client();
$psr17Factory = new Psr17Factory();
// Optional: Default headers sent with each request, argument can be left out.
$defaultHeaders = [
    'X-Custom-Header' => 'custom-header-value',
];

// The $psr17Factory acts both as request and stream factory
$transport = new PsrHttpClientTransport($psr18Client, $psr17Factory, $psr17Factory, $defaultHeaders);
$bbb = new BigBlueButton('https://bbb.example.com/bigbluebutton/', 'S3cr3t', $transport);
// [...]

另一种选择是使用 php-http/discovery，它将根据已安装的包找到合适的PSR-17和PSR-18实现。例如，如果您将此库嵌入到自己的库样式项目中，这很可能是所需的，该项目不应强制任何供应商。

use BigBlueButton\BigBlueButton;
use BigBlueButton\Http\Transport\Bridge\PsrHttpClient\PsrHttpClientTransport;
use Http\Discovery\Psr17FactoryDiscovery;
use Http\Discovery\Psr18ClientDiscovery;

$transport = new PsrHttpClientTransport(
    Psr18ClientDiscovery::find(),
    Psr17FactoryDiscovery::findRequestFactory(),
    Psr17FactoryDiscovery::findStreamFactory(),
    $defaultHeaders // see previous example for details
);
$bbb = new BigBlueButton('https://bbb.example.com/bigbluebutton/', 'S3cr3t', $transport);
// [...]

SymfonyHttpClientTransport

此传输可以直接使用 Symfony HTTP客户端，无需通过PSR-17和PSR-18的迂回。

要使用此传输，您必须至少安装 symfony/http-client-contracts 和适当的实现。通常，通过Composer要求 symfony/http-client 就足够了。

对于独立环境，您可以使用工厂方法轻松创建传输。这将在后台自动选择适合您环境的正确Symfony HTTP客户端

use BigBlueButton\BigBlueButton;
use BigBlueButton\Http\Transport\Bridge\SymfonyHttpClient\SymfonyHttpClientTransport;

// Optional: Default headers sent with each request, argument can be left out.
$defaultHeaders = [
    'X-Custom-Header' => 'custom-header-value',
];
// Optional: Default options for each request, argument can be left out.
// See https://symfony.ac.cn/doc/current/http_client.html for details.
$defaultOptions = [
    'timeout' => 5,
    'max_duration' => 10,
];

$transport = SymfonyHttpClientTransport::create($defaultHeaders, $defaultOptions);
$bbb = new BigBlueButton('https://bbb.example.com/bigbluebutton/', 'S3cr3t', $transport);
// [...]

如果需要，您还可以手动传递预配置的 Symfony\Contracts\HttpClient\HttpClientInterface 实例

use BigBlueButton\BigBlueButton;
use BigBlueButton\Http\Transport\Bridge\SymfonyHttpClient\SymfonyHttpClientTransport;
use Symfony\Component\HttpClient\CurlHttpClient;

$httpClient = new CurlHttpClient();

$transport = new SymfonyHttpClientTransport(
    $httpClient,
    $defaultHeaders, // see previous example for details
    $defaultOptions // see previous example for details
);
$bbb = new BigBlueButton('https://bbb.example.com/bigbluebutton/', 'S3cr3t', $transport);
// [...]

实现自己的转发（高级）

如果本库中的传输方式不适合您，您可以实现自己的自定义传输方式以满足特殊需求。

use BigBlueButton\Http\Transport\TransportInterface;
use BigBlueButton\Http\Transport\TransportRequest;
use BigBlueButton\Http\Transport\TransportResponse;

final class CustomTransport implements TransportInterface
{
    /**
     * {@inheritDoc}
     */
     public function request(TransportRequest $request) : TransportResponse
     {
        $url = $request->getUrl();
        $contentType = $request->getContentType();
        // aka request body
        $payload = $request->getPayload();

        // [...]

        return new TransportResponse($reponseBody, $jsessionId);
     }
 }

您的 TranportInterface 实现必须使用通过 TransportRequest 对象提供的所有值（目前为内容类型、URL 和有效载荷（正文））。根据您使用的后端响应，您必须构建一个合适的 TransportResponse 对象，包含响应正文和由 BBB 传递的 JSESSION cookie。

运行此库的测试

在运行测试之前，请确保已安装此包的所有开发依赖项。根据 composer 的版本，您可能需要运行

composer install --dev

要运行此库的单元测试，只需输入

composer test

由于使用了真实的 BigBlueButton 服务器，因此集成测试需要额外的设置。您需要创建一个 .env.local 文件来配置要使用的服务器和适当的凭证

echo "BBB_SERVER_BASE_URL=https://bbb.example/bigbluebutton/" > .env.local
echo "BBB_SECRET=S3cr3t" >> .env.local

您也可以通过在 shell 中使用例如 export 这样的命令来将这两个变量作为真实的环境变量传递。

要运行此库的集成测试，请输入

composer test-integration

提交错误和功能请求

错误和功能请求在 GitHub 上跟踪

littleredbutton / bigbluebutton-api-php

维护者

详细信息