arthurkushman / querypath

src/DOM.php

<?php

namespace QueryPath;


use DOMNode;
use QueryPath\CSS\DOMTraverser;
use QueryPath\Entities;

/**
 * Class DOM
 *
 * @package QueryPath
 *
 * @property \Traversable|array|\SplObjectStorage matches
 */
abstract class DOM implements Query, \IteratorAggregate, \Countable
{

    /**
     * The array of matches.
     */
    protected $matches = [];

    /**
     * Default parser flags.
     *
     * These are flags that will be used if no global or local flags override them.
     *
     * @since 2.0
     */
    public const DEFAULT_PARSER_FLAGS = NULL;

    public const JS_CSS_ESCAPE_CDATA             = '\\1';
    public const JS_CSS_ESCAPE_CDATA_CCOMMENT    = '/* \\1 */';
    public const JS_CSS_ESCAPE_CDATA_DOUBLESLASH = '// \\1';
    public const JS_CSS_ESCAPE_NONE              = '';

    protected $errTypes = 771; //E_ERROR; | E_USER_ERROR;

    protected $document;
    /**
     * The base DOMDocument.
     */
    protected $options = [
        'parser_flags'                 => NULL,
        'omit_xml_declaration'         => false,
        'replace_entities'             => false,
        'exception_level'              => 771, // E_ERROR | E_USER_ERROR | E_USER_WARNING | E_WARNING
        'ignore_parser_warnings'       => false,
        'escape_xhtml_js_css_sections' => self::JS_CSS_ESCAPE_CDATA_CCOMMENT,
    ];

    /**
     * Constructor.
     *
     * Typically, a new DOMQuery is created by QueryPath::with(), QueryPath::withHTML(),
     * qp(), or htmlqp().
     *
     * @param mixed $document
     *   A document-like object.
     * @param string $string
     *   A CSS 3 Selector
     * @param array $options
     *   An associative array of options.
     * @see qp()
     * @throws Exception
     */
    public function __construct($document = NULL, $string = NULL, $options = [])
    {
        $string = trim($string);

It seems like $string can also be of type null; however, parameter $string of trim() does only seem to accept string, maybe add an additional type check?

        $this->options = $options + Options::get() + $this->options;

        $parser_flags = $options['parser_flags'] ?? self::DEFAULT_PARSER_FLAGS;
        if (!empty($this->options['ignore_parser_warnings'])) {
            // Don't convert parser warnings into exceptions.
            $this->errTypes = 257; //E_ERROR | E_USER_ERROR;
        } elseif (isset($this->options['exception_level'])) {
            // Set the error level at which exceptions will be thrown. By default,
            // QueryPath will throw exceptions for
            // E_ERROR | E_USER_ERROR | E_WARNING | E_USER_WARNING.
            $this->errTypes = $this->options['exception_level'];
        }

        // Empty: Just create an empty QP.
        if (empty($document)) {
            $this->document = isset($this->options['encoding']) ? new \DOMDocument('1.0',
                $this->options['encoding']) : new \DOMDocument();
            $this->setMatches(new \SplObjectStorage());
        } // Figure out if document is DOM, HTML/XML, or a filename
        elseif (is_object($document)) {

            // This is the most frequent object type.
            if ($document instanceof \SplObjectStorage) {
                $this->matches = $document;
                if ($document->count() !== 0) {
                    $first = $this->getFirstMatch();
                    if (!empty($first->ownerDocument)) {
                        $this->document = $first->ownerDocument;
                    }
                }
            } elseif ($document instanceof self) {
                //$this->matches = $document->get(NULL, TRUE);
                $this->setMatches($document->get(NULL, true));
                if ($this->matches->count() > 0) {
                    $this->document = $this->getFirstMatch()->ownerDocument;
                }
            } elseif ($document instanceof \DOMDocument) {
                $this->document = $document;
                //$this->matches = $this->matches($document->documentElement);
                $this->setMatches($document->documentElement);
            } elseif ($document instanceof \DOMNode) {
                $this->document = $document->ownerDocument;
                //$this->matches = array($document);
                $this->setMatches($document);
            } elseif ($document instanceof \Masterminds\HTML5) {
                $this->document = $document;
                $this->setMatches($document->documentElement);

The property documentElement does not seem to exist on Masterminds\HTML5.

            } elseif ($document instanceof \SimpleXMLElement) {
                $import = dom_import_simplexml($document);
                $this->document = $import->ownerDocument;
                //$this->matches = array($import);
                $this->setMatches($import);
            } else {
                throw new \QueryPath\Exception('Unsupported class type: ' . get_class($document));
            }
        } elseif (is_array($document)) {
            //trigger_error('Detected deprecated array support', E_USER_NOTICE);
            if (!empty($document) && $document[0] instanceof \DOMNode) {
                $found = new \SplObjectStorage();
                foreach ($document as $item) {
                    $found->attach($item);
                }
                //$this->matches = $found;
                $this->setMatches($found);
                $this->document = $this->getFirstMatch()->ownerDocument;
            }
        } elseif ($this->isXMLish($document)) {
            // $document is a string with XML
            $this->document = $this->parseXMLString($document);
            $this->setMatches($this->document->documentElement);
        } else {

            // $document is a filename
            $context = empty($options['context']) ? NULL : $options['context'];
            $this->document = $this->parseXMLFile($document, $parser_flags, $context);
            $this->setMatches($this->document->documentElement);
        }

        // Globally set the output option.
        $this->document->formatOutput = true;
        if (isset($this->options['format_output']) && $this->options['format_output'] === false) {
            $this->document->formatOutput = false;
        }

        // Do a find if the second param was set.
        if (strlen($string) > 0) {
            // We don't issue a find because that creates a new DOMQuery.
            //$this->find($string);

            $query = new DOMTraverser($this->matches);

It seems like $this->matches can also be of type array; however, parameter $splos of QueryPath\CSS\DOMTraverser::__construct() does only seem to accept SPLObjectStorage, maybe add an additional type check?

            $query->find($string);
            $this->setMatches($query->matches());
        }
    }

