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/>.

/**

 * Handle simple PHP/CSV/XML datasets to be use with ease by unit tests.

 *

 * This is a very minimal class, able to load data from PHP arrays and

 * CSV/XML files, optionally uploading them to database.

 *

 * This doesn't aim to be a complex or complete solution, but just a

 * utility class to replace old phpunit/dbunit uses, because that package

 * is not longer maintained. Note that, ideally, generators should provide

 * the needed utilities to proceed with this loading of information to

 * database and, if there is any future that should be it.

 *

 * @package    core

 * @category   test

 * @copyright  2020 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

declare(strict_types=1);

/**

 * Lightweight dataset class for phpunit, supports XML, CSV and array datasets.

 *

 * This is a simple replacement class for the old old phpunit/dbunit, now

 * archived. It allows to load CSV, XML and array structures to database.

 */

class phpunit_dataset {

    /** @var array tables being handled by the dataset */

    protected $tables = [];

    /** @var array columns belonging to every table (keys) handled by the dataset */

    protected $columns = [];

    /** @var array rows belonging to every table (keys) handled by the dataset */

    protected $rows = [];

    /**

     * Load information from multiple files (XML, CSV) to the dataset.

     *

     * This method accepts an array of full paths to CSV or XML files to be loaded

     * into the dataset. For CSV files, the name of the table which the file belongs

     * to needs to be specified. Example:

     *

     *   $fullpaths = [

     *       '/path/to/users.xml',

     *       'course' => '/path/to/courses.csv',

     *   ];

     *

     * @param array $fullpaths full paths to CSV or XML files to load.

     */

    public function from_files(array $fullpaths): void {

        foreach ($fullpaths as $table => $fullpath) {

            $table = is_int($table) ? null : $table; // Only a table when it's an associative array.

            $this->from_file($fullpath, $table);

        }

    }

    /**

     * Load information from one file (XML, CSV) to the dataset.

     *

     * @param string $fullpath full path to CSV or XML file to load.

     * @param string|null $table name of the table which the file belongs to (only for CSV files).

     */

    public function from_file(string $fullpath, ?string $table = null): void {

        if (!file_exists($fullpath)) {

            throw new coding_exception('from_file, file not found: ' . $fullpath);

        }

        if (!is_readable($fullpath)) {

            throw new coding_exception('from_file, file not readable: ' . $fullpath);

        }

        $extension = strtolower(pathinfo($fullpath, PATHINFO_EXTENSION));

        if (!in_array($extension, ['csv', 'xml'])) {

            throw new coding_exception('from_file, cannot handle files with extension: ' . $extension);

        }

        $this->from_string(file_get_contents($fullpath), $extension, $table);

    }

    /**

     * Load information from a string (XML, CSV) to the dataset.

     *

     * @param string $content contents (CSV or XML) to load.

     * @param string $type format of the content to be loaded (csv or xml).

     * @param string|null $table name of the table which the file belongs to (only for CSV files).

     */

    public function from_string(string $content, string $type, ?string $table = null): void {

        switch ($type) {

            case 'xml':

                $this->load_xml($content);

                break;

            case 'csv':

                if (empty($table)) {

                    throw new coding_exception('from_string, contents of type "cvs" require a $table to be passed, none found');

                }

                $this->load_csv($content, $table);

                break;

            default:

                throw new coding_exception('from_string, cannot handle contents of type: ' . $type);

        }

    }

    /**

     * Load information from a PHP array to the dataset.

     *

     * The general structure of the PHP array must be

     *   [table name] => [array of rows, each one being an array of values or column => values.

     * The format of the array must be one of the following:

     * - non-associative array, with column names in the first row (pretty much like CSV files are):

     *     $structure = [

     *         'table 1' => [

     *             ['column name 1', 'column name 2'],

     *             ['row 1 column 1 value', 'row 1 column 2 value'*,

     *             ['row 2 column 1 value', 'row 2 column 2 value'*,

     *         ],

     *         'table 2' => ...

     *     ];

     * - associative array, with column names being keys in the array.

     *     $structure = [

     *         'table 1' => [

     *             ['column name 1' => 'row 1 column 1 value', 'column name 2' => 'row 1 column 2 value'],

     *             ['column name 1' => 'row 2 column 1 value', 'column name 2' => 'row 2 column 2 value'],

     *         ],

     *         'table 2' => ...

     *     ];

     * @param array $structure php array with a valid structure to be loaded to the dataset.

     */

