README

从以下链接 fork：https://bitbucket.org/ngvoice/asterisk-ari-client/

Asterisk REST Interface 的客户端实现和简单的 Stasis 应用程序开发库。

目标是使 ARI 通话安全且易于使用。因此，我们希望在应用程序代码中消除 JSON 解析。相反，我们希望尽可能简化任何人与 ARI 通信的过程，而无需担心客户端存根的实现。

先决条件

从以下链接下载并安装 composer：

https://getcomposer.org.cn/download/

安装

Composer

请运行以下命令将库添加到您的项目中

PHP 7.4 composer require opiy-org/asterisk-ari-php

PHP 8.0|8.1 composer require opiy-org/asterisk-ari-php:2

在安装过程中，您可能会遇到有关缺少 PHP 扩展的 composer 错误。根据您的操作系统，有多种安装方法。在极少数情况下，您可能需要先安装 php-dev，然后通过 PECL 安装和启用扩展。但这通常不是必需的。

Asterisk

您将需要启动一个 Asterisk 实例并对其进行配置，才能使用 ARI。官方 Asterisk 文档将指导您如何操作。

https://wiki.asterisk.org/wiki/display/AST/Asterisk+Configuration+for+ARI

或者，使用我们的 Dockerfile 启动 Asterisk（请参阅部署部分）。

示例

REST 客户端

通过提供的 REST 客户端与 Asterisk REST Interface 进行通信。所有请求和响应都是对象，易于理解。

以下示例使用 Channels 资源发起一个通话

<?php

declare(strict_types=1);

use OpiyOrg\AriClient\Exception\AsteriskRestInterfaceException;
use OpiyOrg\AriClient\Client\Rest\Settings as AriRestClientSettings;
use OpiyOrg\AriClient\Client\Rest\Resource\Channels as AriChannelsRestResourceClient;

require_once __DIR__ . '/vendor/autoload.php';

// Of course inject your own REST client settings here.
$ariChannelsRestResourceClient = new AriChannelsRestResourceClient(
    new AriRestClientSettings('login', 'password', '127.0.0.1', 8088, 'ari-php')
);

try {
    // Call the specified number
    $originatedChannel = $ariChannelsRestResourceClient->originate(
        'PJSIP/+4940123456789',
        [
            'app' => 'MyExampleStasisApp'
        ]
    );
} catch (AsteriskRestInterfaceException $e) {
    printf("Error occurred: '%s'\n", $e->getMessage());
}

printf("The originated channel has the ID '%s'\n", $originatedChannel->getId());

WebSocket 客户端

连接到 Asterisk 并订阅 Stasis 应用程序。以下示例展示了如何定义您的 Stasis 应用程序以及如何处理特定传入的事件，这些事件由应用程序上下文中的通道发出。

在这个示例中，我们处理了一个 StasisStart 事件

<?php

declare(strict_types=1);

// TODO: Change to your own project namespace.
namespace My\Own\Project\Namespace;
    
use OpiyOrg\AriClient\StasisApplicationInterface;
use OpiyOrg\AriClient\Model\Message\Event\StasisStart;

/**
 * Write your own Stasis application class that must implement the
 * StasisApplicationInterface.
 *
 * This application will register automatically in Asterisk as soon
 * as you start a WebSocketClient (@see example/my_example_stasis_app_worker.php).
 */
class MyExampleStasisApp implements StasisApplicationInterface
{
    /**
     * To declare an ARI event handler function, name it after
     * the occurring Asterisk event you want to handle and add
     * the prefix 'onAriEvent'. The only parameter is the object
     * representation of the event, provided by this library.
     * The function MUST also be public and non-static.
     *
     * Of course you can define any other functions within this class
     * that do not handle incoming ARI events (leave out the prefix ;-)).
     * Think of your Stasis application class as container for your
     * application logic.
     *
     * The StasisStart event for example is triggered for
     * channels when they enter your application.
     *
     * @param StasisStart $stasisStart The Asterisk event,
     * telling you that a channel has entered your application.
     */
    public function onAriEventStasisStart(StasisStart $stasisStart): void
    {
        printf(
            'This is the channel's StasisStart event '
            . "handler triggered by channel '%s' :-)\n",
            $stasisStart->getChannel()->getId()
        );
    }
}

编写 PHP 脚本来启动您的 WebSocketClient 工作进程。这是一个阻塞过程！对于生产环境，您应该在后台使用进程管理器运行它。我们推荐 Linux 的 supervisor。

<?php

declare(strict_types=1);

use OpiyOrg\AriClient\Client\WebSocket\Factory as AriWebSocketClientFactory;    
use OpiyOrg\AriClient\Client\WebSocket\Settings as AriWebSocketClientSettings;

require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/MyExampleStasisApp.php';

/*
 * Initialize an ARI web socket client to
 * listen for incoming Asterisk events.
 *
 * Of course inject your own web socket settings here.
 */
$ariWebSocketClient = AriWebSocketClientFactory::create(
    new AriWebSocketClientSettings('asterisk', 'asterisk'),
    new MyExampleStasisApp()
);

$ariWebSocketClient->start();

您可以在 example 目录中找到更详细且包含更多选项的示例。

调试日志

为了调试您的 ARI 通信，此客户端库提供简单的调试日志开关。只需在 REST/web socket 客户端设置对象中启用/禁用它即可。错误日志将写入 STDERR。所有其他日志将写入 STDOUT。

或者，使用您自己的 Logger 并将其传递给 REST 客户端和/或 WebSocket 客户端构造函数。

错误处理器

如 example/my_example_stasis_app_worker.php 中所述，您可以为您的应用程序添加自定义错误处理器。这是 Stasis 应用程序逻辑（例如，example/MyExampleStasisApp）与 PHP 进程错误处理器之间的一层。这意味着您可以选择处理未在应用程序逻辑中捕获的 Throwable，它通常会导致应用程序（以及可能整个进程）崩溃。为什么不将其报告给 BugSnag 呢？

运行测试

单元测试

composer test

编码风格测试

用于代码审查

composer lint

用于静态代码分析

composer sca

部署

我们在 docker/asterisk/ 目录中添加了一个Dockerfile，您还可以在这里找到一些用于您自己的Asterisk实例的示例配置文件。

建议使用本库中提供的Dockerfile来编译您自己的Asterisk容器。

cd docker/asterisk
docker build -t --build-arg asterisk_version=WHATEVER_VERSION_YOU_LIKE asterisk:latest .
docker run -d --name some-asterisk -p 8088:8088 -p 5060:5060 -p 5060:5060/udp asterisk:latest

!!! PLEASE NOTE !!!
Compiling Asterisk sometimes is bound to the hardware you are compiling it on.
Currently, we compile a separate container for every machine we run Asterisk on,
to make sure it will work.
Alternatively, you can set generic compiler flags at your own risk.

许可证

MIT

原始来源：ngvoice/asterisk-ari-client（由ng-voice提供）

贡献者

欢迎您的pull请求。如果您想贡献，请坚持PSR-12编码标准。

维护者

• opiy（opiy@opiy.org）

作者

• Lukas Stermann（lukas@ng-voice.com）
• Benedikt Vollmerhaus（项目审核）