README

简介

这是一个非官方的Pusher PHP客户端，用于与REST Pusher API交互。与官方客户端相反，ZfrPusher基于现代工具和更好的架构。

依赖项

Guzzle库: >= 3.5

与框架的集成

为了使这个库更容易使用，以下是一些库

ZfrPusherModule：这是一个Zend Framework 2模块

想要为其他框架进行集成？打开一个问题，我会为你创建一个仓库！

安装

我们建议您使用Composer安装ZfrPusher。只需将以下行添加到您的composer.json文件中

{
    "require": {
        "zfr/zfr-pusher": "1.*"
    }
}

然后，通过输入： php composer.phar update更新您的依赖项。

教程

ZfrPusher分为两种方式：客户端对象（ZfrPusher\Client\PusherClient类）允许手动执行Guzzle命令，以及服务对象（ZfrPusher\Service\PusherService类）它围绕客户端的薄层，旨在简化使用和错误处理。

这是创建Pusher服务的方法

use ZfrPusher\Client\Credentials;
use ZfrPusher\Client\PusherClient;
use ZfrPusher\Service\PusherService;

$credentials = new Credentials('application-id', 'key', 'secret');
$client      = new PusherClient($credentials);
$service     = new PusherService($client);

一旦您有权访问该服务，您就可以执行任何操作。

触发事件

要向一个或多个频道触发事件，请使用trigger方法。第一个参数可以是单个频道（字符串），也可以是多个频道（字符串数组）

// Single channel
$service->trigger('my-channel-1', 'my-event', array('key' => 'value'));

// Multiplie channels
$service->trigger(array('my-channel-1', 'my-channel-2'), 'my-event', array('key' => 'value'));

trigger方法还支持第四个参数，即要排除接收消息的特定套接字的套接字ID（更多信息请参阅这里）

// Exclude socket '1234.1234'
$service->trigger('my-channel-1', 'my-event', array('key' => 'value'), '1234.1234');

最后，trigger方法还支持第五个参数，用于异步触发。这意味着它立即返回到客户端，而不等待响应。默认情况下，所有触发请求都是同步的

// Force the trigger to be asynchronous
$service->trigger('my-channel-1', 'my-event', array('key' => 'value'), '', true);

Pusher服务还提供了使用triggerAsync方法进行异步请求的快捷方式，如上所示

$service->triggerAsync('my-channel-1', 'my-event', array('key' => 'value'));

频道信息

您可以使用getChannelInfo方法获取有关单个频道的信息，可选地获取您要检索的信息数组（目前，Pusher API仅支持user_count和subscription_count值）

$result = $service->getChannelInfo('my-channel', array('user_count'));

您可以使用getChannelsInfo方法获取有关多个频道的信息，可选地按名称过滤。与getChannelInfo一样，此方法接受可选的第二参数，该参数是您要检索的信息数组。

// Get information about all channels whose name begins by 'presence-'
$result = $service->getChannelsInfo('presence-');

存在频道用户

您可以使用getPresenceUsers方法检索存在频道中的所有用户

$result = $service->getPresenceUsers('presence-foobar');

认证私有频道

为了对私有频道进行用户认证，请调用带有频道名称和套接字ID的authenticatePrivate方法。此方法返回一个数组，其键为'auth'，其值为签名认证字符串。由您负责将其编码为JSON字符串（通常在MVC架构中的控制器中完成）以返回给客户端

$result = $service->authenticatePrivate('private-channel', '1234.1234');

var_dump($result); // prints array('auth' => 'authentication-string')

认证存在频道

要验证用户与存在频道，请调用authenticatePresence方法，并传入频道名称、socket ID和用户数据。此方法返回一个数组，包含auth和channel_data键的值。您需要将其编码为JSON字符串（通常在MVC架构中的控制器中完成）以返回给客户端

$result = $service->authenticatePresence('presence-channel', '1234.1234', array('firstName' => 'Michael'));

var_dump($result); // prints array('auth' => 'authentication-string', 'channel_data' => '{"firstName":"Michael"}')

通用认证

为了方便使用，服务还提供了一个通用的authenticate方法，根据频道名称选择正确的方法