    private function parseXMLString($string, $flags = NULL)
    {
        $document = new \DOMDocument('1.0');
        $lead = strtolower(substr($string, 0, 5)); // <?xml
        try {
            set_error_handler([ParseException::class, 'initializeFromError'], $this->errTypes);

            if (isset($this->options['convert_to_encoding'])) {
                // Is there another way to do this?

                $from_enc = $this->options['convert_from_encoding'] ?? 'auto';
                $to_enc = $this->options['convert_to_encoding'];

                if (function_exists('mb_convert_encoding')) {
                    $string = mb_convert_encoding($string, $to_enc, $from_enc);
                }

            }

            // This is to avoid cases where low ascii digits have slipped into HTML.
            // AFAIK, it should not adversly effect UTF-8 documents.
            if (!empty($this->options['strip_low_ascii'])) {
                $string = filter_var($string, FILTER_UNSAFE_RAW, FILTER_FLAG_ENCODE_LOW);
            }

            // Allow users to override parser settings.
            $useParser = '';
            if (!empty($this->options['use_parser'])) {
                $useParser = strtolower($this->options['use_parser']);
            }

            // If HTML parser is requested, we use it.
            if ($useParser === 'html') {
                $document->loadHTML($string);
            } // Parse as XML if it looks like XML, or if XML parser is requested.
            elseif ($lead === '<?xml' || $useParser === 'xml') {
                if ($this->options['replace_entities']) {
                    $string = Entities::replaceAllEntities($string);
                }
                $document->loadXML($string, $flags);
            } // In all other cases, we try the HTML parser.
            else {
                $document->loadHTML($string);
            }
        } // Emulate 'finally' behavior.
        catch (Exception $e) {
            restore_error_handler();
            throw $e;
        }
        restore_error_handler();

        if (empty($document)) {
            throw new \QueryPath\ParseException('Unknown parser exception.');
        }

        return $document;
    }

