Bloatless PHP WebSockets 技术文档

安装指南

环境要求

在安装和使用 Bloatless PHP WebSockets 之前，请确保您的系统满足以下要求：

• PHP >= 7.4
• ext-json
• ext-sockets

安装步骤

1. 使用 Composer 安装包：

   composer require bloatless/php-websocket
   

2. 安装完成后，您可以开始配置和启动 WebSocket 服务器。

项目使用说明

服务器

下载源代码到您的机器后，您需要编写一些代码来实际组装您的 WebSocket 服务器。以下是一个基本示例：

<?php

// 引入必要的文件

// 创建新的服务器实例
$server = new \Bloatless\WebSocket\Server('127.0.0.1', 8000, '/tmp/phpwss.sock');

// 服务器设置
$server->setMaxClients(100);
$server->setCheckOrigin(false);
$server->setAllowedOrigin('example.com');
$server->setMaxConnectionsPerIp(20);

// 注册应用程序
$server->registerApplication('status', \Bloatless\WebSocket\Application\StatusApplication::getInstance());
$server->registerApplication('chat', \Bloatless\WebSocket\Examples\Application\Chat::getInstance());

// 启动服务器
$server->run();

假设此代码位于名为 server.php 的文件中，您可以使用以下命令启动服务器：

php server.php

WebSocket 服务器将在提供的地址和端口上监听新的连接。默认情况下，这将是 localhost:8000。

应用程序

WebSocket 服务器本身处理连接，但没有额外的逻辑，它几乎是无用的。这些逻辑通过应用程序添加。在上面的示例中，两个应用程序被添加到服务器中：status 和 chat。

应用程序中最重要的一些方法包括：

interface ApplicationInterface
{
    public function onConnect(Connection $connection): void;

    public function onDisconnect(Connection $connection): void;

    public function onData(string $data, Connection $client): void;

    public function onIPCData(array $data): void;
}

onConnect 和 onDisconnect 可以用于跟踪连接到您的应用程序的所有客户端。onData 将在 WebSocket 服务器从连接到应用程序的客户端接收到新数据时调用。onIPCData 将在机器上的另一个进程提供数据时调用。

定时器

对于长时间运行的进程（如 WebSocket 服务器），通常需要定期执行任务。这可以通过定时器来实现。定时器可以定期在服务器或应用程序中执行方法。以下是一个示例：

$server = new \Bloatless\WebSocket\Server('127.0.0.1', 8000, '/tmp/phpwss.sock');
$chat = \Bloatless\WebSocket\Examples\Application\Chat::getInstance();
$server->addTimer(5000, function () use ($chat) {
    $chat->someMethod();
});
$server->registerApplication('chat', $chat);

此示例将在每 5 秒钟调用一次聊天应用程序中的 someMethod 方法。

Push-Client (IPC)

通常需要从另一个应用程序向 WebSocket 服务器进程推送数据。假设您运行一个包含聊天和新闻或博客区域的网站。现在，每当您的博客中发布新文章时，您希望通知所有当前在聊天中的用户。为此，您需要将数据从博客逻辑推送到 WebSocket 服务器。这就是 Push-Client 的作用。

启动 WebSocket 服务器时，它会打开一个 unix 域套接字并监听新消息。Push-Client 可用于发送这些消息。以下是一个示例：

$pushClient = new \Bloatless\WebSocket\PushClient('//tmp/phpwss.sock');
$pushClient->sendToApplication('chat', [
    'action' => 'echo',
    'data' => 'New blog post was published!',
]);

此代码将数据推送到正在运行的 WebSocket 服务器进程中。在这种情况下，聊天应用程序中的 echo 方法被调用，并将提供的消息发送给所有连接的客户端。

客户端 (浏览器/JS)

以上所有内容都与服务器端相关。但是，如何从浏览器连接到服务器呢？

以下是一个简单的示例：

<script>
 // 连接到服务器上的聊天应用程序
let serverUrl = 'ws://127.0.0.1:8000/chat';
let socket = new WebSocket(serverUrl);

// 将新消息记录到控制台
socket.onmessage = (msg) => {
    let response = JSON.parse(msg.data);
    console.log(response.data);
};
</script>

此 JavaScript 代码连接到服务器上的聊天应用程序，并将所有传入的消息打印到控制台。

项目API使用文档

服务器API

• setMaxClients(int $maxClients): 设置最大客户端连接数。
• setCheckOrigin(bool $checkOrigin): 设置是否检查源。
• setAllowedOrigin(string $allowedOrigin): 设置允许的源。
• setMaxConnectionsPerIp(int $maxConnectionsPerIp): 设置每个IP的最大连接数。
• registerApplication(string $name, ApplicationInterface $application): 注册应用程序。
• addTimer(int $interval, callable $callback): 添加定时器。
• run(): 启动服务器。

应用程序API

• onConnect(Connection $connection): 当客户端连接时调用。
• onDisconnect(Connection $connection): 当客户端断开连接时调用。
• onData(string $data, Connection $client): 当服务器接收到新数据时调用。
• onIPCData(array $data): 当接收到来自其他进程的数据时调用。

Push-Client API

• sendToApplication(string $applicationName, array $data): 向指定应用程序发送数据。

项目安装方式

1. 使用 Composer 安装包：

   composer require bloatless/php-websocket
   

2. 编写服务器代码并启动服务器。

3. 根据需要配置和使用应用程序、定时器和 Push-Client。

通过以上步骤，您可以成功安装和使用 Bloatless PHP WebSockets 项目。