README

从https://bitbucket.org/ngvoice/asterisk-ari-client/ 分支而来

Asterisk REST接口和简单的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扩展的错误。根据您的操作系统，有多种安装方法。在极少数情况下，您可能需要首先安装 php-dev，然后通过PECL安装和启用扩展。但通常不需要这样做。

Asterisk

您必须启动Asterisk实例并对其进行配置才能使用ARI。官方Asterisk文档会向您展示如何操作。

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

或者，使用我们的Dockerfile启动Asterisk（查看部署）。

示例

REST客户端

通过给定的REST客户端与Asterisk REST接口通信。所有请求和响应都是对象，易于理解。

以下示例使用通道资源发起调用

<?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());

Web socket客户端

连接到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客户端和/或web socket客户端构造函数。

错误处理器

如 example/my_example_stasis_app_worker.php 中所述，您可以为您的应用程序添加自定义错误处理器。这是Stasis应用程序逻辑（例如 e.g. 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（项目审查）