root/trunk/patForms/Parser.php

<?PHP
/**
 * class to parse an HTML document or patTemplate and extract all
 * patForms elements. They will be replaced by placeholders.
 *
 * $Id$
 *
 * @author        Stephan Schmidt <schst@php-tools.net>
 * @package        patForms
 * @subpackage    Parser
 * @license        LGPL
 * @copyright    PHP Application Tools <http://www.php-tools.net>
 */

/**
 * file does not exist
 */
define( 'PATFORMS_PARSER_ERROR_FILE_NOT_FOUND', 100000 );
 
/**
 * file could not be created
 */
define( 'PATFORMS_PARSER_ERROR_FILE_NOT_CREATED', 100001 );

/**
 * element cannot be serialized
 */
define( 'PATFORMS_PARSER_ERROR_ELEMENT_NOT_SERIALIZEABLE', 100002 );

/**
 * element cannot be serialized
 */
define( 'PATFORMS_PARSER_ERROR_CACHEDIR_NOT_VALID', 100003 );

/**
 * no namespace has been declared
 */
define( 'PATFORMS_PARSER_ERROR_NO_NAMESPACE', 100004 );

/**
 * static property does not exist
 */
define( 'PATFORMS_PARSER_ERROR_NO_STATIC_PROPERTY', 100005 );

/**
 * basedir is not valid
 */
define( 'PATFORMS_PARSER_ERROR_BASEDIR_NOT_VALID', 100006 );

/**
 * no closing tag found
 */
define( 'PATFORMS_PARSER_ERROR_NO_CLOSING_TAG', 100007 );

/**
 * invalid tag found
 */
define( 'PATFORMS_PARSER_ERROR_INVALID_CLOSING_TAG', 100008 );

/**
 * invalid tag found
 */
define( 'PATFORMS_PARSER_ERROR_DRIVER_FILE_NOT_FOUND', 100009 );

/**
 * invalid tag found
 */
define( 'PATFORMS_PARSER_ERROR_DRIVER_CLASS_NOT_FOUND', 100010 );

/**
 * form does not exist
 */
define( 'PATFORMS_PARSER_ERROR_FORM_NOT_FOUND', 100011 );

/**
 * unknown tag in custom namespace
 */
define('PATFORMS_PARSER_ERROR_UNKNOWN_TAG', 100020);

/**
 * static properties
 * @var     array
 * @access    private
 */  
$GLOBALS['_patForms_Parser']    =    array( 
                                        'cacheFolder'                =>    false,
                                        'baseDir'                    =>    false,
                                        'namespace'                    =>    false,
                                        'placeholder'                =>    '{PATFORMS_ELEMENT_%s}',
                                        'placeholder_form_start'    =>    '{PATFORMS_FORM_%s_START}',
                                        'placeholder_form_end'        =>    '{PATFORMS_FORM_%s_END}',
                                        'placeholder_case'            =>    'upper',
                                        'namespaceHandlers'            =>    array()
                                    );


/**
 * class to parse an HTML document or patTemplate and extract all
 * patForms elements. They will be replaced by placeholders.
 *
 * It is possible to attach handlers for other namespaces.
 * The parser will delegate the tags to these handlers and
 * the return values will be used to create the form instead.
 *
 * Known issues of the parser:
 * - Currently it's only possible to parse one form per document, this will change in future versions
 *
 * @author        Stephan Schmidt <s.schmidt@metrix.de>
 * @package        patForms
 * @subpackage    Parser
 * @license        LGPL
 * @copyright    PHP Application Tools <http://www.php-tools.net>
 */
class patForms_Parser
{
   /**
    * Stores the names of all static properties that patForms_Parser will use as defaults
    * for the properties with the same name on startup.
    *
    * @access    private
    */
    var $staticProperties    =    array(
        'cacheFolder'    =>    'setCacheDir',
        'baseDir'        =>    'setBaseDir',
        'namespace'        =>    'setNamespace',
    );

   /**
    * namespace for form elements
    * @var        string
    * @access    private
    */
    var $_namespace            =    null;

   /**
    * namespace handlers
    * @var        string
    * @access    private
    */
    var $_namespaceHandlers    =    array();

   /**
    * cache folder
    * @var        string
    * @access    private
    */
    var $_cacheFolder    =    null;

   /**
    * base directory
    * @var        string
    * @access    private
    */
    var $_baseDir    =    null;