    /**
     * EXPERT: Be very, very careful using this.
     * A utility function for setting the current set of matches.
     * It makes sure the last matches buffer is set (for end() and andSelf()).
     *
     * @since 2.0
     * @param $matches
     */
    public function setMatches($matches)
    {
        // This causes a lot of overhead....
        //if ($unique) $matches = self::unique($matches);
        $this->last = $this->matches;

The property last does not exist. Although not strictly required by PHP, it is generally a best practice to declare properties explicitly.

        // Just set current matches.
        if ($matches instanceof \SplObjectStorage) {
            $this->matches = $matches;
        } // This is likely legacy code that needs conversion.
        elseif (is_array($matches)) {
            trigger_error('Legacy array detected.');
            $tmp = new \SplObjectStorage();
            foreach ($matches as $m) {
                $tmp->attach($m);
            }
            $this->matches = $tmp;
        }
        // For non-arrays, try to create a new match set and
        // add this object.
        else {
            $found = new \SplObjectStorage();
            if (isset($matches)) {
                $found->attach($matches);
            }
            $this->matches = $found;
        }

        // EXPERIMENTAL: Support for qp()->length.
        $this->length = $this->matches->count();

The property length does not exist. Although not strictly required by PHP, it is generally a best practice to declare properties explicitly.

    }

    /**
     * A depth-checking function. Typically, it only needs to be
     * invoked with the first parameter. The rest are used for recursion.
     *
     * @see deepest();
     * @param DOMNode $ele
     *  The element.
     * @param int $depth
     *  The depth guage
     * @param mixed $current
     *  The current set.
     * @param DOMNode $deepest
     *  A reference to the current deepest node.
     * @return array
     *  Returns an array of DOM nodes.
     */
    protected function deepestNode(\DOMNode $ele, $depth = 0, $current = NULL, &$deepest = NULL)
    {
        // FIXME: Should this use SplObjectStorage?
        if (!isset($current)) {
            $current = [$ele];
        }
        if (!isset($deepest)) {
            $deepest = $depth;
        }
        if ($ele->hasChildNodes()) {
            foreach ($ele->childNodes as $child) {
                if ($child->nodeType === XML_ELEMENT_NODE) {
                    $current = $this->deepestNode($child, $depth + 1, $current, $deepest);

It seems like $deepest can also be of type integer; however, parameter $deepest of QueryPath\DOM::deepestNode() does only seem to accept DOMNode, maybe add an additional type check?

                }
            }
        } elseif ($depth > $deepest) {
            $current = [$ele];
            $deepest = $depth;
        } elseif ($depth === $deepest) {
            $current[] = $ele;
        }

        return $current;
    }

    /**
     * Prepare an item for insertion into a DOM.
     *
     * This handles a variety of boilerplate tasks that need doing before an
     * indeterminate object can be inserted into a DOM tree.
     * - If item is a string, this is converted into a document fragment and returned.
     * - If item is a DOMQuery, then all items are retrieved and converted into
     *   a document fragment and returned.
     * - If the item is a DOMNode, it is imported into the current DOM if necessary.
     * - If the item is a SimpleXMLElement, it is converted into a DOM node and then
     *   imported.
     *
     * @param mixed $item
     *  Item to prepare for insert.
     * @return mixed
     *  Returns the prepared item.
     * @throws QueryPath::Exception
     *  Thrown if the object passed in is not of a supprted object type.
     * @throws Exception
     */
    protected function prepareInsert($item)
    {
        if (empty($item)) {
            return NULL;
        }

        if (is_string($item)) {
            // If configured to do so, replace all entities.
            if ($this->options['replace_entities']) {
                $item = Entities::replaceAllEntities($item);
            }

            $frag = $this->document->createDocumentFragment();
            try {
                set_error_handler([ParseException::class, 'initializeFromError'], $this->errTypes);
                $frag->appendXML($item);
            } // Simulate a finally block.
            catch (Exception $e) {
                restore_error_handler();
                throw $e;
            }
            restore_error_handler();

            return $frag;
        }

        if ($item instanceof self) {
            if ($item->count() === 0) {
                return NULL;
            }

            $frag = $this->document->createDocumentFragment();
            foreach ($item->matches as $m) {
                $frag->appendXML($item->document->saveXML($m));
            }

            return $frag;
        }

        if ($item instanceof \DOMNode) {
            if ($item->ownerDocument !== $this->document) {
                // Deep clone this and attach it to this document
                $item = $this->document->importNode($item, true);
            }

            return $item;
        }

        if ($item instanceof \SimpleXMLElement) {
            $element = dom_import_simplexml($item);

            return $this->document->importNode($element, true);
        }
        // What should we do here?
        //var_dump($item);
        throw new \QueryPath\Exception('Cannot prepare item of unsupported type: ' . gettype($item));
    }

