A Class Library enabling Asterisk ARI functionality for PHP

Nir Simionovich

Last update: Jan 5, 2023

Related tags

Overview

phpari

A Class Library enabling Asterisk ARI functionality for PHP

Dependencies

These are the minimum requirements to have phpari installed on your server:

** PHP >= 5.3.9

** Composer

** PHP OpenSSL Module to connect using SSL (wss:// uris)

Additional dependencies are installed via Composer, these include:

** Reactphp (http://reactphp.org/)

** ZF2 Logger (http://framework.zend.com/manual/2.0/en/modules/zend.log.overview.html)

Installation

The recommended method of installation is using Composer. Add the following to your composer.json file:

=5.3.9", "educoder/pest": "1.0.0", "devristo/phpws": "dev-master", "greenfieldtech-nirs/phpari": "dev-master" } } ">

{
    "require": {
        "php": ">=5.3.9",
        "educoder/pest": "1.0.0",
        "devristo/phpws": "dev-master",
        "greenfieldtech-nirs/phpari": "dev-master"
    }
}

We recommend using the "dev-master" version at this point in time, as we are still under heavy development and testing.

Configuring phpari.ini

The phpari.ini file is our primary configuration file. You can define your own, just make sure to initiate your phpari object correctly. The files' contents is as following:

[general]
debug=0
logfile=console ; console for direct console output, filename for file based logging

[asterisk_ari]
username=testuser
password=testing
host=your_asterisk_server_ip_or_fqdn
port=your_asterisk_http_port
endpoint=/ari
transport=ws ; ws for none encrypted, wss for encrypted (currently, only ws is supported)

[asterisk_manager]
username=amiuser
password=amipassword
host=127.0.0.1
port=5038

As you may notice, we already carry an Asterisk Manager configuration in there - this will be used in the future to provide an Asterisk manager connector object as well.

Verify functionality

The simplest way to verify that phpari is installed correctly is by using it. Here is a minimal script to ensure you every installed correctly:

channels()->channel_list()) . "\n"; echo "Ending ARI Connection\n"; ">

require_once("vendor/autoload.php");

echo "Starting ARI Connection\n";
$ariConnector = new phpari();
echo "Active Channels: " . json_encode($ariConnector->channels()->channel_list()) . "\n";
echo "Ending ARI Connection\n";

The output should resemble the following:

[root@ari agi-bin]# php test.php
Starting ARI Connection
Active Channels: []
Ending ARI Connection

Error Handling within PHPARI

In order to allow for better error handling, we've decided to hold two variables, within the initiated phpari object. These are "lasterror" and "lasttrace". When an error occures, in any of the phpari module requests, be it a PEST error or another, an exception is thrown internally. In order not to break your applications, we will return a FALSE value, while populating the "lasterror" and "lasttrace" variables.

For example:

applications_list(); if ((!$result) && (count($result))) throw new Exception("phpari error occured", 503); echo json_encode($result); exit(0); } catch (Exception $e) { echo "Error: " . $conn->lasterror. "\n"; echo "Trace: " . $conn->lasttrace. "\n"; } ">

    try {
        $conn = new phpari("hello-world"); //create new object
        $app  = new applications($conn);

        $result=$app->applications_list();

        if ((!$result) && (count($result)))
            throw new Exception("phpari error occured", 503);

        echo json_encode($result);
        exit(0);

    } catch (Exception $e) {
        echo "Error: " . $conn->lasterror. "\n";
        echo "Trace: " . $conn->lasttrace. "\n";
    }

In the above case, we try to issue an "applications" GET request over to our Asterisk server. In case of an error, the applications object will return a FALSE value, while populating the "lasterror" and "lasttrace" variables. Here is a sample output, for a case where the "port" configuration is wrong, in phpari.ini:

$ php ApplicationList.php
Error: Failed connect to 178.62.XXX.XXX:8080; No error
Trace: #0 C:\Users\nirsi_000\Documents\phpari\vendor\educoder\pest\Pest.php(128): Pest->doRequest(Resource id #60)
#1 C:\Users\nirsi_000\Documents\phpari\src\interfaces\applications.php(58): Pest->get('/applications')
#2 C:\Users\nirsi_000\Documents\phpari\examples\ApplicationList.php(33): applications->applications_list()
#3 {main}

Basic Stasis application programming

Stasis is an event driven environment, which isn't really the native environment for PHP. However, thanks to PHP 5.3 and the React library, it is possible to write a "callback" based web socket client. The following example shows how this can be done - the complete example is under examples/BasicStasisApplication.php.

First, we need to setup our basic Stasis connection to Asterisk:

phpariObject = new phpari($appname); $this->ariEndpoint = $this->phpariObject->ariEndpoint; $this->stasisClient = $this->phpariObject->stasisClient; $this->stasisLoop = $this->phpariObject->stasisLoop; $this->stasisLogger = $this->phpariObject->stasisLogger; $this->stasisEvents = $this->phpariObject->stasisEvents; } catch (Exception $e) { echo $e->getMessage(); exit(99); } } ">

    class BasicStasisApplication
    {

        private $ariEndpoint;
        private $stasisClient;
        private $stasisLoop;
        private $phpariObject;
        private $stasisChannelID;
        private $dtmfSequence = "";

        public $stasisLogger;

        public function __construct($appname = NULL)
        {
            try {
                if (is_null($appname))
                    throw new Exception("[" . __FILE__ . ":" . __LINE__ . "] Stasis application name must be defined!", 500);

                $this->phpariObject = new phpari($appname);

                $this->ariEndpoint  = $this->phpariObject->ariEndpoint;
                $this->stasisClient = $this->phpariObject->stasisClient;
                $this->stasisLoop   = $this->phpariObject->stasisLoop;
                $this->stasisLogger = $this->phpariObject->stasisLogger;
                $this->stasisEvents = $this->phpariObject->stasisEvents;
            } catch (Exception $e) {
                echo $e->getMessage();
                exit(99);
            }
        }

Note this, the constructor will normally return no errors for this stage, as we are mearly building the required objects, not connecting to Asterisk yet. Now, we need to define our Stasis Connection Handler:

stasisLogger->notice("Request received!"); }); $this->stasisClient->on("handshake", function () { $this->stasisLogger->notice("Handshake received!"); }); $this->stasisClient->on("message", function ($message) { $event = json_decode($message->getData()); $this->stasisLogger->notice('Received event: ' . $event->type); $this->stasisEvents->emit($event->type, array($event)); }); } catch (Exception $e) { echo $e->getMessage(); exit(99); } } ">

        public function StasisAppConnectionHandlers()
        {
            try {
                $this->stasisClient->on("request", function ($headers) {
                    $this->stasisLogger->notice("Request received!");
                });

                $this->stasisClient->on("handshake", function () {
                    $this->stasisLogger->notice("Handshake received!");
                });

                $this->stasisClient->on("message", function ($message) {
                    $event = json_decode($message->getData());
                    $this->stasisLogger->notice('Received event: ' . $event->type);
                    $this->stasisEvents->emit($event->type, array($event));
                });

            } catch (Exception $e) {
                echo $e->getMessage();
                exit(99);
            }
        }

