Proyectos de Subversion Moodle

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace tool_brickfield\local\htmlchecker\common;

use tool_brickfield\local\htmlchecker\brickfield_accessibility_report_item;
use tool_brickfield\manager;

/**
 * This handles importing DOM objects, adding items to the report and provides a few DOM-traversing methods
 *
 * @package    tool_brickfield
 * @copyright  2020 onward: Brickfield Education Labs, www.brickfield.ie
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class brickfield_accessibility_test {
    /** @var object The DOMDocument object */
    public $dom;

    /** @var object The brickfieldCSS object */
    public $css;

    /** @var array The path for the request */
    public $path;

    /** @var bool Whether the test can be used in a CMS (content without HTML head) */
    public $cms = true;

    /** @var string The base path for this request */
    public $basepath;

    /** @var array An array of ReportItem objects */
    public $report = array();

    /** @var int The fallback severity level for all tests */
    public $defaultseverity = \tool_brickfield\local\htmlchecker\brickfield_accessibility::BA_TEST_SUGGESTION;

    /** @var array An array of all the extensions that are images */
    public $imageextensions = array('gif', 'jpg', 'png', 'jpeg', 'tiff', 'svn');

    /** @var string The language domain */
    public $lang = 'en';

    /** @var array An array of translatable strings */
    public $strings = array('en' => '');

    /** @var mixed Any additional options passed by htmlchecker. */
    public $options;

    /**
     * The class constructor. We pass items by reference so we can alter the DOM if necessary
     * @param object $dom The DOMDocument object
     * @param object $css The brickfieldCSS object
     * @param array $path The path of this request
     * @param string $languagedomain The langauge domain to user
     * @param mixed $options Any additional options passed by htmlchecker.
     */
    public function __construct(&$dom, &$css, &$path, $languagedomain = 'en', $options = null) {
        $this->dom = $dom;
        $this->css = $css;
        $this->path = $path;
        $this->lang = $languagedomain;
        $this->options = $options;
        $this->report = array();
        $this->check();
    }

    /**
     * Helper method to collect the report from this test. Some
     * tests do additional cleanup by overriding this method
     * @return array An array of ReportItem objects
     */
    public function get_report(): array {
        $this->report['severity'] = $this->defaultseverity;
        return $this->report;
    }

    /**
     * Returns the default severity of the test
     * @return int The severity level
     */
    public function get_severity(): int {
        return $this->defaultseverity;
    }

    /**
     * Adds a new ReportItem to this current tests collection of reports.
     * Most reports pertain to a particular element (like an IMG with no Alt attribute);
     * however, some are document-level and just either pass or don't pass
     * @param object $element The DOMElement object that pertains to this report
     * @param string $message An additional message to add to the report
     * @param bool $pass Whether or not this report passed
     * @param object $state Extra information about the error state
     * @param bool $manual Whether the report needs a manual check
     */
    public function add_report($element = null, $message = null, $pass = null, $state = null, $manual = null) {
        $report          = new brickfield_accessibility_report_item();
        $report->element = $element;
        $report->message = $message;
        $report->pass    = $pass;
        $report->state   = $state;
        $report->manual  = $manual;
        $report->line    = $report->get_line();
        $this->report[]  = $report;
    }

    /**
     * Retrieves the full path for a file.
     * @param string $file The path to a file
     * @return string The absolute path to the file.
     */
    public function get_path($file): string {
        if ((substr($file, 0, 7) == 'http://') || (substr($file, 0, 8) == 'https://')) {
            return $file;
        }
        $file = explode('/', $file);
        if (count($file) == 1) {
            return implode('/', $this->path) . '/' . $file[0];
        }

        $path = $this->path;
        foreach ($file as $directory) {
            if ($directory == '..') {
                array_pop($path);
            } else {
                $filepath[] = $directory;
            }
        }
        return implode('/', $path) .'/'. implode('/', $filepath);
    }

    /**
     * Returns a translated variable. If the translation is unavailable, English is returned
     * Because tests only really have one string array, we can get all of this info locally
     * @return mixed The translation for the object
     */
    public function translation() {
        if (isset($this->strings[$this->lang])) {
            return $this->strings[$this->lang];
        }
        if (isset($this->strings['en'])) {
            return $this->strings['en'];
        }
        return false;
    }

    /**
     * Helper method to find all the elements that fit a particular query
     * in the document (either by tag name, or by attributes from the htmlElements object)
     * @param mixed $tags Either a single tag name in a string, or an array of tag names
     * @param string $options The kind of option to select an element by (see htmlElements)
     * @param bool $value The value of the above option
     * @return array An array of elements that fit the description
     */
    public function get_all_elements($tags = null, string $options = '', bool $value = true): array {
        if (!is_array($tags)) {
            $tags = [$tags];
        }
        if ($options !== '') {
            $temp = new html_elements();
            $tags = $temp->get_elements_by_option($options, $value);
        }
        $result = [];

        if (!is_array($tags)) {
            return [];
        }
        foreach ($tags as $tag) {
            $elements = $this->dom->getElementsByTagName($tag);
            if ($elements) {
                foreach ($elements as $element) {
                    $result[] = $element;
                }
            }
        }
        if (count($result) == 0) {
            return [];
        }
        return $result;
    }

    /**
     * Returns true if an element has a child with a given tag name
     * @param object $element A DOMElement object
     * @param string $childtag The tag name of the child to find
     * @return bool TRUE if the element does have a child with
     *              the given tag name, otherwise FALSE
     */
    public function element_has_child($element, string $childtag): bool {
        foreach ($element->childNodes as $child) {
            if (property_exists($child, 'tagName') && $child->tagName == $childtag) {
                return true;
            }
        }
        return false;
    }

    /**
     * Returns the first ancestor reached of a tag, or false if it hits
     * the document root or a given tag.
     * @param object $element A DOMElement object
     * @param string $ancestortag The name of the tag we are looking for
     * @param string $limittag Where to stop searching
     * @return bool
     */
    public function get_element_ancestor($element, string $ancestortag, string $limittag = 'body') {
        while (property_exists($element, 'parentNode')) {
            if ($element->parentNode->tagName == $ancestortag) {
                return $element->parentNode;
            }
            if ($element->parentNode->tagName == $limittag) {
                return false;
            }
            $element = $element->parentNode;
        }
        return false;
    }

    /**
     * Finds all the elements with a given tag name that has
     * an attribute
     * @param string $tag The tag name to search for
     * @param string $attribute The attribute to search on
     * @param bool $unique Whether we only want one result per attribute
     * @return array An array of DOMElements with the attribute
     *               value as the key.
     */
    public function get_elements_by_attribute(string $tag, string $attribute, bool $unique = false): array {
        $results = array();
        foreach ($this->get_all_elements($tag) as $element) {
            if ($element->hasAttribute($attribute)) {
                if ($unique) {
                    $results[$element->getAttribute($attribute)] = $element;
                } else {
                    $results[$element->getAttribute($attribute)][] = $element;
                }
            }
        }
        return $results;
    }

    /**
     * Returns the next element after the current one.
     * @param object $element A DOMElement object
     * @return mixed FALSE if there is no other element, or a DOMElement object
     */
    public function get_next_element($element) {
        $parent = $element->parentNode;
        $next = false;
        foreach ($parent->childNodes as $child) {
            if ($next) {
                return $child;
            }
            if ($child->isSameNode($element)) {
                $next = true;
            }
        }
        return false;
    }

    /**
     * To minimize notices, this compares an object's property to the valus
     * and returns true or false. False will also be returned if the object is
     * not really an object, or if the property doesn't exist at all
     * @param object $object The object too look at
     * @param string $property The name of the property
     * @param mixed $value The value to check against
     * @param bool $trim Whether the property value should be trimmed
     * @param bool $lower Whether the property value should be compared on lower case
     *
     * @return bool
     */
    public function property_is_equal($object, string $property, $value, bool $trim = false, bool $lower = false) {
        if (!is_object($object)) {
            return false;
        }
        if (!property_exists($object, $property)) {
            return false;
        }
        $propertyvalue = $object->$property;
        if ($trim) {
            $propertyvalue = trim($propertyvalue);
            $value = trim($value);
        }
        if ($lower) {
            $propertyvalue = strtolower($propertyvalue);
            $value = strtolower($value);
        }
        return ($propertyvalue == $value);
    }

    /**
     * Returns the parent of an elment that has a given tag Name, but
     * stops the search if it hits the $limiter tag
     * @param object $element The DOMElement object to search on
     * @param string $tagname The name of the tag of the parent to find
     * @param string $limiter The tag name of the element to stop searching on
     *               regardless of the results (like search for a parent "P" tag
     *               of this node but stop if you reach "body")
     * @return mixed FALSE if no parent is found, or the DOMElement object of the found parent
     */
    public function get_parent($element, string $tagname, string $limiter) {
        while ($element) {
            if ($element->tagName == $tagname) {
                return $element;
            }
            if ($element->tagName == $limiter) {
                return false;
            }
            $element = $element->parentNode;
        }
        return false;
    }

    /**
     * Returns if a GIF files is animated or not http://us.php.net/manual/en/function.imagecreatefromgif.php#88005
     * @param string $filename
     * @return int
     */
    public function image_is_animated($filename): int {
        if (!($fh = @fopen($filename, 'rb'))) {
            return false;
        }
        $count = 0;
        // An animated gif contains multiple "frames", with each frame having a
        // header made up of:
        // * a static 4-byte sequence (\x00\x21\xF9\x04)
        // * 4 variable bytes
        // * a static 2-byte sequence (\x00\x2C).

        // We read through the file til we reach the end of the file, or we've found
        // at least 2 frame headers.
        while (!feof($fh) && $count < 2) {
            $chunk = fread($fh, 1024 * 100); // Read 100kb at a time.
            $count += preg_match_all('#\x00\x21\xF9\x04.{4}\x00\x2C#s', $chunk, $matches);
        }

        fclose($fh);
        return $count > 1;
    }

    /**
     * Returns if there are any printable/readable characters within an element.
     * This finds both node values or images with alt text.
     * @param object $element The given element to look at
     * @return bool TRUE if contains readable text, FALSE if otherwise
     */
    public function element_contains_readable_text($element): bool {
        if (is_a($element, 'DOMText')) {
            if (trim($element->wholeText) != '') {
                return true;
            }
        } else {
            if (trim($element->nodeValue) != '' ||
                ($element->hasAttribute('alt') && trim($element->getAttribute('alt')) != '')) {
                    return true;
            }
            if (method_exists($element, 'hasChildNodes') && $element->hasChildNodes()) {
                foreach ($element->childNodes as $child) {
                    if ($this->element_contains_readable_text($child)) {
                        return true;
                    }
                }
            }
        }
        return false;
    }

    /**
     * Returns an array of the newwindowphrases for all enabled language packs.
     * @return array of the newwindowphrases for all enabled language packs.
     */
    public static function get_all_newwindowphrases(): array {
        // Need to process all enabled lang versions of newwindowphrases.
        return static::get_all_phrases('newwindowphrases');
    }

    /**
     * Returns an array of the invalidlinkphrases for all enabled language packs.
     * @return array of the invalidlinkphrases for all enabled language packs.
     */
    public static function get_all_invalidlinkphrases(): array {
        // Need to process all enabled lang versions of invalidlinkphrases.
        return static::get_all_phrases('invalidlinkphrases');
    }

    /**
     * Returns an array of the relevant phrases for all enabled language packs.
     * @param string $stringname the language string identifier you want get the phrases for.
     * @return array of the invalidlinkphrases for all enabled language packs.
     */
    protected static function get_all_phrases(string $stringname): array {
        $stringmgr = get_string_manager();
        $allstrings = [];

        // Somehow, an invalid string was requested. Add exception handling for this in the future.
        if (!$stringmgr->string_exists($stringname, manager::PLUGINNAME)) {
            return $allstrings;
        }

        // Need to process all enabled lang versions of invalidlinkphrases.
        $enabledlangs = $stringmgr->get_list_of_translations();
        foreach ($enabledlangs as $lang => $value) {
            $tmpstring = (string)new \lang_string($stringname, manager::PLUGINNAME, null, $lang);
            $tmplangarray = explode('|', $tmpstring);
            $allstrings = array_merge($allstrings, $tmplangarray);
        }
        // Removing duplicates if a lang is enabled, yet using default 'en' due to no relevant lang file.
        $allstrings = array_unique($allstrings);
        return $allstrings;
    }

    /**
     * Assesses whether a string contains any readable text, which is text that
     * contains any characters other than whitespace characters.
     *
     * @param string $text
     * @return bool
     */
    public static function is_text_readable(string $text): bool {
        // These characters in order are a space, tab, line feed, carriage return,
        // NUL-byte, vertical tab and non-breaking space unicode character \xc2\xa0.
        $emptycharacters = " \t\n\r\0\x0B\xc2\xa0";
        return trim($text, $emptycharacters) != '';
    }
}