    public function from_array(array $structure): void {

        foreach ($structure as $tablename => $rows) {

            if (in_array($tablename, $this->tables)) {

                throw new coding_exception('from_array, table already added to dataset: ' . $tablename);

            }

            $this->tables[] = $tablename;

            $this->columns[$tablename] = [];

            $this->rows[$tablename] = [];

            $isassociative = false;

            $firstrow = reset($rows);

            if (array_key_exists(0, $firstrow)) {

                // Columns are the first row (csv-like).

                $this->columns[$tablename] = $firstrow;

                array_shift($rows);

            } else {

                // Columns are the keys on every record, first one must have all.

                $this->columns[$tablename] = array_keys($firstrow);

                $isassociative = true;

            }

            $countcols = count($this->columns[$tablename]);

            foreach ($rows as $row) {

                $countvalues = count($row);

                if ($countcols != $countvalues) {

                    throw new coding_exception('from_array, number of columns must match number of values, found: ' .

                        $countcols . ' vs ' . $countvalues);

                }

                if ($isassociative && $this->columns[$tablename] != array_keys($row)) {

                    throw new coding_exception('from_array, columns in all elements must match first one, found: ' .

                        implode(', ', array_keys($row)));

                }

                $this->rows[$tablename][] = array_combine($this->columns[$tablename], array_values($row));

            }

        }

    }

    /**

     * Send all the information to the dataset to the database.

     *

     * This method gets all the information loaded in the dataset, using the from_xxx() methods

     * and sends it to the database; table and column names must match.

     *

     * Note that, if the information to be sent to database contains sequence columns (usually 'id')

     * then those values will be preserved (performing an import and adjusting sequences later). Else

     * normal inserts will happen and sequence (auto-increment) columns will be fed automatically.

     *

     * @param string[] $filter Tables to be sent to database. If not specified, all tables are processed.

     */

    public function to_database(array $filter = []): void {

        global $DB;

        // Verify all filter elements are correct.

        foreach ($filter as $table) {

            if (!in_array($table, $this->tables)) {

                throw new coding_exception('dataset_to_database, table is not in the dataset: ' . $table);

            }

        }

        $structure = phpunit_util::get_tablestructure();

        foreach ($this->tables as $table) {

            // Apply filter.

            if (!empty($filter) && !in_array($table, $filter)) {

                continue;

            }

            $doimport = false;

            if (isset($structure[$table]['id']) and $structure[$table]['id']->auto_increment) {

                $doimport = in_array('id', $this->columns[$table]);

            }

            foreach ($this->rows[$table] as $row) {

                if ($doimport) {

                    $DB->import_record($table, $row);

                } else {

                    $DB->insert_record($table, $row);

                }

            }

            if ($doimport) {

                $DB->get_manager()->reset_sequence(new xmldb_table($table));

            }

        }

    }

    /**

     * Returns the rows, for a given table, that the dataset holds.

     *

     * @param string[] $filter Tables to return rows. If not specified, all tables are processed.

     * @return array tables as keys with rows on each as sub array.

     */

    public function get_rows(array $filter = []): array {

        // Verify all filter elements are correct.

        foreach ($filter as $table) {

            if (!in_array($table, $this->tables)) {

                throw new coding_exception('dataset_get_rows, table is not in the dataset: ' . $table);

            }

        }

        $result = [];

        foreach ($this->tables as $table) {

            // Apply filter.

            if (!empty($filter) && !in_array($table, $filter)) {

                continue;

            }

            $result[$table] = $this->rows[$table];

        }

        return $result;

    }

