Merge pull request #145 from tgalopin/phpdoc-improvements

Add more extensions on composer.json, improve phpdocs and remove dead code

Author: goetas

README.md

@@ -75,8 +75,6 @@ print $html5->saveHTML($dom);
 
 // Or save it to a file:
 $html5->save($dom, 'out.html');
-
-?>
 ```
 
 The `$dom` created by the parser is a full `DOMDocument` object. And the

composer.json

@@ -20,6 +20,7 @@
         }
     ],
     "require" : {
+        "ext-ctype": "*",
         "ext-dom": "*",
         "ext-libxml" : "*",
         "php" : ">=5.3.0"

src/HTML5.php

@@ -2,6 +2,7 @@
 namespace Masterminds;
 
 use Masterminds\HTML5\Parser\FileInputStream;
+use Masterminds\HTML5\Parser\InputStream;
 use Masterminds\HTML5\Parser\StringInputStream;
 use Masterminds\HTML5\Parser\DOMTreeBuilder;
 use Masterminds\HTML5\Parser\Scanner;
@@ -160,8 +161,13 @@ public function hasErrors()
      *
      * Lower-level loading function. This requires an input stream instead
      * of a string, file, or resource.
+     *
+     * @param InputStream $input
+     * @param array $options
+     *
+     * @return \DOMDocument
      */
-    public function parse(\Masterminds\HTML5\Parser\InputStream $input, array $options = array())
+    public function parse(InputStream $input, array $options = array())
     {
         $this->errors = array();
         $options = array_merge($this->getOptions(), $options);
@@ -180,8 +186,15 @@ public function parse(\Masterminds\HTML5\Parser\InputStream $input, array $optio
      *
      * Lower-level loading function. This requires an input stream instead
      * of a string, file, or resource.
+     *
+     * @param InputStream $input
+     *            The input data to parse in the form of a InputStream instance.
+     * @param array $options
+     *            An array of options
+     *
+     * @return \DOMDocumentFragment
      */
-    public function parseFragment(\Masterminds\HTML5\Parser\InputStream $input, array $options = array())
+    public function parseFragment(InputStream $input, array $options = array())
     {
         $options = array_merge($this->getOptions(), $options);
         $events = new DOMTreeBuilder(true, $options);

src/HTML5/Parser/DOMTreeBuilder.php

@@ -136,6 +136,7 @@ class DOMTreeBuilder implements EventHandler
     protected $stack = array();
 
     protected $current; // Pointer in the tag hierarchy.
+    protected $rules;
     protected $doc;
 
     protected $frag;
@@ -216,7 +217,7 @@ public function document()
      *
      * @see http://www.w3.org/TR/2012/CR-html5-20121217/syntax.html#concept-frag-parse-context
      *
-     * @return \DOMFragmentDocumentFragment
+     * @return \DOMDocumentFragment
      */
     public function fragment()
     {
@@ -650,15 +651,19 @@ protected function quirksTreeResolver($name)
 
     /**
      * Automatically climb the tree and close the closest node with the matching $tag.
+     *
+     * @param string $tagName
+     *
+     * @return bool
      */
-    protected function autoclose($tag)
+    protected function autoclose($tagName)
     {
         $working = $this->current;
         do {
             if ($working->nodeType != XML_ELEMENT_NODE) {
                 return false;
             }
-            if ($working->tagName == $tag) {
+            if ($working->tagName == $tagName) {
                 $this->current = $working->parentNode;
 
                 return true;
@@ -672,12 +677,16 @@ protected function autoclose($tag)
      *
      * If $this->current or anything above $this->current matches the given tag
      * name, this returns true.
+     *
+     * @param string $tagName
+     *
+     * @return bool
      */
-    protected function isAncestor($tagname)
+    protected function isAncestor($tagName)
     {
         $candidate = $this->current;
         while ($candidate->nodeType === XML_ELEMENT_NODE) {
-            if ($candidate->tagName == $tagname) {
+            if ($candidate->tagName == $tagName) {
                 return true;
             }
             $candidate = $candidate->parentNode;
@@ -688,9 +697,13 @@ protected function isAncestor($tagname)
 
     /**
      * Returns true if the immediate parent element is of the given tagname.
+     *
+     * @param string $tagName
+     *
+     * @return bool
      */
-    protected function isParent($tagname)
+    protected function isParent($tagName)
     {
-        return $this->current->tagName == $tagname;
+        return $this->current->tagName == $tagName;
     }
 }

src/HTML5/Parser/FileInputStream.php

@@ -19,8 +19,9 @@ class FileInputStream extends StringInputStream implements InputStream
     /**
      * Load a file input stream.
      *
-     * @param string $data
-     *            The file or url path to load.
+     * @param string $data The file or url path to load.
+     * @param string $encoding The encoding to use for the data.
+     * @param string $debug A fprintf format to use to echo the data on stdout.
      */
     public function __construct($data, $encoding = 'UTF-8', $debug = '')
     {

src/HTML5/Parser/StringInputStream.php

@@ -65,22 +65,21 @@ class StringInputStream implements InputStream
     /**
      * Create a new InputStream wrapper.
      *
-     * @param $data Data
-     *            to parse
+     * @param string $data Data to parse
+     * @param string $encoding The encoding to use for the data.
+     * @param string $debug A fprintf format to use to echo the data on stdout.
      */
     public function __construct($data, $encoding = 'UTF-8', $debug = '')
     {
         $data = UTF8Utils::convertToUTF8($data, $encoding);
-        if ($debug)
+        if ($debug) {
             fprintf(STDOUT, $debug, $data, strlen($data));
+        }
 
-            // There is good reason to question whether it makes sense to
-            // do this here, since most of these checks are done during
-            // parsing, and since this check doesn't actually *do* anything.
+        // There is good reason to question whether it makes sense to
+        // do this here, since most of these checks are done during
+        // parsing, and since this check doesn't actually *do* anything.
         $this->errors = UTF8Utils::checkForIllegalCodepoints($data);
-        // if (!empty($e)) {
-        // throw new ParseError("UTF-8 encoding issues: " . implode(', ', $e));
-        // }
 
         $data = $this->replaceLinefeeds($data);
 
@@ -95,7 +94,11 @@ public function __construct($data, $encoding = 'UTF-8', $debug = '')
     protected function replaceLinefeeds($data)
     {
         /*
-         * U+000D CARRIAGE RETURN (CR) characters and U+000A LINE FEED (LF) characters are treated specially. Any CR characters that are followed by LF characters must be removed, and any CR characters not followed by LF characters must be converted to LF characters. Thus, newlines in HTML DOMs are represented by LF characters, and there are never any CR characters in the input to the tokenization stage.
+         * U+000D CARRIAGE RETURN (CR) characters and U+000A LINE FEED (LF) characters are treated specially.
+         * Any CR characters that are followed by LF characters must be removed, and any CR characters not
+         * followed by LF characters must be converted to LF characters. Thus, newlines in HTML DOMs are
+         * represented by LF characters, and there are never any CR characters in the input to the tokenization
+         * stage.
          */
         $crlfTable = array(
             "\0" => "\xEF\xBF\xBD",
@@ -126,7 +129,7 @@ public function currentLine()
      */
     public function getCurrentLine()
     {
-        return currentLine();
+        return $this->currentLine();
     }
 
     /**
@@ -281,6 +284,8 @@ public function charsUntil($bytes, $max = null)
      *            substring.
      * @param int $max
      *            The max number of chars to read.
+     *
+     * @return string
      */
     public function charsWhile($bytes, $max = null)
     {

src/HTML5/Parser/Tokenizer.php

@@ -431,6 +431,12 @@ protected function isTagEnd(&$selfClose)
 
     /**
      * Parse attributes from inside of a tag.
+     *
+     * @param string[] $attributes
+     *
+     * @return bool
+     *
+     * @throws ParseError
      */
     protected function attribute(&$attributes)
     {
@@ -489,6 +495,8 @@ protected function attribute(&$attributes)
     /**
      * Consume an attribute value.
      * 8.2.4.37 and after.
+     *
+     * @return string|null
      */
     protected function attributeValue()
     {
@@ -590,6 +598,8 @@ protected function unquotedAttributeValue()
      *            Prepend any leading characters. This essentially
      *            negates the need to backtrack, but it's sort of
      *            a hack.
+     *
+     * @return bool
      */
     protected function bogusComment($leading = '')
     {
@@ -614,6 +624,8 @@ protected function bogusComment($leading = '')
      * Read a comment.
      *
      * Expects the first tok to be inside of the comment.
+     *
+     * @return bool
      */
     protected function comment()
     {
@@ -645,6 +657,8 @@ protected function comment()
 
     /**
      * Check if the scanner has reached the end of a comment.
+     *
+     * @return bool
      */
     protected function isCommentEnd()
     {
@@ -679,6 +693,8 @@ protected function isCommentEnd()
      * not Quirksmode is enabled on the event handler.
      *
      * @todo This method is a little long. Should probably refactor.
+     *
+     * @return bool
      */
     protected function doctype()
     {
@@ -701,13 +717,9 @@ protected function doctype()
             return $this->eof();
         }
 
-        $doctypeName = '';
-
         // NULL char: convert.
         if ($tok === "\0") {
             $this->parseError("Unexpected null character in DOCTYPE.");
-            $doctypeName .= UTF8::FFFD;
-            $tok = $this->scanner->next();
         }
 
         $stop = " \n\f>";
@@ -792,6 +804,7 @@ protected function doctype()
      * @param string $stopchars
      *            Characters (in addition to a close-quote) that should stop the string.
      *            E.g. sometimes '>' is higher precedence than '"' or "'".
+     *
      * @return mixed String if one is found (quotations omitted)
      */
     protected function quotedString($stopchars)
@@ -813,6 +826,8 @@ protected function quotedString($stopchars)
 
     /**
      * Handle a CDATA section.
+     *
+     * @return bool
      */
     protected function cdataSection()
     {
@@ -856,6 +871,8 @@ protected function cdataSection()
      * treated as "bogus comments". However, since we're not a user
      * agent, we allow them. We consume until ?> and then issue a
      * EventListener::processingInstruction() event.
+     *
+     * @return bool
      */
     protected function processingInstruction()
     {
@@ -900,6 +917,10 @@ protected function processingInstruction()
     /**
      * Read from the input stream until we get to the desired sequene
      * or hit the end of the input stream.
+     *
+     * @param string $sequence
+     *
+     * @return string
      */
     protected function readUntilSequence($sequence)
     {
@@ -935,6 +956,11 @@ protected function readUntilSequence($sequence)
      * Example: $this->sequenceMatches('</script>') will
      * see if the input stream is at the start of a
      * '</script>' string.
+     *
+     * @param string $sequence
+     * @param bool $caseSensitive
+     *
+     * @return bool
      */
     protected function sequenceMatches($sequence, $caseSensitive = true)
     {
@@ -976,6 +1002,8 @@ protected function flushBuffer()
      * Add text to the temporary buffer.
      *
      * @see flushBuffer()
+     *
+     * @param string $str
      */
     protected function buffer($str)
     {
@@ -987,6 +1015,10 @@ protected function buffer($str)
      *
      * A parse error always returns false because it never consumes any
      * characters.
+     *
+     * @param string $msg
+     *
+     * @return string
      */
     protected function parseError($msg)
     {
@@ -1009,9 +1041,11 @@ protected function parseError($msg)
      * Returns false if the entity could not be found. If $inAttribute is set
      * to true, a bare & will be returned as-is.
      *
-     * @param boolean $inAttribute
+     * @param bool $inAttribute
      *            Set to true if the text is inside of an attribute value.
      *            false otherwise.
+     *
+     * @return bool|string
      */
     protected function decodeCharacterReference($inAttribute = false)
     {
@@ -1023,7 +1057,6 @@ protected function decodeCharacterReference($inAttribute = false)
 
         // Next char after &.
         $tok = $this->scanner->next();
-        $entity = '';
         $start = $this->scanner->position();
 
         if ($tok == false) {

src/HTML5/Parser/TreeBuildingRules.php

@@ -127,7 +127,6 @@ protected function handleRT($ele, $current)
 
     protected function closeIfCurrentMatches($ele, $current, $match)
     {
-        $tname = $current->tagName;
         if (in_array($current->tagName, $match)) {
             $current->parentNode->appendChild($ele);
         } else {