    /**
     * Convenience function for getNthMatch(0).
     */
    protected function getFirstMatch()
    {
        $this->matches->rewind();

The method rewind() does not exist on Traversable. It seems like you code against a sub-type of Traversable such as Yaf_Config_Simple or Yaf\Session or SimpleXMLElement or Yaf_Session or Yaf\Config\Simple or Yaf\Config\Ini or Iterator or Yaf_Config_Ini or MongoGridFSCursor or Mockery\Generator\TestTraversableInterface2 or SplFixedArray or QueryPath\DOMQuery.

        return $this->matches->current();

The method current() does not exist on Traversable. It seems like you code against a sub-type of Traversable such as IntlCodePointBreakIterator or Yaf_Config_Simple or Yaf\Session or SimpleXMLElement or IntlRuleBasedBreakIterator or Yaf_Session or Yaf\Config\Simple or Yaf\Config\Ini or Iterator or Yaf_Config_Ini or MongoGridFSCursor or Mockery\Generator\TestTraversableInterface2 or SplFixedArray or IntlBreakIterator or QueryPath\DOMQuery.

    }

    /**
     * Parse an XML or HTML file.
     *
     * This attempts to autodetect the type of file, and then parse it.
     *
     * @param string $filename
     *  The file name to parse.
     * @param int $flags
     *  The OR-combined flags accepted by the DOM parser. See the PHP documentation
     *  for DOM or for libxml.
     * @param resource $context
     *  The stream context for the file IO. If this is set, then an alternate
     *  parsing path is followed: The file is loaded by PHP's stream-aware IO
     *  facilities, read entirely into memory, and then handed off to
     *  {@link parseXMLString()}. On large files, this can have a performance impact.
     * @throws \QueryPath\ParseException
     *  Thrown when a file cannot be loaded or parsed.
     */
    private function parseXMLFile($filename, $flags = NULL, $context = NULL)
    {

        // If a context is specified, we basically have to do the reading in
        // two steps:
        if (!empty($context)) {
            try {
                set_error_handler(['\QueryPath\ParseException', 'initializeFromError'], $this->errTypes);
                $contents = file_get_contents($filename, false, $context);
            }
                // Apparently there is no 'finally' in PHP, so we have to restore the error
                // handler this way:
            catch (Exception $e) {
                restore_error_handler();
                throw $e;
            }
            restore_error_handler();

            if ($contents == false) {

It seems like you are loosely comparing $contents of type string to the boolean false. If you are specifically checking for an empty string, consider using the more explicit === '' instead.

                throw new \QueryPath\ParseException(sprintf('Contents of the file %s could not be retrieved.',
                    $filename));
            }

            return $this->parseXMLString($contents, $flags);
        }

        $document = new \DOMDocument();
        $lastDot = strrpos($filename, '.');

        $htmlExtensions = [
            '.html' => 1,
            '.htm'  => 1,
        ];

        // Allow users to override parser settings.
        if (empty($this->options['use_parser'])) {
            $useParser = '';
        } else {
            $useParser = strtolower($this->options['use_parser']);
        }

        $ext = $lastDot !== false ? strtolower(substr($filename, $lastDot)) : '';

        try {
            set_error_handler([ParseException::class, 'initializeFromError'], $this->errTypes);

            // If the parser is explicitly set to XML, use that parser.
            if ($useParser === 'xml') {
                $document->load($filename, $flags);
            } // Otherwise, see if it looks like HTML.
            elseif ($useParser === 'html' || isset($htmlExtensions[$ext])) {
                // Try parsing it as HTML.
                $document->loadHTMLFile($filename);
            } // Default to XML.
            else {
                $document->load($filename, $flags);
            }

        } // Emulate 'finally' behavior.
        catch (Exception $e) {
            restore_error_handler();
            throw $e;
        }
        restore_error_handler();

        return $document;
    }

