Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

   1  <?php
   2  
   3  // This file is part of Moodle - http://moodle.org/
   4  //
   5  // Moodle is free software: you can redistribute it and/or modify
   6  // it under the terms of the GNU General Public License as published by
   7  // the Free Software Foundation, either version 3 of the License, or
   8  // (at your option) any later version.
   9  //
  10  // Moodle is distributed in the hope that it will be useful,
  11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  // GNU General Public License for more details.
  14  //
  15  // You should have received a copy of the GNU General Public License
  16  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17  
  18  /**
  19   * @package    moodlecore
  20   * @subpackage backup-xml
  21   * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  /**
  26   * This abstract class outputs XML contents provided by @xml_writer
  27   *
  28   * Contains the common functionalities for all the xml_output_xxx classes
  29   * and the interface for them. Mainly it's in charge of:
  30   *   - Initialize the corresponding stream/handler (file, DB connection...)
  31   *   - Finalize the stream/handler
  32   *   - Provide one common buffer for all output implementations
  33   *   - Receive XML contents from the @xml_writer and output them
  34   *   - Some basic throughtput stats
  35   *
  36   * TODO: Finish phpdocs
  37   */
  38  abstract class xml_output {
  39  
  40      const DEFAULT_BUFFER_SIZE = 4096; // Use a default buffer size of 4K
  41  
  42      protected $inittime;  // Initial microtime
  43      protected $sentbytes; // Bytes sent to output
  44  
  45      protected $usebuffer; // Boolean to specify if output supports buffer (true) or no (false)
  46      protected $buffersize;// Size, in bytes, of the buffer.
  47      protected $currentbuffer;    // Buffer contents
  48      protected $currentbuffersize;// Current buffer size
  49  
  50      protected $running; // To know if output is running
  51  
  52      public function __construct($usebuffer = true) {
  53          $this->inittime   = microtime(true);
  54          $this->finishtime = $this->inittime;
  55          $this->sentbytes  = 0;
  56  
  57          $this->usebuffer         = $usebuffer;
  58          $this->buffersize        = $this->usebuffer ? self::DEFAULT_BUFFER_SIZE : 0;
  59  
  60          $this->running = null;
  61      }
  62  
  63      public function set_buffersize($buffersize) {
  64          if ($this->running) {
  65              throw new xml_output_exception('xml_output_already_started');
  66          }
  67          if (!$this->usebuffer) {
  68              throw new xml_output_exception('xml_output_buffer_nosupport');
  69          }
  70          // TODO: check it is integer > 0
  71          $this->buffersize = $buffersize;
  72      }
  73  
  74      public function start() {
  75          if ($this->running === true) {
  76              throw new xml_output_exception('xml_output_already_started');
  77          }
  78          if ($this->running === false) {
  79              throw new xml_output_exception('xml_output_already_stopped');
  80          }
  81          $this->inittime  = microtime(true);
  82          $this->sentbytes = 0;
  83          $this->running = true;
  84          $this->currentbuffer     = '';
  85          $this->currentbuffersize = 0;
  86          $this->init();
  87      }
  88  
  89      public function stop() {
  90          if (!$this->running) {
  91              throw new xml_output_exception('xml_output_not_started');
  92          }
  93          $this->finishtime = microtime(true);
  94          if ($this->usebuffer && $this->currentbuffersize > 0) { // Have pending contents in buffer
  95              $this->send($this->currentbuffer); // Send them
  96              $this->currentbuffer = '';
  97              $this->currentbuffersize = 0;
  98          }
  99          $this->running = false;
 100          $this->finish();
 101      }
 102  
 103      /**
 104       * Get contents from @xml_writer and buffer/output them
 105       */
 106      public function write($content) {
 107          if (!$this->running) {
 108              throw new xml_output_exception('xml_output_not_started');
 109          }
 110          $lenc = strlen($content ?? ''); // Get length in bytes.
 111          if ($lenc == 0) { // 0 length contents, nothing to do
 112              return;
 113          }
 114          // Buffer handling if available
 115          $tooutput = true; // By default, perform output
 116          if ($this->usebuffer) { // Buffer
 117              $this->currentbuffer .= $content;
 118              $this->currentbuffersize += $lenc;
 119              if ($this->currentbuffersize < $this->buffersize) {
 120                  $tooutput = false; // Still within the buffer, don't output
 121              } else {
 122                  $content = $this->currentbuffer; // Prepare for output
 123                  $lenc = $this->currentbuffersize;
 124                  $this->currentbuffer = '';
 125                  $this->currentbuffersize = 0;
 126              }
 127          }
 128          // Output
 129          if ($tooutput) {
 130              $this->send($content); // Efectively send the contents
 131              $this->sentbytes += $lenc;
 132          }
 133      }
 134  
 135      public function debug_info() {
 136          if ($this->running !== false) {
 137              throw new xml_output_exception('xml_output_not_stopped');
 138          }
 139          return array('memory' => memory_get_peak_usage(true),
 140                       'time'   => $this->finishtime - $this->inittime,
 141                       'sent'   => $this->sentbytes);
 142      }
 143  
 144  // Implementable API starts here
 145  
 146      abstract protected function init();
 147  
 148      abstract protected function finish();
 149  
 150      abstract protected function send($content);
 151  }
 152  
 153  /*
 154   * Exception class used by all the @xml_output stuff
 155   */
 156  class xml_output_exception extends moodle_exception {
 157  
 158      public function __construct($errorcode, $a=NULL, $debuginfo=null) {
 159          parent::__construct($errorcode, 'error', '', $a, null, $debuginfo);
 160      }
 161  }