Note that we will be ommiting an Event for any additional Asterisk Stasis "message" that is received. Now, we need to actually build our connection to Asterisk:

        public function execute()
        {
            try {
                $this->stasisClient->open();
                $this->stasisLoop->run();
            } catch (Exception $e) {
                echo $e->getMessage();
                exit(99);
            }
        }

Our main script body would be the following:

stasisLogger->info("Starting Stasis Program... Waiting for handshake..."); $basicAriClient->StasisAppEventHandler(); $basicAriClient->stasisLogger->info("Connecting... Waiting for handshake..."); $basicAriClient->execute(); ">

    $basicAriClient = new BasicStasisApplication("hello-world");

    $basicAriClient->stasisLogger->info("Starting Stasis Program... Waiting for handshake...");
    $basicAriClient->StasisAppEventHandler();

    $basicAriClient->stasisLogger->info("Connecting... Waiting for handshake...");
    $basicAriClient->execute();

That's it - this is your most basic Stasis application. We suggest that you now take a look at examples/BasicStasisApplication.php to see the entire code in action.

Reporting Issues

Please report issues directly via the Github project page.

Contibuting Code

We are very open when it comes to people contributing code to this project. In order to make life easier, here is the preferred method to contribute code:

For bug fixes and security updates in Master branch:

Fork the Master Branch into your own personal Github account
Update your local fork
Generate a pull request from your own fork over to our Master Branch

For new features and improvement:

Fork the Development Branch into your own personal Github account
Update your local fork
Generate a pull request from your own fork over to our development branch

