first commit

backup/util/xml/output/file_xml_output.class.php

@@ -0,0 +1,71 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-xml
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * This class implements one @xml_output able to send contents to one OS file
+ *
+ * Buffering enabled by default (can be disabled)
+ *
+ * TODO: Finish phpdocs
+ */
+class file_xml_output extends xml_output {
+
+    protected $fullpath; // Full path to OS file where contents will be stored
+    protected $fhandle;  // File handle where all write operations happen
+
+    public function __construct($fullpath, $usebuffer = true) {
+        $this->fullpath = $fullpath;
+        parent::__construct($usebuffer);
+    }
+
+// Private API starts here
+
+    protected function init() {
+        if (!file_exists(dirname($this->fullpath))) {
+            throw new xml_output_exception('directory_not_exists', dirname($this->fullpath));
+        }
+        if (file_exists($this->fullpath)) {
+            throw new xml_output_exception('file_already_exists', $this->fullpath);
+        }
+        if (!is_writable(dirname($this->fullpath))) {
+            throw new xml_output_exception('directory_not_writable', dirname($this->fullpath));
+        }
+        // Open the OS file for writing
+        if (! $this->fhandle = fopen($this->fullpath, 'w')) {
+            throw new xml_output_exception('error_opening_file');
+        }
+    }
+
+    protected function finish() {
+        if (false === fclose($this->fhandle)) {
+            throw new xml_output_exception('error_closing_file');
+        }
+    }
+
+    protected function send($content) {
+        if (false === fwrite($this->fhandle, $content)) {
+            throw new xml_output_exception('error_writing_file');
+        }
+    }
+}

backup/util/xml/output/memory_xml_output.class.php

@@ -0,0 +1,64 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-xml
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * This class implements one @xml_output able to store and return output in memory
+ *
+ * Although possible to use, has been defined as not supporting buffering for
+ * testing purposes. get_allcontents() will return the contents after ending.
+ *
+ * TODO: Finish phpdocs
+ */
+class memory_xml_output extends xml_output{
+
+    protected $allcontents; // Here we'll store all the written contents
+
+    public function __construct() {
+        $this->allcontents = '';
+        parent::__construct(false); // disable buffering
+    }
+
+    public function get_allcontents() {
+        if ($this->running !== false) {
+            throw new xml_output_exception('xml_output_not_stopped');
+        }
+        return $this->allcontents;
+    }
+
+// Private API starts here
+
+    protected function init() {
+        // Easy :-)
+    }
+
+    protected function finish() {
+        // Trivial :-)
+    }
+
+    protected function send($content) {
+        // Accumulate contents
+        $this->allcontents .= $content;
+    }
+
+}

backup/util/xml/output/tests/output_test.php

