ACCESSING SPEAGRAM ON THE WEB WITH PHP

Assume that you have created a simple Speagram grammar with our live interface and now you want to use it from your web site with PHP. Let us concentrate on the very basic test.php file that we prepared for use with this tutorial. This file just loads the basic Speagram library and can be used for example as an calculator. On this page you will learn how to query this or any other Speagram live file from PHP.

Speagram XML Output

Just over the bottom part of the test.php file you can see two buttons — one to get the XSLT stylesheet and the other to get the SRGS grammar corresponding to the live file. Whenever you need them for your developement work with any Speagram live file just click there.

Let us now show you how to get Speagram output in XML through the web. Please first open the XML output window for the test.php file. You will see that what you get is an XML file without associated stylesheet that contains the Speagram response and looks like this:

<speagram-response>
<speagram-comment>// PART 0 with ID 1.</speagram-comment>

<speagram-message>
<spg-msg-general>Loaded state ../library/basic.</spg-msg-general>
<spg-msg-detail></spg-msg-detail>
</speagram-message>

<speagram-result>
<term class="C7">
</term>
<type class="Tnatural_number">
</type>
</speagram-result>
</speagram-response>

What you see here is the response in internal Speagram XML format. This format is normally translated to give readable output using the corresponding XSLT stylesheet generated by Speagram. You can influence the XSLT from within Speagram to output terms in non-standard way, we show how to do this in the web music example. If you want to use the pure Speagram XML directly you might need to know how class names for terms and types are constructed in Speagram from the syntax definitions you enter. This is documented in the speagram.pdf (or speagram.ps) file.

HTTP Queries to Speagram Live Files

After taking a look at the XML output from Speagram you should look at the URL used to generate the XML:

http://www.speagram.org/useme/test.php?cmd=run_get&
  name=test&
  len=1&
  xml=yes&
  stop=3&
  n0=1&
  t1=This%20is%20a%20very%20basic%20Speagram%20live%20file%20to%20show%20how
     %20the%20live%20system%20works.%0A%25%24%0ALoad%20state%20library%3A%2F
     basic.%0A3%2B4.%0A%24%25%0A

As you can see in the example above each Speagram live file provides HTTP GET interface to run Speagram. In fact each live file provides a POST interface as well and using POST is more welcome (and GET will fail with longer queries). But for the sake of this tutorial let us stay with GET. The query consists of command specification (cmd, run_get for GET queries and run for POST queries), file name, number of parts in the file, xml flag for output, part number to stop on (ignored when it is bigger than len), and encoded parts.

To use the above description from you PHP file just run the following PHP file and see the results.

<?php
  function query_test_file ($query) {
    $url = "http://www.speagram.org/useme/test.php";
    $name = test;

    $prefix = "$url?cmd=run_get&name=$name&len=1&stop=3&n0=1&xml=yes";
    $speagram_query = "$prefix&t1=" . rawurlencode ($query);
    return file_get_contents ($speagram_query);
  }

  echo query_test_file ('%$Load state library:/basic. 2+3.$%');
?>

With the example above you should be comfortable to query Speagram live files from your PHP scripts. If you want to learn how to use Speagram's XSLT functions and combine Speagram with other Open Source tools to get more out of it proceed to our web music example.