    /**
     * Determine whether a given string looks like XML or not.
     *
     * Basically, this scans a portion of the supplied string, checking to see
     * if it has a tag-like structure. It is possible to "confuse" this, which
     * may subsequently result in parse errors, but in the vast majority of
     * cases, this method serves as a valid inicator of whether or not the
     * content looks like XML.
     *
     * Things that are intentional excluded:
     * - plain text with no markup.
     * - strings that look like filesystem paths.
     *
     * Subclasses SHOULD NOT OVERRIDE THIS. Altering it may be altering
     * core assumptions about how things work. Instead, classes should
     * override the constructor and pass in only one of the parsed types
     * that this class expects.
     */
    protected function isXMLish($string)
    {
        return (strpos($string, '<') !== false && strpos($string, '>') !== false);
    }

    /**
     * A utility function for retriving a match by index.
     *
     * The internal data structure used in DOMQuery does not have
     * strong random access support, so we suppliment it with this method.
     *
     * @param $index
     * @return object|void
     */
    protected function getNthMatch(int $index)
    {
        if ($index < 0 || $index > $this->matches->count()) {

The method count() does not exist on Traversable. It seems like you code against a sub-type of Traversable such as parallel\Events or Yaf_Config_Simple or Yaf\Session or Threaded or Volatile or MockeryTest_InterfaceWithTraversable or SimpleXMLElement or Thread or Yaf_Session or Ds\Collection or pq\Result or Yaf\Config\Simple or Yaf\Config\Ini or Worker or Yaf_Config_Ini or MongoGridFSCursor or DOMNodeList or PharIo\Manifest\AuthorCollection or SplFixedArray or QueryPath\CSS\Selector or QueryPath\DOM or WeakMap or DOMNamedNodeMap or PharIo\Manifest\BundledComponentCollection or SebastianBergmann\CodeCoverage\Node\Directory or ArrayObject or PHPUnit\Framework\TestSuite or PharIo\Manifest\RequirementCollection or ResourceBundle or SplDoublyLinkedList or HttpMessage or HttpRequestPool or RdKafka\Metadata\Collection or Yaf_Config_Simple or SplFixedArray or SplObjectStorage or Yaf\Session or SQLiteResult or Cassandra\UserTypeValue or Imagick or Cassandra\Collection or SimpleXMLElement or TheSeer\Tokenizer\TokenCollection or http\Message or Yaf_Session or SplPriorityQueue or Cassandra\Rows or Cassandra\Map or Yaf\Config\Simple or Yaf\Config\Ini or MongoCursor or Yaf_Config_Ini or SplHeap or Cassandra\Set or MongoGridFSCursor or Cassandra\Tuple or CachingIterator or PHP_Token_Stream or Phar or ArrayIterator or GlobIterator or Phar or Phar or RecursiveCachingIterator or SimpleXMLElement or RecursiveArrayIterator or SimpleXMLIterator or Phar.

            return;
        }

        $i = 0;
        foreach ($this->matches as $m) {
            if ($i++ === $index) {
                return $m;
            }
        }
    }
}