   /**
    * placeholder template for form elements
    *
    * %s will be replaced with the name of the element
    *
    * @var        string
    * @access    private
    * @see        $_placeholder_case
    */
    var $_placeholder = '{PATFORMS_ELEMENT_%s}';

   /**
    * placeholder template for start of form
    *
    * %s will be replaced with the name of the form
    *
    * @var        string
    * @access    private
    * @see        $_placeholder_case
    * @see        $_placeholder_form_end
    */
    var $_placeholder_form_start = '{PATFORMS_FORM_%s_START}';

   /**
    * placeholder template for start of form
    *
    * %s will be replaced with the name of the form
    *
    * @var        string
    * @access    private
    * @see        $_placeholder_case
    * @see        $_placeholder_form_start
    */
    var $_placeholder_form_end = '{PATFORMS_FORM_%s_END}';

   /**
    * case of the element name in the template
    *
    * @var        string
    * @access    private
    * @see        $_placeholder
    */
    var $_placeholder_case = 'upper';

   /**
    * sourcefile name
    * @var        string
    * @access    private
    */
    var $_sourceFile;

   /**
    * outputfile name
    * @var        string
    * @access    private
    */
    var $_outputFile;

   /**
    * form object
    * @var    object
    * @access    private
    */
    var $_form;
    
   /**
    * name of the current form
    * @var        string
    * @access    private
    */
    var $_currentForm = '__default';

   /**
    * form element definitions
    * @var    array
    * @access    private
    */
    var $_elementDefinitions = array();

   /**
    * form attributes
    * @var    array
    * @access    private
    */
    var $_formAttributes = array();
    
   /**
    * HTML code
    * @access    private
    * @var      string
    */
    var $_html;

   /**
    * elements found during parsing process
    * @access    private
    * @var    array
    */
    var    $_elStack = array();

   /**
    * cdata found during parsing process
    * @access    private
    * @var    array
    */
    var    $_cData    = array();

   /**
    * tag depth
    * @access    private
    * @var    integer
    */
    var    $_depth    =    0;

   /**
    * entities that may be used in attributes
    * @var        array
    * @access    private
    */
    var $_entities    =    array(
                                '&quot;' => '"',
                                '&amp;'  => '&',
                                '&apos;' => '\'',
                                '&gt;'   => '>',
                                '&lt;'   => '<',
                            );

   /**
    * constructor
    *
    * @access    public
    */
    function patForms_Parser()
    {
        $this->__construct();    
    }
    
   /**
    * constructor
    *
    * @access    public
    */
    function __construct()
    {
        foreach ($this->staticProperties as $staticProperty => $setMethod) {
            $propValue = patForms_Parser::getStaticProperty( $staticProperty );
            if (patErrorManager::isError($propValue)) {
                continue;
            }
            
            $this->$setMethod($propValue);
        }

        /**
         * set the placeholders
         */
        $this->setPlaceholder( patForms_Parser::getStaticProperty( 'placeholder' ), patForms_Parser::getStaticProperty( 'placeholder_case' ) );
        $this->setFormPlaceholders( patForms_Parser::getStaticProperty( 'placeholder_form_start' ), patForms_Parser::getStaticProperty( 'placeholder_form_end' ) );
        
        // configure namespace handler
        $nsHandlers    = &patForms_Parser::getStaticProperty('namespaceHandlers');
        $namespaces    = array_keys( $nsHandlers );
        foreach ($namespaces as $ns) {
            $this->addNamespace( $ns, $nsHandlers[$ns] );
        }
    }
    
   /**
    * setCacheDir
    *
    * The cache dir has to be set to utilize the caching features.
    *
    * @access    public
    * @param    mixed        path to the directory or false to disable caching
    * @return    boolean        true on success
    * @see    $_cacheFolder
    */
    function setCacheDir( $dir )
    {
        if ($dir != false) {
            if (!is_dir($dir) || !is_writable($dir)) {
                return patErrorManager::raiseError(
                    PATFORMS_PARSER_ERROR_CACHEDIR_NOT_VALID,
                    "Cache folder '$dir' is either no directory or not writable.",
                    'Check path and permissions'
                );
            }
        }

        if (isset($this) && is_a($this, 'patForms_Parser')) {
            $this->_cacheFolder    = $dir;
        } else {
            patForms_Parser::setStaticProperty('cacheFolder', $dir);
        }
        return  true;
    }
    
