<?php
/**
 *=-------------------------------------------------------------------------=
 * Swajax.php
 *=-------------------------------------------------------------------------=
 * This class contains a PHP Ajax wrapper-like class -- there's so much
 * duplicated code that i'm going to try and factor out most of it into
 * a nifty class like this.
 *
 * Basic usage pattern:
 *
 * - Create Swajax object.  This will initialise the responseArray that
 *    will be sent back as JavaScript on output.
 * - call setResponseVariableXX(string, value) on it.  This will add an element
 *    with the given string name to the responseAray on output.  The type is
 *    controlled by XX, and is only really important for non-simple types such
 *    as strings and arrays, etc.
 * - call transmitError(string [, Exception]) when an error occurs.  This
 *    will cause the class to write an entry to the Ajax Error log and return
 *    an error code.
 * - call transmitRedirect(string) for those cases where you want to have the
 *    calling page load in a new page.
 * - call transmitOK() to send the final response to the caller when all is 
 *    well.
 *
 * The class will always set the 'code' field of the responseArray to the
 * text string of the code.  All callers MUST expect at least ERROR on
 * return, and one of OK or REDIR.  other codes are as defined by the PHP
 * code and should be handled in JavaScript appropriately.
 *
 * Created by marc wandschneider, 2005-07-25
 * Released under the GPL, license details available at http://swik.net/SWiK
 */

class SwajaxException extends Exception {}


class SwajaxCore
{
    /**
     * We'll set ourselves up to allow customisation of this in the future,
     * but for now, it'll always be responseArray ...
     */
    protected $m_javaScriptArrayName = 'responseArray';

    /**
     * This contains the list of array indices, and then the value that will
     * go at that index in the responseArray.  Structure is:
     *
     * indexName => array(type, value);
     * 
     * Type can be s (string), a (array), or o (other).  
     */
    protected $m_responseArray;

    /**
     * "which" ajax call path are we executing?  The name of the form being
     * submitted, or functionality is fine -- we just need something so that
     * somebody looking through the Ajax error logs would know WHERE the error
     * occurred.
     */
    protected $m_ajaxCalLName;


    /**
     *=---------------------------------------------------------------------=
     * __construct
     *=---------------------------------------------------------------------=
     * Initialises a new instance of this class. 
     */
    public function __construct($in_ajaxCallName)
    {
        global $g_errorsToOutputStream;
        global $g_errorText;

        //
        // tell the error subsystem to send all errors to g_errorText...
        //
        $g_errorsToOutputStream = FALSE;

        $this->m_responseArray = array();
        $this->m_ajaxCallName = $in_ajaxCallName;

    }


    /**
     *=---------------------------------------------------------------------=
     * setResponseVariableString
     *=---------------------------------------------------------------------=
     * Instructs us to send a variable of the given name back to the client
     * of type String.
     *
     * @param String     The name of the response variable.
     * @param String     The value to pass back.
     */
    public function setResponseVariableString($in_name, $in_value)
    {
        if ($in_name == '')
            throw new InvalidArgumentException('$in_name');

        $this->m_responseArray[$in_name] = array ('s', $in_value);
    }


    /**
     *=---------------------------------------------------------------------=
     * setResponseVariableNumber
     *=---------------------------------------------------------------------=
     * Instructs us to send a variable of the given name back to the client
     * of type Number.
     *
     * @param String     The name of the response variable.
     * @param integer/double     The value to pass back.
     */
    public function setResponseVariableNumber($in_name, $in_value)
    {
        if ($in_name == '')
            throw new InvalidArgumentException('$in_name');

        $this->m_responseArray[$in_name] = array ('o', $in_value);
    }


    /**
     *=---------------------------------------------------------------------=
     * setResponseVariableBoolean
     *=---------------------------------------------------------------------=
     * Instructs us to send a variable of the given name back to the client
     * of type Boolean.
     *
     * @param String     The name of the response variable.
     * @param Boolean    The value to pass back.
     */
    public function setResponseVariableBoolean($in_name, $in_value)
    {
        if ($in_name == '')
            throw new InvalidArgumentException('$in_name');

        if ($in_value == TRUE)
            $this->m_responseArray[$in_name] = array('o', 'true');
        else
            $this->m_responseArray[$in_name] = array('o', 'false');
    }


    /**
     *=---------------------------------------------------------------------=
     * transmit
     *=---------------------------------------------------------------------=
     * Send the final results to the client in the responseArray JavaScript
     * variable.
     */
    public function transmit()
    {
        $this->transmitFinalResultsAndExit();
    }