$result = $service->authenticate('private-channel', '1234.1234');
$result = $service->authenticate('presence-channel', '1234.1234', array('firstName' => 'Michael'));

高级使用

错误处理

当使用Pusher服务时，所有可能发生的异常都会被处理，这样您可以轻松地过滤Pusher错误。所有Pusher异常都实现了ZfrPusher\Exception\ExceptionInterface

use ZfrPusher\Exception\ExceptionInterface as PusherExceptionInterface;

try {
    $result = $service->getPresenceUsers('presence-foobar');
} catch (PusherExceptionInterface $e) {
    // Handle exception
}

服务根据错误状态码实例化具体的异常

ZfrPusher\Service\Exception\UnauthorizedException：当Pusher REST API返回401错误（未授权）时抛出。
ZfrPusher\Service\Exception\ForbiddenException：当Pusher REST API返回403错误（当应用程序可能被禁用或您已达到消息配额时）时抛出。
ZfrPusher\Service\UnknownResourceException：当Pusher REST API返回404错误（例如，当您请求有关未知频道的信息时）时抛出。
ZfrPusher\Service\RuntimeException：对于任何其他错误。

在所有情况下，您可以通过调用php $exception->getMessage();来获取有关错误的更多信息。

使用示例

use ZfrPusher\Exception\ExceptionInterface as PusherExceptionInterface;
use ZfrPusher\Service\Exception\ForbiddenException;

try {
    $result = $service->getPresenceUsers('presence-foobar');
} catch(ForbiddenException $e) {
    // Oops, we may have reached our messages quota... Let's do something!
} catch (PusherExceptionInterface $e) {
    // Any other Pusher exception...
} catch (\Exception $e) {
    // Any other non-Pusher exception...
}

调试应用程序

在官方Pusher PHP客户端中，您可以通过set_logger方法直接将记录器附加到客户端。虽然简单，但这是一种不好的实现方式，因为它硬编码到客户端中（并且您的记录器必须有log方法，因此您的记录器可能没有它）。此外，记录发生的地方也是硬编码的。

相反，ZfrPusher客户端利用事件管理器来完成此操作。例如，假设我们想要在请求发送之前记录每个URL。首先创建一个订阅者。订阅者实现Symfony\Component\EventDispatcher\EventSubscriberInterface接口。在getSubscribedEvents方法中，我们为事件request.before_send（您可以在此处找到可用钩子的完整列表）附加一个监听器

<?php

namespace Application\Logger;

use Symfony\Component\EventDispatcher\Event;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class PusherLogger implements EventSubscriberInterface
{
    /**
     * {@inheritDoc}
     */
    public static function getSubscribedEvents()
    {
        return array(
            'request.before_send' => array('log', -255)
        );
    }

    /**
     * Log something
     *
     * @param  Event $event
     * @return void
     */
    public function log(Event $event)
    {
        $request = $event['request'];
        $url     = $request->getUrl();

        // Log the URL...
    }
}

接下来，我们需要将订阅者附加到客户端

use ZfrPusher\Client\Credentials;
use ZfrPusher\Client\PusherClient;
use ZfrPusher\Service\PusherService;

$credentials = new Credentials('application-id', 'key', 'secret');
$client      = new PusherClient($credentials);

$client->addSubscriber(new PusherLogger());

$service = new PusherService($client);

现在，所有的URL都会被记录。

直接使用客户端

虽然Pusher服务很方便，但您可能希望直接使用Pusher客户端，这样您可以更好地控制请求的发送方式。您可以这样操作

use ZfrPusher\Client\Credentials;
use ZfrPusher\Client\PusherClient;

$credentials = new Credentials('application-id', 'key', 'secret');
$client      = new PusherClient($credentials);

// Let's do a trigger
$parameters = array(
    'event'     => 'my-event',
    'channel'   => 'my-channel',
    'data'      => array('key' => 'value'),
    'socket_id' => '1234.1234'
);

$command = $client->getCommand('Trigger', $parameters)
                  ->execute();

直接使用客户端时，错误发生时抛出的异常是Guzzle异常，而不是Pusher异常。因此，过滤仅Pusher异常会更困难。如果您想使用此功能，请使用服务或编写围绕Pusher客户端的包装器。

zfr / zfr-pusher

维护者

详细信息