In this article by Nir Simionovich, we will develop our first ever AGI script using PHP scripting language. This article deals with the most basic elements of AGI scripting and the information contained within. So, take time to familiarize yourself with this article, especially if you intend to use a language different from PHP.

PHP-CLI vs PHP-CGI

Most Linux distributions include both versions of PHP when installed, especially if you are using a modern distribution such as CentOS or Mandriva. When writing AGI scripts with PHP, it is imperative that you use PHP-CLI, and not PHP-CGI.

Why is this so important? The main issue is that PHP-CLI and PHP-CGI handle their STDIN (standard input) slightly differently, which makes the reading of channel variables via PHP-CGI slightly more problematic.

The php.ini configuration file

The PHP interpreter includes a configuration file that defines a set of defaults for the interpreter. For your scripts to work in an efficient manner, the following must be set—either via the php.ini file, or by your PHP script:

ob_implicit_flush(false); 
set_time_limit(5); 
error_log = filename;
error_reporting(0);

The above code snippet performs the following:

AGI script permissions

All AGI scripts must be located in the directory /var/lib/asterisk/agi-bin, which is Asterisk's default directory for AGI scripts. All AGI scripts should have the execute permission, and should be owned by the user running Asterisk. If you are unfamiliar with these, consult with your system administrator for additional information.

The structure of a PHP based AGI script

Every PHP based AGI script takes the following form:

#!/usr/bin/php -q 
<?
   $stdin = fopen(‘php://stdin’, ‘r’);
   $stdout = fopen(‘php://stdout’, ‘w’); 
   $stdlog = fopen(‘my_agi.log’, ‘w’);


   /* Operational Code starts here */
   ..
   ..
   ..
?>

Upon execution, Asterisk transmits a set of information to our AGI script via STDIN. Handling of that input is best performed in the following manner:

#!/usr/bin/php -q 
<?
   $stdin = fopen(‘php://stdin’, ‘r’);
   $stdout = fopen(‘php://stdout’, ‘w’); 
   $stdlog = fopen(‘my_agi.log’, ‘w’);

   /* Handling execution input from Asterisk */

   while (!feof($stdin)) 
   { 
  	 $temp = fgets($stdin); 
  	 $temp = str_replace("n","",$temp); 
  	 $s = explode(":",$temp); 
  	 $agivar[$s[0]] = trim($s[1]); 
  	 if $temp == "")  
      { 
    	break; 
  	} 
   }

   /* Operational Code starts here */
   ..
   ..
   ..
?>

Once we have handled our inbound information from the Asterisk server, we can start our actual operational flow.

Communication between Asterisk and AGI

The communication between Asterisk and an AGI script is performed via STDIN and STDOUT (standard output). Let's examine the following diagram:

In the above diagram, ASC refers to our AGI script, while AST refers to Asterisk itself.

As you can see from the diagram above, the entire flow is fairly simple. It is just a set of simple I/O queries and responses that are carried through the STDIN/STDOUT data streams.

Let's now examine a slightly more complicated example:

The above figure shows an example that includes two new elements in our AGI logic—access to a database, and to information provided via a web service. For example, the above image illustrates something that may be used as a connection between the telephony world and a dating service. This leads to an immediate conclusion that just as AGI is capable of connecting to almost any type of information source, depending solely on the implementation of the AGI script and not on Asterisk, Asterisk is capable of interfacing with almost any type of information source via out-of-band facilities.

Enough of talking! Let's write our first AGI script.