    /**
     *=---------------------------------------------------------------------=
     * transmitFinalResultsAndExit
     *=---------------------------------------------------------------------=
     * Send the final results to the client in the responseArray JavaScript
     * variable and then terminate the PHP script execution.
     */
    protected function transmitFinalResultsAndExit()
    {
        global $g_errorText;

        //
        // make sure the client gets the right content type ...
        //
        header('Content-Type: text/javascript');

        //
        // If an error was generated by PHP before we started executing Ajax
        // code and something was sent to stdout, then we will capture that
        // now, stuff it in a log file, and report an error.  That should 
        // never happen in normal use scenarios of Ajax ...
        //
        $this->checkForPHPErrorsOnOutput();

        //
        // if an error was generated while executing this ajax request,
        // we told the error subsystem to put it in a global variable
        // called $g_errorText.  so, if this is set, something bad
        // happened and we need to abortimify.
        //
        if ($g_errorText != '')
        {
            $this->m_responseArray = array();
            $this->m_responseArray['code'] = array('s', 'ERROR');
        }

        //
        // emit the common portions of the output stream.
        //
        echo "var responseArray = new Array();\n";

        //
        // start output of values for the array.
        //
        foreach ($this->m_responseArray as $name => $valueInfo)
        {
            switch ($valueInfo[0])
            {
                case 'o':
                    echo "responseArray['$name'] = {$valueInfo[1]};\n";
                    break;

                case 's':
                    $str = Util::stringForJavascript($valueInfo[1]);
                    echo "responseArray['$name'] = \"$str\";\n";
                    break;

                case 'a':
                    throw new InternalErrorException(
                        'Swajax array support not implemented');
                    break;
                default:
                    throw new InternalErrorException(
                        'Invalid value type in Swajax transmission');
                    break;
            }
        }

        //
        // be-de-be-de-be-de that's all folks!!
        //
        ob_end_flush();
        exit;
    }


    /**
     *=---------------------------------------------------------------------=
     * checkForPHPErrorsOnOutput
     *=---------------------------------------------------------------------=
     * Looks to see if any PHP errors were thrown while executing this
     * code.
     */
    protected function checkForPHPErrorsOnOutput()
    {
        $str = trim(ob_get_contents());
        if ($str != '')
        {
            //
            // text was found in the stream, indicating an error, so generate
            // an error and abort.
            //
            $this->responseArray = array('code' => array('s', 'ERROR'));
        }
    }
}


class Swajax extends SwajaxCore
{
    /**
     *=---------------------------------------------------------------------=
     * transmitOK
     *=---------------------------------------------------------------------=
     * Sends the response data with an OK response code.
     */
    public function transmitOK()
    {
        $this->m_responseArray['code'] = array('s', 'OK');
        $this->transmitFinalResultsAndExit();
    }


    /**
     *=---------------------------------------------------------------------=
     * transmitRedirect
     *=---------------------------------------------------------------------=
     * Sends the response data with an REDIR response code and the URL to go
     * to.
     *
     * @param String    The URL to which the client should be redirected.
     */
    public function transmitRedirect($in_url)
    {
        $this->m_responseArray['code'] = array('s', 'REDIR');
        $this->m_responseArray['redirect'] = array('s', $in_url);
        $this->transmitFinalResultsAndExit();
    }


    /**
     *=---------------------------------------------------------------------=
     * tranmitNonfatalError
     *=---------------------------------------------------------------------=
     * Sends the response data with the given error response code.  This error
     * is NOT logged to app.ajax-errors.log
     *
     * @param String    The error response code to send the client.
     * @param String    [optional] An additional error message if j00 want it.
     */
    public function transmitNonfatalError
    (
        $in_code,
        $in_message = ''
    )
    {
        $this->m_responseArray['code'] = array('s', $in_code);
        $this->m_responseArray['errormsg'] = array('s', $in_message);
        $this->transmitFinalResultsAndExit();
    }


    /**
     *=---------------------------------------------------------------------=
     * tranmitFatalError
     *=---------------------------------------------------------------------=
     * Sends the response data with the given error response code.  This error
     * IS logged to app.ajax-errors.log
     *
     * @param String    The error response code to send the client.
     * @param String    [optional] An additional error message if j00 want it.
     */
    public function transmitFatalError
    (
        $in_code,
        $in_exception
    )
    {
        $this->m_responseArray['code'] = array('s', $in_code);
        $this->transmitFinalResultsAndExit();
    }


}


?>