@@ -0,0 +1,313 @@
+<?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/>.
+
+/**
+ * xml_output tests (base, memory and file).
+ *
+ * @package   core_backup
+ * @category  test
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_backup;
+
+use file_xml_output;
+use memory_xml_output;
+use xml_output;
+use xml_output_exception;
+
+defined('MOODLE_INTERNAL') || die();
+
+// Include all the needed stuff
+global $CFG;
+require_once($CFG->dirroot . '/backup/util/xml/output/xml_output.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/output/memory_xml_output.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/output/file_xml_output.class.php');
+
+/**
+ * xml_output tests (base, memory and file)
+ *
+ * @package   core_backup
+ * @category  test
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class output_test extends \advanced_testcase {
+
+    /*
+     * test memory_xml_output
+     */
+    function test_memory_xml_output(): void {
+        // Instantiate xml_output
+        $xo = new memory_xml_output();
+        $this->assertTrue($xo instanceof xml_output);
+
+        // Try to write some contents before starting it
+        $xo = new memory_xml_output();
+        try {
+            $xo->write('test');
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_not_started');
+        }
+
+        // Try to set buffer size if unsupported
+        $xo = new memory_xml_output();
+        try {
+            $xo->set_buffersize(8192);
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_buffer_nosupport');
+        }
+
+        // Try to set buffer after start
+        $xo = new memory_xml_output();
+        $xo->start();
+        try {
+            $xo->set_buffersize(8192);
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_already_started');
+        }
+
+        // Try to stop output before starting it
+        $xo = new memory_xml_output();
+        try {
+            $xo->stop();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_not_started');
+        }
+
+        // Try to debug_info() before starting
+        $xo = new memory_xml_output();
+        try {
+            $xo->debug_info();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_not_stopped');
+        }
+
+        // Start output twice
+        $xo = new memory_xml_output();
+        $xo->start();
+        try {
+            $xo->start();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_already_started');
+        }
+
+        // Try to debug_info() before stoping
+        $xo = new memory_xml_output();
+        $xo->start();
+        try {
+            $xo->debug_info();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_not_stopped');
+        }
+
+        // Stop output twice
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->stop();
+        try {
+            $xo->stop();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_not_started');
+        }
+
+        // Try to re-start after stop
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->stop();
+        try {
+            $xo->start();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_already_stopped');
+        }
+
+        // Try to get contents before stopping
+        $xo = new memory_xml_output();
+        $xo->start();
+        try {
+            $xo->get_allcontents();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'xml_output_not_stopped');
+        }
+
+        // Write some contents and check them
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->write('first test');
+        $xo->stop();
+        $this->assertEquals('first test', $xo->get_allcontents());
+
+        // Write 3 times and check them
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->write('first test');
+        $xo->write(', sencond test');
+        $xo->write(', third test');
+        $xo->stop();
+        $this->assertEquals('first test, sencond test, third test', $xo->get_allcontents());
+
+        // Write some line feeds, tabs and friends
+        $string = "\n\r\tcrazy test\n\r\t";
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->write($string);
+        $xo->stop();
+        $this->assertEquals($string, $xo->get_allcontents());
+
+        // Write some UTF-8 chars
+        $string = 'áéíóú';
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->write($string);
+        $xo->stop();
+        $this->assertEquals($string, $xo->get_allcontents());
+
+        // Write some empty content
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->write('Hello ');
+        $xo->write(null);
+        $xo->write(false);
+        $xo->write('');
+        $xo->write('World');
+        $xo->write(null);
+        $xo->stop();
+        $this->assertEquals('Hello World', $xo->get_allcontents());
+
+        // Get debug info
+        $xo = new memory_xml_output();
+        $xo->start();
+        $xo->write('01234');
+        $xo->write('56789');
+        $xo->stop();
+        $this->assertEquals('0123456789', $xo->get_allcontents());
+        $debug = $xo->debug_info();
+        $this->assertTrue(is_array($debug));
+        $this->assertTrue(array_key_exists('sent', $debug));
+        $this->assertEquals($debug['sent'], 10);
+    }
+
+    /*
+     * test file_xml_output
+     */
+    function test_file_xml_output(): void {
+        global $CFG;
+
+        $this->resetAfterTest();
+
+        $file = $CFG->tempdir . '/test/test_file_xml_output.txt';
+        // Remove the test dir and any content
+        @remove_dir(dirname($file));
+        // Recreate test dir
+        if (!check_dir_exists(dirname($file), true, true)) {
+            throw new \moodle_exception('error_creating_temp_dir', 'error', dirname($file));
+        }
+
+        // Instantiate xml_output
+        $xo = new file_xml_output($file);
+        $this->assertTrue($xo instanceof xml_output);
+
+        // Try to init file in (near) impossible path
+        $file = $CFG->tempdir . '/test_azby/test_file_xml_output.txt';
+        $xo = new file_xml_output($file);
+        try {
+            $xo->start();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'directory_not_exists');
+        }
+
+        // Try to init file already existing
+        $file = $CFG->tempdir . '/test/test_file_xml_output.txt';
+        file_put_contents($file, 'createdtobedeleted'); // create file manually
+        $xo = new file_xml_output($file);
+        try {
+            $xo->start();
+            $this->assertTrue(false, 'xml_output_exception expected');
+        } catch (\Exception $e) {
+            $this->assertTrue($e instanceof xml_output_exception);
+            $this->assertEquals($e->errorcode, 'file_already_exists');
+        }
+        unlink($file); // delete file
+
+        // Send some output and check
+        $file = $CFG->tempdir . '/test/test_file_xml_output.txt';
+        $xo = new file_xml_output($file);
+        $xo->start();
+        $xo->write('first text');
+        $xo->stop();
+        $this->assertEquals('first text', file_get_contents($file));
+        unlink($file); // delete file
+
+        // With buffer of 4 bytes, send 3 contents of 3 bytes each
+        // so we force both buffering and last write on stop
+        $file = $CFG->tempdir . '/test/test_file_xml_output.txt';
+        $xo = new file_xml_output($file);
+        $xo->set_buffersize(5);
+        $xo->start();
+        $xo->write('123');
+        $xo->write('456');
+        $xo->write('789');
+        $xo->stop();
+        $this->assertEquals('123456789',  file_get_contents($file));
+        unlink($file); // delete file
+
+        // Write some line feeds, tabs and friends
+        $file = $CFG->tempdir . '/test/test_file_xml_output.txt';
+        $string = "\n\r\tcrazy test\n\r\t";
+        $xo = new file_xml_output($file);
+        $xo->start();
+        $xo->write($string);
+        $xo->stop();
+        $this->assertEquals($string, file_get_contents($file));
+        unlink($file); // delete file
+
+        // Write some UTF-8 chars
+        $file = $CFG->tempdir . '/test/test_file_xml_output.txt';
+        $string = 'áéíóú';
+        $xo = new file_xml_output($file);
+        $xo->start();
+        $xo->write($string);
+        $xo->stop();
+        $this->assertEquals($string, file_get_contents($file));
+        unlink($file); // delete file
+
+        // Remove the test dir and any content
+        @remove_dir(dirname($file));
+    }
+}

