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;

use DOMDocument;

use tool_brickfield\local\htmlchecker\common\brickfield_accessibility_css;

/**

 * Brickfield accessibility HTML checker library.

 *

 * The main interface class for brickfield_accessibility.

 *

 * @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 {

    /** @var int Failure level severe. */

    const BA_TEST_SEVERE = 1;

    /** @var int Failure level moderate. */

    const BA_TEST_MODERATE = 2;

    /** @var int Failure level seggestion. */

    const BA_TEST_SUGGESTION = 3;

    /** @var string Tag identifier to enclose all error HTML fragments in. */

    const BA_ERROR_TAG = 'bferror';

    /** @var object The central DOMDocument object */

    public $dom;

    /** @var string The type of request this is (either 'string', 'file', or 'uri' */

    public $type;

    /** @var string The value of the request. Either HTML, a URI, or the path to a file */

    public $value;

    /** @var string The base URI of the current request (used to rebuild page if necessary) */

    public $uri = '';

    /** @var string The translation domain of the current library */

    public $domain;

    /** @var string The name of the guideline */

    public $guidelinename = 'wcag';

    /** @var string The name of the reporter to use */

    public $reportername = 'static';

    /** @var object A reporting object */

    public $reporter;

    /** @var object The central guideline object */

    public $guideline;

    /** @var string The base URL for any request of type URI */

    public $baseurl;

    /** @var array An array of the current file or URI path */

    public $path = [];

    /** @var array An array of additional CSS files to load (useful for CMS content) */

    public $cssfiles = [];

    /** @var object The brickfieldCSS object */

    public $css;

    /** @var array An array of additional options */

    public $options = [

            'cms_mode'      => false,

            'start_element' => 0,

            'end_element'   => 0,

            'cms_template'  => []

        ];

    /** @var bool An indicator if the DOMDocument loaded. If not, this means that the

     * HTML given to it was so munged it wouldn't even load.

     */

    public $isvalid = true;

    /**

     * The class constructor

     * @param string $value Either the HTML string to check or the file/uri of the request

     * @param string $guideline The name of the guideline

     * @param string $type The type of the request (either file, uri, or string)

     * @param string $reporter The name of the reporter to use

     * @param string $domain The domain of the translation language to use

     */

    public function __construct(string $value = '', string $guideline = 'wcag2aaa', string $type = 'string',

                                string $reporter = 'static', string $domain = 'en') {

        $this->dom = new DOMDocument();

        $this->type = $type;

        if ($type == 'uri' || $type == 'file') {

            $this->uri = $value;

        }

        $this->domain = $domain;

        $this->guidelinename = $guideline;

        $this->reportername = $reporter;

        $this->value = $value;

    }

    /**

     * Prepares the DOMDocument object for brickfield_accessibility. It loads based on the file type

     * declaration and first scrubs the value using prepareValue().

     */

    public function prepare_dom() {

        $this->prepare_value();

        $this->isvalid = @$this->dom->loadHTML('<?xml encoding="utf-8" ?>' . $this->value);

        $this->prepare_base_url($this->value, $this->type);

    }

    /**

     * If the CMS mode options are set, then we remove some items front the

     * HTML value before sending it back.

     */

    public function prepare_value() {

        // We ignore the 'string' type because it would mean the value already contains HTML.

        if ($this->type == 'file' || $this->type == 'uri') {

            $this->value = @file_get_contents($this->value);

        }

        // If there are no surrounding tags, add self::BA_ERROR_TAG to prevent the DOM from adding a <p> tag.

        if (strpos(trim($this->value), '<') !== 0) {

            $this->value = '<' . self::BA_ERROR_TAG . '>' . $this->value . '</' . self::BA_ERROR_TAG . '>';

        }

    }

    /**

     * Set global predefined options for brickfield_accessibility. First we check that the

     * array key has been defined.

     * @param mixed $variable Either an array of values, or a variable name of the option

     * @param mixed $value If this is a single option, the value of the option

     */

    public function set_option($variable, $value = null) {

        if (!is_array($variable)) {

            $variable = [$variable => $value];

        }

        foreach ($variable as $k => $value) {

            if (isset($this->options[$k])) {

                $this->options[$k] = $value;

            }

        }

    }

    /**

     * Returns an absolute path from a relative one.

     * @param string $absolute The absolute URL

     * @param string $relative The relative path

     * @return string A new path

     */

    public function get_absolute_path(string $absolute, string $relative): string {

        if (substr($relative, 0, 2) == '//') {

            if ($this->uri) {

                $current = parse_url($this->uri);

            } else {

                $current = ['scheme' => 'http'];

            }

            return $current['scheme'] .':'. $relative;

        }

        $relativeurl = parse_url($relative);

        if (isset($relativeurl['scheme'])) {

            return $relative;

        }

        $absoluteurl = parse_url($absolute);

        if (isset($absoluteurl['path'])) {

            $path = dirname($absoluteurl['path']);

        }

        if ($relative[0] == '/') {

            $cparts = array_filter(explode('/', $relative));

        } else {

            $aparts = array_filter(explode('/', $path));

            $rparts = array_filter(explode('/', $relative));

            $cparts = array_merge($aparts, $rparts);

            foreach ($cparts as $i => $part) {

                if ($part == '.') {

                    $cparts[$i] = null;

                }

                if ($part == '..') {

                    $cparts[$i - 1] = null;

                    $cparts[$i] = null;

                }

            }

            $cparts = array_filter($cparts);

        }

        $path = implode('/', $cparts);

        $url  = "";

        if (isset($absoluteurl['scheme'])) {

            $url = $absoluteurl['scheme'] .'://';

        }

        if (isset($absoluteurl['user'])) {

            $url .= $absoluteurl['user'];

            if ($absoluteurl['pass']) {

                $url .= ':'. $absoluteurl['user'];

            }

            $url .= '@';

        }

        if (isset($absoluteurl['host'])) {

            $url .= $absoluteurl['host'];

            if (isset($absoluteurl['port'])) {

                $url .= ':'. $absoluteurl['port'];

            }

            $url .= '/';

        }

        $url .= $path;

        return $url;

    }

    /**

     * Sets the URI if this is for a string or to change where

     * Will look for resources like CSS files

     * @param string $uri The URI to set

     */

    public function set_uri(string $uri) {

        if (parse_url($uri)) {

            $this->uri = $uri;

        }

    }

    /**

     * Formats the base URL for either a file or uri request. We are essentially

     * formatting a base url for future reporters to use to find CSS files or

     * for tests that use external resources (images, objects, etc) to run tests on them.

     * @param string $value The path value

     * @param string $type The type of request

     */

    public function prepare_base_url(string $value, string $type) {

        if ($type == 'file') {

            $path = explode('/', $this->uri);

            array_pop($path);

            $this->path = $path;

        } else if ($type == 'uri' || $this->uri) {

            $parts = explode('://', $this->uri);

            $this->path[] = $parts[0] .':/';

            if (is_array($parts[1])) {

                foreach (explode('/', $this->get_base_from_file($parts[1])) as $part) {

                    $this->path[] = $part;

                }

            } else {

                $this->path[] = $parts[1] .'/';

            }

        }

    }

    /**

     * Retrieves the absolute path to a file

     * @param string $file The path to a file

     * @return string The absolute path to a file

     */

    public function get_base_from_file(string $file): string {

         $find = '/';

         $afterfind = substr(strrchr($file, $find), 1);

         $strlenstr = strlen($afterfind);

         $result = substr($file, 0, -$strlenstr);

         return $result;

    }

    /**

     * Helper method to add an additional CSS file

     * @param string $css The URI or file path to a CSS file

     */

    public function add_css(string $css) {

        if (is_array($css)) {

            $this->cssfiles = $css;

        } else {

            $this->cssfiles[] = $css;

        }

    }

    /**

     * Retrives a single error from the current reporter

     * @param string $error The error key

     * @return object A ReportItem object

     */

    public function get_error(string $error) {

        return $this->reporter->get_error($error);

    }

    /**

     * A local method to load the required file for a reporter and set it for the current object

     * @param array $options An array of options for the reporter

     */

    public function load_reporter(array $options = []) {

        $classname = '\\tool_brickfield\\local\\htmlchecker\\reporters\\'.'report_'.$this->reportername;

        $this->reporter = new $classname($this->dom, $this->css, $this->guideline, $this->path);

        if (count($options)) {

            $this->reporter->set_options($options);

        }

    }

    /**

     * Checks that the DOM object is valid or not

     * @return bool Whether the DOMDocument is valid

     */

    public function is_valid(): bool {

        return $this->isvalid;

    }

    /**

     * Starts running automated checks. Loads the CSS file parser

     * and the guideline object.

     * @param null $options

     * @return bool

     */

    public function run_check($options = null) {

        $this->prepare_dom();

        if (!$this->is_valid()) {

            return false;

        }

        $this->get_css_object();

        $classname = 'tool_brickfield\\local\\htmlchecker\\guidelines\\'.strtolower($this->guidelinename).'_guideline';

        $this->guideline = new $classname($this->dom, $this->css, $this->path, $options, $this->domain, $this->options['cms_mode']);

    }

    /**

     * Loads the brickfield_accessibility_css object

     */

    public function get_css_object() {

        $this->css = new brickfield_accessibility_css($this->dom, $this->uri, $this->type, $this->path, false, $this->cssfiles);

    }

    /**

     * Returns a formatted report from the current reporter.

     * @param array $options An array of all the options

     * @return mixed See the documentation on your reporter's getReport method.

     */

    public function get_report(array $options = []) {

        if (!$this->reporter) {

            $this->load_reporter($options);

        }

        if ($options) {

            $this->reporter->set_options($options);

        }

        $report = $this->reporter->get_report();

        $path = $this->path;

        return ['report' => $report, 'path' => $path];

    }

    /**

     * Runs one test on the current DOMDocument

     * @param string $test The name of the test to run

     * @return bool|array The ReportItem returned from the test

     */

    public function get_test(string $test) {

        $test = 'tool_brickfield\local\htmlchecker\common\checks\\' . $test;

        if (!class_exists($test)) {

            return false;

        }

        $testclass = new $test($this->dom, $this->css, $this->path);

        return $testclass->report;

    }

    /**

     * Retrieves the default severity of a test

     * @param string $test The name of the test to run

     * @return object The severity level of the test

     */

    public function get_test_severity(string $test) {

        $testclass = new $test($this->dom, $this->css, $this->path);

        return $testclass->get_severity();

    }

    /**

     * A general cleanup function which just does some memory

     * cleanup by unsetting the particularly large local vars.

     */

    public function cleanup() {

        unset($this->dom);

        unset($this->css);

        unset($this->guideline);

        unset($this->reporter);

    }

    /**

     * Determines if the link text is the same as the link URL, without necessarily being an exact match.

     * For example, 'www.google.com' matches 'https://www.google.com'.

     * @param string $text

     * @param string $href

     * @return bool

     */

    public static function match_urls(string $text, string $href): bool {

        $parsetext = parse_url($text);

        $parsehref = parse_url($href);

        $parsetextfull = (isset($parsetext['host'])) ? $parsetext['host'] : '';

        $parsetextfull .= (isset($parsetext['path'])) ? $parsetext['path'] : '';

        $parsehreffull = (isset($parsehref['host'])) ? $parsehref['host'] : '';

        $parsehreffull .= (isset($parsehref['path'])) ? $parsehref['path'] : '';

        // Remove any last '/' character before comparing.

        return (rtrim($parsetextfull, '/') === rtrim($parsehreffull, '/'));

    }

}