We will do our best to go over the various contributions as fast as possible. Bug fixes and security updates will be handled faster - feature improvements will be added to the next major release.

Our IDE of choice is phpStorm from JetBrains (http://www.jetbrains.com/phpstorm/) - we use the default styling, so no need to change that. If you use a different IDE, please make sure you update your IDE to support the internal styling of the project, so that you don't break the general code styling.

Make sure to document your code - once it's merged in, we will need to keep working on your code, so please make sure your documentation will be clear and concise, so we can continue your work (as required).

Our objective is to involve the community as much as possible, so feel free to jump in and assist. Contibutions to the project will automatically put your name into the README.md file, so that everybody will see your coolness and greatness supporting the Open Source movement and the continuation of this project.

Release Policy

Releasing code into the Open Source is always a challenge, it can be both confusing and dawnting at the same time. In order to make life simple with version numbers, here is our projected release policy (it may change in the future).

Every version will be marked with a Major.Minor.Patch version numbering scheme.

A major release will be released once the code of the library is stable and battle tested. How long does that take? good question, we don't know. Currently, our major release version is 0 - we are still in active development.

A minor release will be released once the code of the library is stable and had been introduced with a significant number of fixes and modifications, and been regressed by several members of the community.

A patch release will be released once the code of the library is stable and had been introduced with minor modifications. These modifications will normally include bug fixes and security updates.

Feature enhancements will only be merged into minor releases, not into patch releases.

Team Members and Contributors

The following list includes names and aliases for people who had something to do with the creation/maintenance of this library. It takes alot of resources to maintain an Open Source project, thus, we will always do our best to make sure contributions and tested and merged as fast as possible.

Nir Simionovich, https://github.com/greenfieldtech-nirs
Leonid Notik, https://github.com/lnotik
Scott Griepentrog, https://github.com/stgnet
Matak, https://github.com/matak

Comments

Problems answering the channel

Hello there,

we've been doing some tests using the library and everything was ok but the answering function. If the call it's answered in the dialplan is ok, but if we try to answer the call inside the stasis it fails (it never answers the call).

We've tested it with Centos/Ubuntu systems and Asterisk13/Asterisk14. The php version always 5.6.

To check the ARI itself we've tested ringing a call, get the channel id and then send a http post to answer the channel, like curl -v -u user:pass -X POST "http://localhost:8088/ari/channels/1487608619.14/answer" and that works, but this (inside the stasis) doesn't: $this->phpariObject->channels()->channel_answer($this->stasisChannelID);

So looks like the Asterisk ARI part it's ok. We're able to manage the channels by ARI.

For the test we've used the example BasicStasisApplication.php without changing anything.

¿That simple test works for you? ¿Does the stasis answer the call?

Thanks for your help ;)

opened by richilp 13
Authentication or connection error should result in exception

If the underlying pest connection fails due to connection or authentication problems, it would be (in my opinion) more useful to have a descriptive exception specifying the nature of the problem rather than just receiving a false return value.

opened by stgnet 13
channel/bridge record

Hi, I'm trying to record a call (by recording a channel or a bridge). I use channels()->channel_record("channelid","file.wav","wav",60,1) and I get "false" as a result. Can anyone help?

opened by rperre 8
Cannot redirect or continue channel

Hi there

I have an ARI application to which I attempted to add a new function using channel_continue

The channel that I am attempting to continue has been answered and had ringing started

When I continue the channel I see dialplan execution continuing in asterisk but I get no audio on the channel. The channel is able to pass audio when, instead of continuing, I start playback on the channel. This is whether or not I specify context,extension,priority, both methods of invocation have the same behavior

Do I need to add the channel to a bridge first or something? It seems like I'm missing something obvious.

Please let me know if you need additional data to help track this down, I will provide whatever is necessary, it will take some time to create a sanitized test case, but I can do that if it's necessary

opened by kunwon1 7
Error Connect Asterisk

Hi everyone, i wrote to you because i have a problem about connection in asterisk .... whe use code asterisk console throws this error ERROR[3075]: res_http_websocket.c:513 ws_safe_read: Error reading from web socket: Connection reset by peer [2018-11-22 19:37:28] WARNING[3075]: ari/ari_websockets.c:128 ast_ari_websocket_session_read: WebSocket read error: Connection reset by peer == WebSocket connection from '192.168.0.20:49921' forcefully closed due to fatal write error

can you help me please?

opened by gabrielmatau79 6