    /**
     * Set base directory for all files.
     *
     * @access    public
     * @param    mixed    path to the directory or false reset the basedir
     * @return boolean $result    true on success
     * @see    $_cacheFolder
     */
    function setBaseDir( $dir )
    {
        if( $dir != false )
        {
            if( !is_dir( $dir ) )
            {
                return patErrorManager::raiseError(
                    PATFORMS_PARSER_ERROR_BASEDIR_NOT_VALID,
                    "Base directory '$dir' is does not exist or is no directory"
                );
            }
        }
        
        if( isset( $this ) && is_a( $this, "patForms_Parser" ) )
        {
            $this->_baseDir    =    $dir;
        }
        else
        {
            patForms_Parser::setStaticProperty( "baseDir", $dir );
        }
        
        return  true;
    }
    
   /**
    * Set the namespace for the form elements
    *
    * If this method is called statically, it will set the
    * namespace for future static calls to createFormFromTemplate()
    * and parseFile().
    *
    * If the namespace is set to null, patForms_Parser will try
    * to get the namespace declaration from the (X)HTML document
    * that is being parsed.
    *
    * That means that you should include a 
    * xmlns:myForm="http://www.php-tools.net/patForms/basic"
    * attribute in the root tag of your templates.
    * "myForm" is the namespace that you are using for your
    * patForms elements. Make sure that you are using the
    * correct URI for the attribute so it can be recognized.
    *
    * @access    public
    * @param    string    namespace
    * @see        getNamespacePrefix()
    */
    function setNamespace( $ns )
    {
        if( isset( $this ) && is_a( $this, "patForms_Parser" ) )
        {
            $this->_namespace    =    $ns;
        }
        else
        {
            patForms_Parser::setStaticProperty( "namespace", $ns );
        }
    }
    
   /**
    * Set the placeholder template for elements.
    *
    * When parsing an HTML page that contains patForms elements
    * they will be replaced by placeholders. This method allows
    * you to set the format of the placeholders.
    * 
    * You may specify a format string like you would for
    * sprintf, with one %s that marks where the name of the
    * element will be inserted.
    *
    * @access    public
    * @param    string        placeholder
    * @param    string        flag to indicate, whether the name should be inserted in uppercase ('upper'),
    *                        lowercase ('lower') or how it was specified ('keep').
    * @see        sprintf()
    * @see        setFormPlaceholders()
    */
    function setPlaceholder( $placeholder, $case = "upper" )
    {
        if( isset( $this ) && is_a( $this, "patForms_Parser" ) )
        {
            $this->_placeholder            =    $placeholder;
            $this->_placeholder_case    =    $case;
        }
        else
        {
            patForms_Parser::setStaticProperty( "placeholder", $placeholder );
            patForms_Parser::setStaticProperty( "placeholder_case", $case );
        }
    }
    
   /**
    * Set the placeholder template for form start and end tag.
    *
    * When parsing an HTML page that contains a patForms:Form tag
    * this will be replaced by placeholders. This method allows
    * you to set the format of the placeholders.
    * 
    * You may specify a format string like you would for
    * sprintf, with one %s that marks where the name of the
    * element will be inserted.
    *
    * @access    public
    * @param    string        placeholder for the start tag
    * @param    string        placeholder for the end tag
    * @see        sprintf()
    * @see        setPlaceholder()
    */
    function setFormPlaceholders( $start, $end )
    {
        if( isset( $this ) && is_a( $this, "patForms_Parser" ) )
        {
            $this->_placeholder_form_start    =    $start;
            $this->_placeholder_form_end    =    $end;
        }
        else
        {
            patForms_Parser::setStaticProperty( "placeholder_form_start", $start );
            patForms_Parser::setStaticProperty( "placeholder_form_end", $end );
        }
    }
    
   /**
    * add a namespace handler
    *
    * Namespace handlers can be used to include external
    * data in patForms elements.
    *
    * @access    public
    * @param    string    namespace
    * @param    object    handler
    */
    function addNamespace( $namespace, &$handler )
    {
        if( isset( $this ) && is_a( $this, "patForms_Parser" ) )
        {
            $this->_namespaceHandlers[$namespace]    =&    $handler;
        }
        else
        {
            $ns    =&    patForms_Parser::getStaticProperty( 'namespaceHandlers' );
            $ns[$namespace]    =&    $handler;
        }
    }

