README

这是一套PHP类，旨在让您轻松访问新的西北EventHub & AMQ。

截至编写本文时，此PHP SDK实现了所有EventHub API调用的方法。

安装

此包通过composer提供

composer require northwestern-sysdev/event-hub-php-sdk

此包的最新版本支持PHP v7.4+。它可能不支持较旧的PHP版本。如果您需要与较旧版本兼容，请使用v1！

示例

以下是一些使用此SDK的快速示例。有关EventHub及其功能的更多信息，请参阅服务注册表上的文档。

请注意，此SDK的所有方法都可以抛出 Northwestern\SysDev\SOA\EventHub\Exception\EventHubDown 和 Northwestern\SysDev\SOA\EventHub\Exception\EventHubError 消息。前者表示网络问题或中断；后者表示您的EventHub使用中存在问题。

消费者

您可以循环以下示例代码，并使用cron调度程序轮询队列中的消息。

$message_api = new \Northwestern\SysDev\SOA\EventHub\Message('https://northwestern-dev.apigee.net', 'my api key', new GuzzleHttp\Client);
$topic_name = 'etsysdev.test.queue.name';

try {
    $message = $message_api->readOldest($topic_name); // returns a DeliveredMessage object

    // The ID is useful for moving messages & troubleshooting. The raw message will be a plain text representation, ideal for logging!
    log_stuff_in_my_database($message->getId(), $message->getRawMessage());

    // If you use JSON messages, this will be a PHP associative array. For XML, you'll need to getRawMessage() and parse it yourself.
    $body = $message->getMessage();
    update_my_database($body['some_unique_id_from_the_message'], $body['some_other_info']['a_field']);

    // Should be the last thing you do in your try block
    $message_api->acknowledgeOldest($topic_name);
} catch (\Exception $e) {
    // If we get an error before the acknowledgeOldest call, the message won't be ack'd & removed from the queue.
    // This gives you an opportunity to fix your stuff & try again!
}

请注意，EventHub支持webhook交付；当它实时收到消息时，它可以向您的应用程序执行HTTP POST。在实施队列轮询之前，您应该评估该选项。

发布者

$topic_api = new \Northwestern\SysDev\SOA\EventHub\Topic('https://northwestern-dev.apigee.net', 'my api key', new GuzzleHttp\Client);
$topic_name = 'etsysdev.test.queue.name';

// If you are sending JSON messages, you can build your messages as PHP associative arrays and send those.
$my_message = [
    'id' => 1,
    'important_enterprise_data' => 'Bananas float in water because they are less dense in comparison.',
    'crucial_security_info' => 'Bananas grow on plants that are officially considered an herb.',
];
$message_id = $eh->writeJsonMessage($topic_name, $my_message);

// For XML, you are responsible for building the string & sending the appropriate content type.
$my_message = '<?xml version="1.0" encoding="UTF-8"?><banana><fact>The banana is actually classified as a berry.</fact></banana>'; // but you're using an XML builder -- do whatever to cast to string
$message_id = $eh->writeMessage($topic_name, $my_message, 'application/xml');

管理Webhooks

EventHub可以配置为通过HTTP POST将目标为您的应用程序的消息发送到您通过webhooks创建的API端点。这是一个您可以自行配置的自服务功能。

有关如何操作以及配置选项的完整详细信息，请参阅EventHub Webhook文档。

$webhook_api = new \Northwestern\SysDev\SOA\EventHub\Webhook('https://northwestern-dev.apigee.net', 'my api key', new GuzzleHttp\Client);
$topic_name = 'etsysdev.test.queue.name';

// Create a paused webhook
$details = $webhook_api->create($topic_name, [
    'topicName' => $topic_name,
    'endpoint' => 'https://my-app-dev.northwestern.edu/api/webhook/receive', // the URL in your application
    'contentType' => 'application/json', // desired format for delivered messages
    'active' => false, // start off paused, so no deliveries are made to your app
    'securityTypes' => ['NONE'], // what authentication method(s) need to be done to authenticate w/ your endpoint -- see the webhook documentation for more info
    'webhookSecurity' => [
        ['securityType' => 'NONE']
    ]
]);

// When you're ready, turn the webhook on:
$details = $webhook_api->unpause($topic_name);

// You can adjust any of your settings whenever you need to -- see the EventHub docs for more info
$details = $webhook_api->updateConfig($topic_name, [
    'endpoint' => 'https://my-app-dev.northwestern.edu/api/v2/webhooks',
]);

// Or remove the webhook entirely & go back to polling the queue
$webhook_api->delete($topic_name);

常见问题解答

为什么我必须传入一个GuzzleHttp客户端？

我从Laravel特定的一个中分离出此包，并在构造函数中使用Guzzle使我可以轻松地将依赖项注入到Laravel的服务容器中。

Guzzle支持一些很酷的中间件功能，您在将其提供给EventHub SDK之前可能想要设置这些功能。

实际上，此包附带了一个用于临时网络错误的重试中间件。您可以这样做，以获取一个Guzzle客户端，如果它无法建立与EventHub的连接，则会立即尝试重试三次。

$client = \Northwestern\SysDev\SOA\EventHub\Guzzle\RetryClient::make();
$api = new \Northwestern\SysDev\SOA\EventHub\Webhook('https://northwestern-dev.apigee.net', 'my api key', $client);

这不会自动重试任何HTTP错误代码，例如，401未授权不会触发重试尝试。您可以根据需要扩展类并调整createRetryHandler()以更好地满足您的需求。

您有更多文档吗？

实际上没有。代码中有PHP docblocks，但它们只是将您引回到主要的EventHub API文档。此SDK只是一个小适配器层，以使使用EventHub感觉更像是PHP。

我需要帮助！

I&A团队是EventHub的主要联系人——我也是一名终端用户！

但是，如果您有关于PHP SDK的具体问题，您可以在NIT Slack上的#et-sysdev中提问，或通过nick.evans@northwestern.edu发送电子邮件。

贡献

提交一个拉取请求！

如果您需要为开发目的包含本地副本的包，请调整您的消费应用的 composer.json 如下

{
    // Add this section
    "repositories": [
        {
            "type": "path",
            "url": "/home/vagrant/code/SysDev-EventHub-PHP-SDK"
        }
    ],

    "require": {
        // Any branch that isn't named in a version format can be specified by prefixing
        // it with 'dev-', so this would install the 'my-feature' branch from a local copy of the package.
        "northwestern-sysdev/event-hub-php-sdk": "dev-my-feature"
    },
}

您可以通过运行 phpunit && ./vendor/bin/phpstan analyse --level 5 src/ 来测试该包。