Statis App not receiving events

I got the StatisApp up and running and looking at the code it should be displaying events as they are received, but I never see any.

What am I missing to be able to receive the events?

		$this->stasisClient->on("message", function ($message) {
			$event = json_decode($message->getData());
			$this->stasisLogger->notice('Received event: ' . $event->type);
			$this->stasisEvents->emit($event->type, array($event));
		});

opened by degive 6

storing nonsense variables?

why you store all this variables

private $applications; private $asterisk; private $bridges; private $channels; private $devicestates; private $endpoints; private $events; private $mailboxes; private $recordings; private $sounds; private $playbacks;

if you always create them again?

https://github.com/greenfieldtech-nirs/phpari/blob/master/phpari.php#L142

you cant reach these variables outside of phpari class, because they are private, and when you try reach them you always create a new instance? so why? why you dont test if variable is empty or not and after that decide if you create new instance or not?

opened by matak 5
Testing StasisAppDial.php
Hi,

I am trying to make a Click2call for my Asterisk PBX, at the past I used AMI to make this, but I am trying to realize the same using ARI.

To begin learning how to use the ARI PHP API, I am trying to use StasisAppDial.php, but it seems that it does not executing the StasisAppEventHandler function that is who place the call.

# php StasisAppDial.php 'SIP/101' '30' 2018-09-11T03:46:12-07:00 INFO (6): Starting Stasis Program... Waiting for handshake... 2018-09-11T03:46:12-07:00 INFO (6): Initializing Handlers... Waiting for handshake... 2018-09-11T03:46:12-07:00 INFO (6): Connecting... Waiting for handshake... 2018-09-11T03:46:12-07:00 NOTICE (5): Request received! 2018-09-11T03:46:12-07:00 NOTICE (5): Handshake received!

I do not know if this is the right place to place my query. Can you tell me the place when I can resolve my question?. Thanks in advance.

Best Regards
opened by NewbieVoIP 4

Discussion/Overhaul: Non Blocking Async Request

I did speak to @greenfieldtech-nirs in the past about it and I haven't come back to him which I do apologize for as we were in the middle of rolling out a 1500 seater over multiple countries.

Now that that is over I would like to officially contribute.

Now the problem we where facing is we wrote a application that had a queue split across 12 asterisk servers. Now the amount of calls we handle the blocking aspect of curl was causing a issues. And at least in the project I had to change some calls to async requests.

The reason why I want to discuss is making phpari non blocking in line with phpreact and converting the calls to async is a large change to how the lib is being used. For example

// Current Originate
    $response = $channels->channel_originate(
        'SIP/7001',
        NULL,
        array(
            "extension"      => "7001",
            "context"        => 'from-phone',
            "priority"       => 1,
            "app"            => "",
            "appArgs"        => "",
            "callerid"       => "111",
            "timeout"        => -1,
            "channelId"      => '324234',
            "otherChannelId" => ""
        ),
        array("var1" => "cool")
    );
// Will become callback based 
    $channels->channel_originate(
        'SIP/7001',
        NULL,
        array(
            "extension"      => "7001",
            "context"        => 'from-phone',
            "priority"       => 1,
            "app"            => "",
            "appArgs"        => "",
            "callerid"       => "111",
            "timeout"        => -1,
            "channelId"      => '324234',
            "otherChannelId" => ""
        ),
        array("var1" => "cool"),
        function($response) {
             //Do Something with the response
        }
    );

// Or Promise Based
    $channels->channel_originate(
        'SIP/7001',
        NULL,
        array(
            "extension"      => "7001",
            "context"        => 'from-phone',
            "priority"       => 1,
            "app"            => "",
            "appArgs"        => "",
            "callerid"       => "111",
            "timeout"        => -1,
            "channelId"      => '324234',
            "otherChannelId" => ""
        ),
        array("var1" => "cool")
    )->then(function($response) {
        //Do Something with response
    }, function($error) {
         //Do Something with error
    });

So I don't know seeing it is as large as of usage that it should be done on phpari as a next major release or if it should be done like they do with Predis/Predis and create a new Project for Predis/PredisAsync as that gives people the option of both.

opened by PieterVenter7 4

Connecting 2 incoming channels

I've been pondering over this. Is it possible to connect 2 channels from 2 bridges?

Much like a callcenter would do. If A calls you (B) and you put A on hold while you call C and then you'll want to connect A to C and leave the conversation.

