Download the PHP package clue/ami-react without Composer

On this page you can find all versions of the php package clue/ami-react. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package ami-react

clue/reactphp-ami

CI status installs on Packagist

Streaming, event-driven access to the Asterisk Manager Interface (AMI), built on top of ReactPHP.

The Asterisk PBX is a popular open source telephony solution that offers a wide range of telephony features. The Asterisk Manager Interface (AMI) allows you to control and monitor the PBX. Among others, it can be used to originate a new call, execute Asterisk commands or monitor the status of subscribers, channels or queues.

Table of contents

Support us

We invest a lot of time developing, maintaining and updating our awesome open-source projects. You can help us sustain this high-quality of our work by becoming a sponsor on GitHub. Sponsors get numerous benefits in return, see our sponsoring page for details.

Let's take these projects to the next level together! 🚀

Quickstart example

Once installed, you can use the following code to access your local Asterisk instance and issue some simple commands via AMI:

See also the examples.

Usage

Factory

The Factory is responsible for creating your Client instance.

This class takes an optional LoopInterface|null $loop parameter that can be used to pass the event loop instance to use for this object. You can use a null value here in order to use the default loop. This value SHOULD NOT be given unless you're sure you want to explicitly use a given event loop instance.

If you need custom connector settings (DNS resolution, TLS parameters, timeouts, proxy servers etc.), you can explicitly pass a custom instance of the ConnectorInterface:

createClient()

The createClient(string $url): PromiseInterface<Client,Exception> method can be used to create a new Client.

It helps with establishing a plain TCP/IP or secure TLS connection to the AMI and optionally issuing an initial login action.

The method returns a Promise that will resolve with the Client instance on success or will reject with an Exception if the URL is invalid or the connection or authentication fails.

The $url parameter contains the host and optional port (which defaults to 5038 for plain TCP/IP connections) to connect to:

The above example does not pass any authentication details, so you may have to call ActionSender::login() after connecting or use the recommended shortcut to pass a username and secret for your AMI login details like this:

Note that both the username and password must be URL-encoded (percent-encoded) if they contain special characters:

The Factory defaults to establishing a plaintext TCP connection. If you want to create a secure TLS connection, you can use the tls scheme (which defaults to port 5039):

Client

The Client is responsible for exchanging messages with the Asterisk Manager Interface and keeps track of pending actions.

If you want to send outgoing actions, see below for the ActionSender class.

Besides defining a few methods, this interface also implements the EventEmitterInterface which allows you to react to certain events as documented below.

close()

The close(): void method can be used to force-close the AMI connection and reject all pending actions.

end()

The end(): void method can be used to soft-close the AMI connection once all pending actions are completed.

createAction()

The createAction(string $name, array $fields): Action method can be used to construct a custom AMI action.

This method is considered advanced usage and mostly used internally only. Creating Action objects, sending them via AMI and waiting for incoming Response objects is usually hidden behind the ActionSender interface.

If you happen to need a custom or otherwise unsupported action, you can also do so manually as follows. Consider filing a PR to add new actions to the ActionSender.

A unique value will be added to "ActionID" field automatically (needed to match the incoming responses).

request()

The request(Action $action): PromiseInterface<Response,Exception> method can be used to queue the given messages to be sent via AMI and wait for a Response object that matches the value of its "ActionID" field.

This method is considered advanced usage and mostly used internally only. Creating Action objects, sending them via AMI and waiting for incoming Response objects is usually hidden behind the ActionSender interface.

If you happen to need a custom or otherwise unsupported action, you can also do so manually as follows. Consider filing a PR to add new actions to the ActionSender.

event event

The event event (what a lovely name) will be emitted whenever AMI sends an event, such as a phone call that just started or ended and much more. The event receives a single Event argument describing the event instance.

Event reporting can be turned on/off via AMI configuration and the events() action. The events() action can also be used to enable an "EventMask" to only report certain events as per the AMI documentation.

See also AMI Events documentation for more details about event types and their respective fields.

error event

The error event will be emitted once a fatal error occurs, such as when the client connection is lost or is invalid. The event receives a single Exception argument for the error instance.

This event will only be triggered for fatal errors and will be followed by closing the client connection. It is not to be confused with "soft" errors caused by invalid commands.

close event

The close event will be emitted once the client connection closes (terminates).

See also the close() method.