   /**
    * parse a file and extract all elements
    *
    * If an outputfile is specified and the cache directory
    * has been set, two files will be created:
    * - the outputfile, containing the HTML code with placeholders for all elements
    * - a cache file that contains a serialized string with the attributes of all elements
    *
    * On the next call to parseFile() patForms_Parser will check
    * if these files exist and use them instead of parsing the sourcefile.
    *
    * @access    public
    * @param    string    $filename    filename
    * @return    boolean
    * @uses        parseString()
    */
    function parseFile( $filename, $outputFile = null )
    {
        $this->_sourceFile    =    $filename;
        $this->_outputFile    =    $outputFile;

        if ($this->_outputFile != null) {
            $cache = $this->_checkCache();
            if ($cache) {
                return true;
            }
        }
                
        $string    = file_get_contents( $this->_adjustFilename( $this->_sourceFile ) );
        if ($string === false) {
            $relative = '(no basedir set)';
            if( !empty( $this->_baseDir ) ) {
                $relative = '(relative to "'.$this->_baseDir.'")';
            }
            
            return patErrorManager::raiseError(
                PATFORMS_PARSER_ERROR_FILE_NOT_FOUND, 
                'Sourcefile could not be read', 
                'Tried to open file "'.$this->_sourceFile.'" '.$relative
            );
        }

        $result    = $this->parseString($string);

        if ($this->_outputFile != null && $this->_cacheFolder != null) {
            $success = $this->_writeHTMLToFile();
            if (patErrorManager::isError($success)) {
                return $success;
            }
                
            $success = $this->_writeFormToFile();
            if (patErrorManager::isError($success)) {
                return $success;
            }
        }
        return    $result;
    }

   /**
    * write the resulting HTML code to a file
    *
    * @access    private
    */
    function _writeHTMLToFile()
    {
        return    $this->_writeToFile( $this->_adjustFilename( $this->_outputFile ), $this->getHTML() );
    }
    
   /**
    * write the form defintions to a cache file
    *
    * @access    private
    */
    function _writeFormToFile()
    {
        $tmp        =    array(
                                'attributes'    =>    $this->_formAttributes,
                                'elements'        =>    $this->_elementDefinitions
                            );
        $formDef    =    serialize( $tmp );
        $cacheFile    =    $this->_getFormCacheFilename();
        return    $this->_writeToFile( $cacheFile, $formDef );
    }

   /**
    * get the filename for the form cache
    *
    * @access    private
    * @return    string
    */
    function _getFormCacheFilename()
    {
        return    $this->_cacheFolder . "/" . md5( $this->_sourceFile ) . ".form";
    }

   /**
    * adjust a filename according to the specified basedir
    *
    * @access    private
    * @param    string        filename
    * @param    string        adjusted filename
    */
    function _adjustFilename( $filename )
    {
        if( !empty( $this->_baseDir ) )
            return    "{$this->_baseDir}/$filename";
        return $filename;
    }
    
   /**
    * write a string to a file
    *
    * I dreamed of a world, where PHP5 has already been declared as
    * stable and I could just use file_put_contents() for such an easy
    * task.
    *
    * @access    private
    * @param    string    $filename
    * @param    string    $data
    */
    function _writeToFile( $file, $data )
    {
        $fp = @fopen( $file, "w" );
        if (!$fp) {
            return patErrorManager::raiseError(
                PATFORMS_PARSER_ERROR_FILE_NOT_CREATED, 
                "Could not create file '$file'.", 
                "File: " . $file 
            );
        }
        flock($fp, LOCK_EX);
        fwrite($fp, $data);
        flock($fp, LOCK_UN);
        fclose($fp);
        return true;
    }
    
    
   /**
    * check, whether a cache can be used
    *
    * @access    private
    * @return    boolean        true, if the cache exists and still is valid, false otherwise
    */
    function _checkCache()
    {
        if( empty( $this->_cacheFolder ) )
            return    false;
            
        if( !file_exists( $this->_outputFile ) )
            return    false;

        $cacheFile    =    $this->_getFormCacheFilename();
            
        if( !file_exists( $cacheFile ) )
            return    false;

        $srcFile    =    $this->_adjustFilename( $this->_sourceFile );
        $srcTime    =    filemtime( $srcFile );
            
        if( filemtime