opened by apocsrbs 3
recordings interface, unmute

phpari/src/interfaces/recordings.php in function live, line 199, the "unmute" case $result = $this->pestObject->post($uri);

should be $result = $this->pestObject->delete($uri);

Reference: https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Recordings+REST+API#Asterisk13RecordingsRESTAPI-unmute

Thanks, Mark Ingles

opened by mark-ingles 3
Read any keypress using asterisk

Hello. I started using asterisk and phpari and enjoying too much. i have an issue that i am browsing from past one week if someone can please help.

1: I want to call one of our employee number using phpari. 2: Once the person receive call will be asked to press 1 to accept and 2 to hangup. 3: If employee press 1 will give a call to the client and will connect both.

I DON'T KNOW HOW TO GET THE READ VALUE AFTER ORIGINATING CALL AND THE REST OF STUFF. also if someone guid eme to use phpari or phpagi for my this issue.

opened by kamranali14 3
socket error when i stoping aplication

Socket error when i stoping aplication with $this->stasisLoop->stop(); [2019-04-05 04:52:19] WARNING[7409]: res_http_websocket.c:505 ws_safe_read: Web socket closed [2019-04-05 04:52:19] WARNING[7409]: ari/ari_websockets.c:128 ast_ari_websocket_session_read:

opened by solehi 1

CALLERID(name) does not work,

Hi @greenfieldtech-nirs I am using the basic StasisAppDial.php example, but It doesn't work when I send "CALLERID(name)" => "test"

Could there be a bug in the library?

$response = $this->phpariObject->channels()->channel_originate(
                        $args[0],
                        NULL,
                        array(
                            "app"     => "stasis-dial",
                            "appArgs" => '',
                            "timeout" => $args[1],
                            "callerId" => '888888888'
                        ),
                        array(
                            "CALLERID(name)" => "test"
                        )
                    );

opened by wilcarjose 6

Guzzle issues on php 7.1

Having an error with php 7.1 - I've tried updating the guzzle but no luck.

PHP Fatal error: Cannot use lexical variable $eventName as a parameter name in /home/asd/vendor/guzzlehttp/guzzle/src/Event/Emitter.php on line 49

opened by bashong 3
Migration to guzzle incomplete?

Hi @greenfieldtech-nirs, the changes merged in PR https://github.com/greenfieldtech-nirs/phpari/pull/49 seems to break functionality. Some examples of errors introduced with the changes are below:

PHP Notice: Undefined property: asterisk::$pestObject in /var/ari/vendor/greenfieldtech-nirs/phpari/src/interfaces/asterisk.php on line 113 PHP Fatal error: Call to a member function get() on a non-object in /var/ari/vendor/greenfieldtech-nirs/phpari/src/interfaces/asterisk.php on line 113 PHP Notice: Undefined index: protocol in /var/ari/vendor/greenfieldtech-nirs/phpari/phpari.php on line 100 PHP Notice: Undefined property: asterisk::$pestObject in /var/ari/vendor/greenfieldtech-nirs/phpari/src/interfaces/asterisk.php on line 113 PHP Fatal error: Call to a member function get() on a non-object in /var/ari/vendor/greenfieldtech-nirs/phpari/src/interfaces/asterisk.php on line 113 PHP Notice: Undefined index: protocol in /var/ari/vendor/greenfieldtech-nirs/phpari/phpari.php on line 100 PHP Notice: Undefined property: phpari::$ariEndpoint in /var/ari/lib/StasisAppCore.php on line 56 PHP Notice: Undefined property: asterisk::$pestObject in /var/ari/vendor/greenfieldtech-nirs/phpari/src/interfaces/asterisk.php on line 113 PHP Fatal error: Call to a member function get() on a non-object in /var/ari/vendor/greenfieldtech-nirs/phpari/src/interfaces/asterisk.php on line 113

So at first glance I am guessing that the React guzzle refactor is incomplete possibly? I would have expected changes in all of the interface files instead of just applications.php. Since this is a fairly significant change can it be done in a different branch or version so that we can set the old version in our composer.json until the refactor is stable/complete?

opened by twoodard-datto 2

Releases(0.3)

0.3(Feb 5, 2015)

PHPARI is a PHP development library for developing Asterisk Stasis and ARI applications using PHP. Release 3 is the latest stable release is the recommended release for production use.

*Pull requests are welcome.
Source code(tar.gz)
Source code(zip)