EventSource 项目技术文档

1. 安装指南

1.1 使用 Composer 安装

推荐使用 Composer 来安装 EventSource 库。首先，在你的项目根目录下创建一个 composer.json 文件，内容如下：

{
    "require": {
        "igorw/event-source": "1.0.*"
    }
}

然后，运行以下命令来安装依赖：

$ curl -s http://getcomposer.org/installer | php
$ php composer.phar install

安装完成后，你可以通过自动加载器来使用库：

<?php
require 'vendor/autoload.php';

2. 项目使用说明

2.1 输出 EventSource 头信息

首先，你需要输出 EventSource 的头信息，以便客户端知道它正在与一个 EventSource 服务器通信。可以使用以下代码：

<?php

use Igorw\EventSource\Stream;

foreach (Stream::getHeaders() as $name => $value) {
    header("$name: $value");
}

2.2 创建并发送事件

接下来，创建一个 Stream 对象，并通过其 API 创建和发送事件。以下示例代码每 2 秒发送一个新事件：

<?php

use Igorw\EventSource\Stream;

$stream = new Stream();

while (true) {
    $stream
        ->event()
            ->setData("Hello World")
        ->end()
        ->flush();
    
    sleep(2);
}

2.3 JavaScript 客户端示例

在客户端，你可以使用以下 JavaScript 代码来接收事件：

var stream = new EventSource('stream.php');

stream.addEventListener('message', function (event) {
    console.log(event.data);
});

3. 项目 API 使用文档

3.1 事件 ID

如果你的事件有 ID，客户端在重新连接时会发送 Last-Event-ID 头信息。你可以读取这个值并重新发送任何在此之后发生的事件。

<?php

$lastId = filter_input(INPUT_SERVER, 'HTTP_LAST_EVENT_ID');

if ($lastId) {
    $buffer = getMessagesAfter($lastId);

    foreach ($buffer as $message) {
        $stream->event()
            ->setId($message['id'])
            ->setData($message['data']);
    }

    $stream->flush();
}

3.2 事件命名空间

你可以通过 setEvent 方法为事件设置命名空间。这允许你在客户端绑定到特定类型的事件。

<?php

$stream
    ->event()
        ->setEvent('foo')
        ->setData($message['data']);
    ->end()
    ->event()
        ->setEvent('bar')
        ->setData($message['data']);
    ->end()
    ->flush();

在客户端，你可以绑定到这些事件类型：

var stream = new EventSource('stream.php');

stream.addEventListener('foo', function (event) {
    console.log('Received event foo!');
});

stream.addEventListener('bar', function (event) {
    console.log('Received event bar!');
});

3.3 发送 JSON 数据

在大多数应用中，你可能需要发送更复杂的数据而不是简单的字符串。推荐使用 JSON 格式来实现这一点。

在服务器端，使用 json_encode 函数来编码数据：

<?php

$data = array('userIds' => array(21, 43, 127));

$stream
    ->event()
        ->setData(json_encode($data));
    ->end()
    ->flush();

在客户端，使用 JSON.parse 来解码数据：

var stream = new EventSource('stream.php');

stream.addEventListener('message', function (event) {
    var data = JSON.parse(event.data);
    console.log('User IDs: '+data.userIds.join(', '));
});

4. 项目安装方式

4.1 通过 Composer 安装

如前所述，推荐使用 Composer 来安装 EventSource 库。具体步骤请参考 安装指南。

4.2 手动安装

如果你不使用 Composer，也可以手动下载库文件并将其包含在你的项目中。不过，这种方式不推荐，因为它会增加维护的复杂性。

4.3 测试

你可以通过运行以下命令来测试项目：

$ phpunit

5. 其他注意事项

5.1 PHP 时间限制

在某些环境中，可能需要移除脚本的时间限制。如果你的脚本在 30 或 60 秒后停止运行，可以添加以下代码：

<?php
set_time_limit(0);

5.2 Polyfill

大多数旧版浏览器尚未实现 EventSource。幸运的是，有一个 polyfill 可用，允许在更广泛的浏览器中使用 EventSource。

---

通过以上文档，你应该能够顺利安装、使用和理解 EventSource 项目。如果有任何问题，请参考项目的 GitHub Wiki 或联系项目维护者。