$Id: Readme,v 1.4 2004/06/02 14:33:38 hfuecks Exp $

++Introduction

XML_HTMLSax3 is a SAX based XML parser for badly formed XML documents,

such as HTML.



The original code base was developed by Alexander Zhukov and published at

http://sourceforge.net/projects/phpshelve/. Alexander kindly gave permission

to modify the code and license for inclusion in PEAR.



PEAR::XML_HTMLSax3 provides an API very similar to the native PHP SAX

extension (http://www.php.net/xml), allowing handlers using one to be

easily adapted to the other. The key difference is HTMLSax will not

break on badly formed XML, allowing it to be used for parsing HTML

documents. Otherwise HTMLSax supports all the handlers available from

Expat except namespace and external entity handlers. Provides methods

for handling XML escapes as well as JSP/ASP opening and close tags.



Version 1.x introduced an API similar to the native SAX extension but

used a slow character by character approach to parsing.



Version 2.x has had it's internals completely overhauled to use a Lexer,

delivering performance *approaching* that of the native XML extension,

as well as a radically improved, modular design that makes adding

further functionality easy.



Version 3.x is about fine tuning the API, behaviour and providing a

mechanism to distinguish HTML "quirks" from badly formed HTML





A big thanks to Jeff Moore (lead developer of WACT:

http://wact.sourceforge.net) who's largely responsible for new design, as well

input from members at Sitepoint's Advanced PHP forums:

http://www.sitepointforums.com/showthread.php?threadid=121246.



Thanks also to Marcus Baker (lead developer of SimpleTest:

http://www.lastcraft.com/simple_test.php) for sorting out the unit tests.



++Uses

Some particular situations where XML_HTMLSax3 can be useful include;

- Template Engines (see WACT for example: http://wact.sf.net)

- Parsing XML documents (such as those online) where the source is

  out of your control and Expat is choking because it's badly formed.

- Converting HTML to XHTML

- Reading HTML based content from a database and converting to PDF (with

  help from a PDF generation library and probably PEAR::XML_SaxFilters as

  well)

- Parsing ASP(.NET) and JSP pages.

- Creating a PHP-GTK based web browser? A PHP CSS Parser exists:

  http://www.phpclasses.org/browse.html/package/1081.html



++Features

- Won't "break" on badly formed XML. May in some instances get it "wrong"

  (see Limitations) but will continue parsing.



- Provides an API similar to the native PHP XML extension so switching code

  from one to the other is typically minimal effort.



- Can be instructed to behave in more or less the same manner as SAX,

  when dealing with linefeeds, tabs and XML entities



- In addition to handling basic XML elements attributes and data also

  capable of dealing with; 

   - Processing instructions e.g. <?php ?> / <?xml ?> etc. Within PI's

     XML entities are not parsed (i.e. ignore < and > )

   - XML Escape markup such as <! >, <!-- --> and <![CDATA[ ]]>. Within

     this XML entities are not parsed (useful for JavaScript, for example)

   - JSP / ASP (JASP) marked up with <% %>. Note: You will need to

     deal with <%@ %> and <%= %> yourself. With JASP markup XML entities

     are not parsed



++Usage Notes



- Performance-wise, it runs faster on PHP 4.3.0 thanks to strspn() and

  strcspn() supporting position arguments. For older PHP versions while

  loops are used to achieve the same effect, meaning a slightly higher

  overhead. Note also that setting XML options with XML_HTMLSax3::set_option()

  also slows down the parser, the options being handled by "decorators"

  which perform some further formatting on XML events which have already

  been parsed.



- By default, no parser options are set



- Regarding the XML_OPTION_ENTITIES_PARSED, this uses the html_entity_decode()

  function which is only available in PHP 4.3.0+. To get round this, HTMLSax

  checks your PHP version and for the function name html_entity_decode. If not

  found, it defines a function which mirrors the behavior of the native PHP

  html_entity_decode().

  Both XML_OPTION_ENTITIES_PARSED and XML_OPTION_ENTITIES_UNPARSED can be used

  down to PHP version 4.0.5, due to the regular expression used to find entities.



- For attributes which have just a name but no value e.g.

  <option value="bar" selected>



  HTMLSax will return a NULL value for that attribute name, when

  calling the opening tag handler;



  function myOpenHandler($parser,$name,$attrs) {

      print_r ( $attrs );

  }



  This would produce;



  Array

  (

      [value] => bar

      [selected] => NULL

  )



- JASP directives like <%@ and <%= will be not be regarded as special.

  I.e. you will get back the @ or % from the contents of the JASP block

  and have to deal with these yourself.



++ Limitations

- XML_HTMLSax3 only supports use of PHP classes as callback handlers;

  there is no support for using PHP functions as handlers.



- The only weird behaviour is for attributes which only have a left quote

  or apostrophe e.g. <tag foo="bar>Some Text</tag> will give you an

  attribute like $attrs['foo']="bar>Some Text"; This is a trade off against

  allowing XML entities like < and > to appear inside attributes.



- Although the package name might suggest otherwise, XML_HTMLSax3 currently

  has no special knowledge of HTML (i.e. there is no understanding of whether

  a given HTML document is well formed or not, according to HTML's rules).

  XML_HTMLSax3 is primarily intended as a SAX based parser that will not

  complain about structure of a document it is asked to parse. It even does

  a fair job of parsing http://static.php.net/www.php.net/images/php.gif ...

  Version 3.x will introduce some basic knowledge of HTML grammar to help with

  identifying HTML "quirks".



- <script /> elements containing < or > characters; these will be treated as new

  elements triggering the listeners. Make sure that any JavaScript inside is marked

  either with an XML comment <!-- --> or a CDATA block <[CDATA[ ]]>

  </script>

  Alternatively define open / close handlers which watch for <script /> elements

  as a special case, so that any further events triggered within them are handled

  as part of the <script /> element.



- If you change the handlers once parsing has started, you will need to re-set

  and parser options you have defined



++ Example Use

Further examples are available in the examples directory of this package.



<?php

// Include HTMLSax

require_once('XML/HTMLSax3.php');



// Define a customer handler class

class MyHandler {

    function MyHandler(){}



    // Opening tags

    function openHandler(& $parser,$name,$attrs) {

        echo ( 'Open Tag Handler: '.$name );

        echo ( 'Attrs:' );

        print_r($attrs);

    }



    // Closing tags

    function closeHandler(& $parser,$name) {

        echo ( 'Close Tag Handler: '.$name );

    }



    // Text node handler

    function dataHandler(& $parser,$data) {

        echo ( 'Data Handler: '.$data );

    }



    // XML escape handler (e.g. HTML comments)

    function escapeHandler(& $parser,$data) {

        echo ( 'Escape Handler: '.$data );

    }



    // Processing instruction handler

    function piHandler(& $parser,$target,$data) {

        echo ( 'PI Handler: '.$target.' - '.$data );

    }



    // JSP / ASP markup handler

    function jaspHandler(& $parser,$data) {

        echo ( 'Jasp Handler: '.$data );

    }

}



// Get some HTML document

$doc = file_get_contents('http://www.php.net');



// Instantiate the handler

$handler=new MyHandler();



// Instantiate the parser

$parser=& new XML_HTMLSax3();



// Register the handler with the parser

$parser->set_object($handler);



// Set a parser option

$parser->set_option('XML_OPTION_TRIM_DATA_NODES');



// Set the callback handlers (MyHandler methods)

$parser->set_element_handler('openHandler','closeHandler');

$parser->set_data_handler('dataHandler');

$parser->set_escape_handler('escapeHandler');

$parser->set_pi_handler('piHandler');

$parser->set_jasp_handler('jaspHandler');



// Parse the document

$parser->parse($doc);

?>