backup/util/xml/output/xml_output.class.php

@@ -0,0 +1,164 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-xml
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * This abstract class outputs XML contents provided by @xml_writer
+ *
+ * Contains the common functionalities for all the xml_output_xxx classes
+ * and the interface for them. Mainly it's in charge of:
+ *   - Initialize the corresponding stream/handler (file, DB connection...)
+ *   - Finalize the stream/handler
+ *   - Provide one common buffer for all output implementations
+ *   - Receive XML contents from the @xml_writer and output them
+ *   - Some basic throughtput stats
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class xml_output {
+
+    const DEFAULT_BUFFER_SIZE = 4096; // Use a default buffer size of 4K
+
+    protected $inittime;  // Initial microtime
+    protected $sentbytes; // Bytes sent to output
+
+    protected $usebuffer; // Boolean to specify if output supports buffer (true) or no (false)
+    protected $buffersize;// Size, in bytes, of the buffer.
+    protected $currentbuffer;    // Buffer contents
+    protected $currentbuffersize;// Current buffer size
+
+    protected $running; // To know if output is running
+
+    /** @var string|float finish microtime. */
+    protected $finishtime;
+
+    public function __construct($usebuffer = true) {
+        $this->inittime   = microtime(true);
+        $this->finishtime = $this->inittime;
+        $this->sentbytes  = 0;
+
+        $this->usebuffer         = $usebuffer;
+        $this->buffersize        = $this->usebuffer ? self::DEFAULT_BUFFER_SIZE : 0;
+
+        $this->running = null;
+    }
+
+    public function set_buffersize($buffersize) {
+        if ($this->running) {
+            throw new xml_output_exception('xml_output_already_started');
+        }
+        if (!$this->usebuffer) {
+            throw new xml_output_exception('xml_output_buffer_nosupport');
+        }
+        // TODO: check it is integer > 0
+        $this->buffersize = $buffersize;
+    }
+
+    public function start() {
+        if ($this->running === true) {
+            throw new xml_output_exception('xml_output_already_started');
+        }
+        if ($this->running === false) {
+            throw new xml_output_exception('xml_output_already_stopped');
+        }
+        $this->inittime  = microtime(true);
+        $this->sentbytes = 0;
+        $this->running = true;
+        $this->currentbuffer     = '';
+        $this->currentbuffersize = 0;
+        $this->init();
+    }
+
+    public function stop() {
+        if (!$this->running) {
+            throw new xml_output_exception('xml_output_not_started');
+        }
+        $this->finishtime = microtime(true);
+        if ($this->usebuffer && $this->currentbuffersize > 0) { // Have pending contents in buffer
+            $this->send($this->currentbuffer); // Send them
+            $this->currentbuffer = '';
+            $this->currentbuffersize = 0;
+        }
+        $this->running = false;
+        $this->finish();
+    }
+
+    /**
+     * Get contents from @xml_writer and buffer/output them
+     */
+    public function write($content) {
+        if (!$this->running) {
+            throw new xml_output_exception('xml_output_not_started');
+        }
+        $lenc = strlen($content ?? ''); // Get length in bytes.
+        if ($lenc == 0) { // 0 length contents, nothing to do
+            return;
+        }
+        // Buffer handling if available
+        $tooutput = true; // By default, perform output
+        if ($this->usebuffer) { // Buffer
+            $this->currentbuffer .= $content;
+            $this->currentbuffersize += $lenc;
+            if ($this->currentbuffersize < $this->buffersize) {
+                $tooutput = false; // Still within the buffer, don't output
+            } else {
+                $content = $this->currentbuffer; // Prepare for output
+                $lenc = $this->currentbuffersize;
+                $this->currentbuffer = '';
+                $this->currentbuffersize = 0;
+            }
+        }
+        // Output
+        if ($tooutput) {
+            $this->send($content); // Efectively send the contents
+            $this->sentbytes += $lenc;
+        }
+    }
+
+    public function debug_info() {
+        if ($this->running !== false) {
+            throw new xml_output_exception('xml_output_not_stopped');
+        }
+        return array('memory' => memory_get_peak_usage(true),
+                     'time'   => $this->finishtime - $this->inittime,
+                     'sent'   => $this->sentbytes);
+    }
+
+// Implementable API starts here
+
+    abstract protected function init();
+
+    abstract protected function finish();
+
+    abstract protected function send($content);
+}
+
+/*
+ * Exception class used by all the @xml_output stuff
+ */
+class xml_output_exception extends moodle_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, 'error', '', $a, null, $debuginfo);
+    }
+}