README

A modern PHP library for creating Cloudonix CXML Voice Applications. This library provides a clean, fluent interface for generating CXML documents using lazy-loading and nested callbacks.

## Vibe-Code Disclaimer ##

This library was created using claude-code and the documentation available at https://developers.cloudonix.com

While the library is tested to produce working results, it is up to you to make sure that it works for you, as 
I make no guarentees as to the quality of this source code - I didn't write it!

Installation

Install the library via Composer:

composer require nir-simionovich/cloudonix-php8

Requirements

PHP 8.0 or newer
ext-xml

Basic Usage

<?php

require_once 'vendor/autoload.php';

use Cloudonix\CXML\CXML;
use Cloudonix\CXML\Verbs\Gather\Gather;
use Cloudonix\CXML\Verbs\Record\Record;

// Create a simple CXML document
$response = CXML::response();
$response->addChild(CXML::say('Hello, world!'));
$response->addChild(CXML::hangup());

// Output the CXML document
header('Content-Type: text/xml');
echo $response->toDocument();

Advanced Usage

The library supports method chaining for a fluent interface:

<?php

require_once 'vendor/autoload.php';

use Cloudonix\CXML\CXML;
use Cloudonix\CXML\Verbs\Gather\Gather;
use Cloudonix\CXML\Verbs\Record\Record;

// Create a more complex CXML document
$response = CXML::response();

// Add a welcome message
$response->addChild(
    CXML::say('Welcome to our system.')
        ->voice('woman')
        ->language('en-US')
);

// Create a gather with nested elements
$gather = CXML::gather()
    ->input('dtmf speech')
    ->timeout(5)
    ->action('https://example.com/handle-input');

// Add nested elements to the gather using children() with a closure
$gather->children(function($cxml) {
    $cxml->say('Please enter your account number followed by the pound key.')
        ->pause(1);
});

// Add the gather to the response
$response->addChild($gather);

// Add a fallback
$response->addChild(CXML::say('We did not receive any input. Goodbye.'));
$response->addChild(CXML::hangup());

// Output the CXML document
header('Content-Type: text/xml');
echo $response->toDocument();

Using Record with Nested Verbs

The Record verb also supports nested verbs (Say, Play, and Pause):

<?php

require_once 'vendor/autoload.php';

use Cloudonix\CXML\CXML;
use Cloudonix\CXML\Verbs\Gather\Gather;
use Cloudonix\CXML\Verbs\Record\Record;

// Create a record verb with nested elements
$record = CXML::record()
    ->action('https://example.com/handle-recording')
    ->playBeep(true)
    ->maxLength(60);

// Add nested elements using the children() method with a closure
$record->children(function($cxml) {
    $cxml->say('Please record your message after the beep.')
        ->pause(1)
        ->play('https://example.com/beep.mp3');
});

// Add the record to the response
$response->addChild($record);

Supported Verbs

Implemented

Say - Convert text to speech
Play - Play an audio file
Pause - Add a period of silence
Hangup - End the call
Redirect - Transfer control to another CXML document
Reject - Reject an incoming call
Gather - Collect input from the caller (with nested verbs)
Record - Record audio from the caller (with nested verbs)
Start - Begin an asynchronous operation (with nested Stream)
Coach - Allow a caller to connect to an existing session and provide coaching
Dial - Connect calls to numbers, conferences, SIP endpoints or service providers:
- Number - Dial subscribers or external numbers
- Conference - Conference calls
- Sip - Direct SIP addresses
- Service - 3rd party service providers
- Header - Custom SIP headers
Converse - Enable conversational AI interactions using LLMs, STT, and TTS:
- System - System prompts for the LLM
- User - User prompts for the LLM
- Tool - External tools for the LLM to use
- Description - Descriptions for tools
- Speech - Placeholder for caller's verbal response

Project Structure

/src/Verbs/Nested/ - Contains the shared VerbBuilder for all nested verbs
/src/Verbs/Gather/ - Contains the Gather verb and its specialized GatherVerbBuilder
/src/Verbs/Record/ - Contains the Record verb and its specialized RecordVerbBuilder
/src/Verbs/Start/ - Contains the Start verb, Stream noun, and specialized StartVerbBuilder
/src/Verbs/Dial/ - Contains the Dial verb and all related nouns (Number, Conference, Sip, Service, Header)
/src/Verbs/Converse/ - Contains the Converse verb and all related nouns (System, User, Tool, Description, Speech)
/src/Verbs/ - Contains the basic verbs that don't support nesting

The project uses inheritance to avoid code duplication, with a shared base builder for nested verbs.

Changelog

See the CHANGES.md file for a detailed list of changes between versions.

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

nir-simionovich / cloudonix-php8

Maintainers

Details