README

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

想法是使ARI呼叫安全且简单。因此，我们希望在我们的应用程序代码中消除JSON解析。相反，我们希望尽可能简单，以便任何人都无需担心客户端存根的实现即可与ARI进行通信。

先决条件

从以下链接下载并安装Composer

https://getcomposer.org/download/

安装

Composer

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

composer require ng-voice/asterisk-ari-client

在安装过程中，您可能会遇到有关缺失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接口进行通信。所有请求和响应都是对象，易于理解。

以下示例使用Channels资源发起呼叫

<?php

declare(strict_types=1);

use NgVoice\AriClient\Exception\AsteriskRestInterfaceException;
use NgVoice\AriClient\Client\Rest\Settings as AriRestClientSettings;
use NgVoice\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('asterisk', 'asterisk')
);

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 NgVoice\AriClient\StasisApplicationInterface;
use NgVoice\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 NgVoice\AriClient\Client\WebSocket\Factory as AriWebSocketClientFactory;    
use NgVoice\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应用程序（例如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 © ng-voice GmbH (2020)

ng-voice很高兴为您提供帮助！请随时给我们发送消息。我们也很乐意了解您的应用想法和用例。:)

贡献者

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

维护者

• Lukas Stermann (lukas@ng-voice.com)

其他人

• Benedikt Vollmerhaus (项目审查)