ActionSender

The ActionSender wraps a given Client instance to provide a simple way to execute common actions. This class represents the main interface to execute actions and wait for the corresponding responses.

Actions

All public methods resemble their respective AMI actions.

Listing all available actions is out of scope here, please refer to the class outline.

Note that using the ActionSender is not strictly necessary, but is the recommended way to execute common actions.

If you happen to need a custom or otherwise unsupported action, you can also do so manually. See the advanced createAction() usage above for details. Consider filing a PR to add new actions to the ActionSender.

Promises

Sending actions is async (non-blocking), so you can actually send multiple action requests in parallel. The AMI will respond to each action with a Response object. The order is not guaranteed. Sending actions uses a Promise-based interface that makes it easy to react to when an action is completed (i.e. either successfully fulfilled or rejected with an error):

All actions resolve with a Response object on success, some actions are documented to return the specialized Collection object to contain a list of entries.

Blocking

As stated above, this library provides you a powerful, async API by default.

If, however, you want to integrate this into your traditional, blocking environment, you should look into also using clue/reactphp-block.

The resulting blocking code could look something like this:

Refer to clue/reactphp-block for more details.

Message

The Message is an abstract base class for the Response, Event value objects. It provides a common interface for these three message types.

Each Message consists of any number of fields with each having a name and one or multiple values. Field names are matched case-insensitive. The interpretation of values is application-specific.

getFieldValue()

The getFieldValue(string $key): ?string method can be used to get the first value for the given field key.

If no value was found, null is returned.

getFieldValues()

The getFieldValues(string $key): string[] method can be used to get a list of all values for the given field key.

If no value was found, an empty array() is returned.

getFieldVariables()

The getFieldVariables(string $key): array method can be used to get a hashmap of all variable assignments in the given $key.

If no value was found, an empty array() is returned.

getFields()

The getFields(): array method can be used to get an array of all fields.

getActionId()

The getActionId(): string method can be used to get the unique action ID of this message.

This is a shortcut to get the value of the "ActionID" field.

Response

The Response value object represents the incoming response received from the AMI. It shares all properties of the Message parent class.

getCommandOutput()

The getCommandOutput(): ?string method can be used to get the resulting output of a "command" Action. This value is only available if this is actually a response to a "command" action, otherwise it defaults to null.

Collection

The Collection value object represents an incoming response received from the AMI for certain actions that return a list of entries. It shares all properties of the Response parent class.

You can access the Collection like a normal Response in order to access the leading Response for this collection or you can use the below methods to access the list entries and completion event.

getEntryEvents()

The getEntryEvents(): Event[] method can be used to get the list of all intermediary Event objects where each entry represents a single entry in the collection.

getCompleteEvent()

The getCompleteEvent(): Event method can be used to get the trailing Event that completes this collection.

Action

The Action value object represents an outgoing action message to be sent to the AMI. It shares all properties of the Message parent class.

getMessageSerialized()

The getMessageSerialized(): string method can be used to get the serialized version of this outgoing action to send to Asterisk.

This method is considered advanced usage and mostly used internally only.

Event

The Event value object represents the incoming event received from the AMI. It shares all properties of the Message parent class.

getName()

The getName(): ?string method can be used to get the name of the event.

This is a shortcut to get the value of the "Event" field.

Install

The recommended way to install this library is through Composer. New to Composer?

This project follows SemVer. This will install the latest supported version:

See also the CHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+. It's highly recommended to use the latest supported PHP version for this project.

Tests

To run the test suite, you first need to clone this repo and then install all dependencies through Composer:

To run the test suite, go to the project root and run:

The test suite contains both unit tests and functional integration tests. The functional tests require access to a running Asterisk server instance and will be skipped by default. If you want to also run the functional tests, you need to supply your AMI login details in an environment variable like this:

License

This project is released under the permissive MIT license.

Did you know that I offer custom development services and issuing invoices for sponsorships of releases and for contributions? Contact me (@clue) for details.


All versions of ami-react with dependencies

PHP Build Version
Package Version
Requires php Version >=5.3
evenement/evenement Version ^3.0 || ^2.0 || ^1.0
react/event-loop Version ^1.2
react/promise Version ^3.0 || ^2.9 || ^1.1
react/socket Version ^1.14
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package clue/ami-react contains the following files

Loading the files please wait ....