    /**

     * Given a CSV content, process and load it as a table into the dataset.

     *

     * @param string $content CSV content to be loaded (only one table).

     * @param string $tablename Name of the table the content belongs to.

     */

    protected function load_csv(string $content, string $tablename): void {

        if (in_array($tablename, $this->tables)) {

            throw new coding_exception('csv_dataset_format, table already added to dataset: ' . $tablename);

        }

        $this->tables[] = $tablename;

        $this->columns[$tablename] = [];

        $this->rows[$tablename] = [];

        // Normalise newlines.

        $content = preg_replace('#\r\n?#', '\n', $content);

        // Function str_getcsv() is not good for new lines within the data, so lets use temp file and fgetcsv() instead.

        $tempfile = tempnam(make_temp_directory('phpunit'), 'csv');

        $fh = fopen($tempfile, 'w+b');

        fwrite($fh, $content);

        // And let's read it using fgetcsv().

        rewind($fh);

        // We just accept default, delimiter = comma, enclosure = double quote.

        while ( ($row = fgetcsv($fh) ) !== false ) {

            if (empty($this->columns[$tablename])) {

                $this->columns[$tablename] = $row;

            } else {

                $this->rows[$tablename][] = array_combine($this->columns[$tablename], $row);

            }

        }

        fclose($fh);

        unlink($tempfile);

    }

    /**

     * Given a XML content, process and load it as tables into the dataset.

     *

     * @param string $content XML content to be loaded (can be multi-table).

     */

    protected function load_xml(string $content): void {

        $xml = new SimpleXMLElement($content);

        // Main element must be dataset.

        if ($xml->getName() !== 'dataset') {

            throw new coding_exception('xml_dataset_format, main xml element must be "dataset", found: ' . $xml->getName());

        }

        foreach ($xml->children() as $table) {

            // Only table elements allowed.

            if ($table->getName() !== 'table') {

                throw new coding_exception('xml_dataset_format, only "table" elements allowed, found: ' . $table->getName());

            }

            // Only allowed attribute of table is "name".

            if (!isset($table['name'])) {

                throw new coding_exception('xml_dataset_format, "table" element only allows "name" attribute.');

            }

            $tablename = (string)$table['name'];

            if (in_array($tablename, $this->tables)) {

                throw new coding_exception('xml_dataset_format, table already added to dataset: ' . $tablename);

            }

            $this->tables[] = $tablename;

            $this->columns[$tablename] = [];

            $this->rows[$tablename] = [];

            $countcols = 0;

            foreach ($table->children() as $colrow) {

                // Only column and row allowed.

                if ($colrow->getName() !== 'column' && $colrow->getName() !== 'row') {

                    throw new coding_exception('xml_dataset_format, only "column or "row" elements allowed, found: ' .

                        $colrow->getName());

                }

                // Column always before row.

                if ($colrow->getName() == 'column' && !empty($this->rows[$tablename])) {

                    throw new coding_exception('xml_dataset_format, "column" elements always must be before "row" ones');

                }

                // Row always after column.

                if ($colrow->getName() == 'row' && empty($this->columns[$tablename])) {

                    throw new coding_exception('xml_dataset_format, "row" elements always must be after "column" ones');

                }

                // Process column.

                if ($colrow->getName() == 'column') {

                    $this->columns[$tablename][] = (string)$colrow;

                    $countcols++;

                }

                // Process row.

                if ($colrow->getName() == 'row') {

                    $countvalues = 0;

                    $row = [];

                    foreach ($colrow->children() as $value) {

                        // Only value allowed under row.

                        if ($value->getName() !== 'value') {

                            throw new coding_exception('xml_dataset_format, only "value" elements allowed, found: ' .

                                $value->getName());

                        }

                        $row[$this->columns[$tablename][$countvalues]] = (string)$value;

                        $countvalues++;

                    }

                    if ($countcols !== $countvalues) {

                        throw new coding_exception('xml_dataset_format, number of columns must match number of values, found: ' .

                            $countcols . ' vs ' . $countvalues);

                    }

                    $this->rows[$tablename][] = $row;

                }

            }

        }

    }

}