backup/util/xml/parser/processors/grouped_parser_processor.class.php

   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 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 require_once($CFG->dirroot.'/backup/util/xml/parser/processors/simplified_parser_processor.class.php');
  26
  27 /**
  28  * Abstract xml parser processor able to group chunks as configured
  29  * and dispatch them to other arbitrary methods
  30  *
  31  * This @progressive_parser_processor handles the requested paths,
  32  * allowing to group information under any of them, dispatching them
  33  * to the methods specified
  34  *
  35  * Note memory increases as you group more and more paths, so use it for
  36  * well-known structures being smaller enough (never to group MBs into one
  37  * in-memory structure)
  38  *
  39  * TODO: Complete phpdocs
  40  */
  41 abstract class grouped_parser_processor extends simplified_parser_processor {
  42
  43     protected $groupedpaths; // Paths we are requesting grouped
  44     protected $currentdata;  // Where we'll be acummulating data
  45
  46     public function __construct(array $paths = array()) {
  47         $this->groupedpaths = array();
  48         $this->currentdata = null;
  49         parent::__construct($paths);
  50     }
  51
  52     public function add_path($path, $grouped = false) {
  53         if ($grouped) {
  54             // Check there is no parent in the branch being grouped
  55             if ($found = $this->grouped_parent_exists($path)) {
  56                 $a = new stdclass();
  57                 $a->path = $path;
  58                 $a->parent = $found;
  59                 throw new progressive_parser_exception('xml_grouped_parent_found', $a);
  60             }
  61             // Check there is no child in the branch being grouped
  62             if ($found = $this->grouped_child_exists($path)) {
  63                 $a = new stdclass();
  64                 $a->path = $path;
  65                 $a->child = $found;
  66                 throw new progressive_parser_exception('xml_grouped_child_found', $a);
  67             }
  68             $this->groupedpaths[] = $path;
  69         }
  70         parent::add_path($path);
  71     }
  72
  73     /**
  74      * The parser fires this each time one path is going to be parsed
  75      *
  76      * @param string $path xml path which parsing has started
  77      */
  78     public function before_path($path) {
  79         if ($this->path_is_grouped($path) and !isset($this->currentdata[$path])) {
  80             // If the grouped element itself does not contain any final tags,
  81             // we would not get any chunk data for it. So we add an artificial
  82             // empty data chunk here that will be eventually replaced with
  83             // real data later in {@link self::postprocess_chunk()}.
  84             $this->currentdata[$path] = array(
  85                 'path' => $path,
  86                 'level' => substr_count($path, '/') + 1,
  87                 'tags' => array(),
  88             );
  89         }
  90         if (!$this->grouped_parent_exists($path)) {
  91             parent::before_path($path);
  92         }
  93     }
  94
  95     /**
  96      * The parser fires this each time one path has been parsed
  97      *
  98      * @param string $path xml path which parsing has ended
  99      */
 100     public function after_path($path) {
 101         // Have finished one grouped path, dispatch it
 102         if ($this->path_is_grouped($path)) {
 103             // Any accumulated information must be in
 104             // currentdata, properly built
 105             $data = $this->currentdata[$path];
 106             unset($this->currentdata[$path]);
 107             // TODO: If running under DEBUG_DEVELOPER notice about >1MB grouped chunks
 108             $this->dispatch_chunk($data);
 109         }
 110         // Normal notification of path end
 111         // Only if path is selected and not child of grouped
 112         if (!$this->grouped_parent_exists($path)) {
 113             parent::after_path($path);
 114         }
 115     }
 116
 117 // Protected API starts here
 118
 119     /**
 120      * Override this method so grouping will be happening here
 121      * also deciding between accumulating/dispatching
 122      */
 123     protected function postprocess_chunk($data) {
 124         $path = $data['path'];
 125         // If the chunk is a grouped one, simply put it into currentdata
 126         if ($this->path_is_grouped($path)) {
 127             $this->currentdata[$path] = $data;
 128
 129         // If the chunk is child of grouped one, add it to currentdata
 130         } else if ($grouped = $this->grouped_parent_exists($path)) {
 131             $this->build_currentdata($grouped, $data);
 132             $this->chunks--; // not counted, as it's accumulated
 133
 134         // No grouped nor child of grouped, dispatch it
 135         } else {
 136             $this->dispatch_chunk($data);
 137         }
 138     }
 139
 140     protected function path_is_grouped($path) {
 141         return in_array($path, $this->groupedpaths);
 142     }
 143
 144     /**
 145      * Function that will look for any grouped
 146      * parent for the given path, returning it if found,
 147      * false if not
 148      */
 149     protected function grouped_parent_exists($path) {
 150         $parentpath = progressive_parser::dirname($path);
 151         while ($parentpath != '/') {
 152             if ($this->path_is_grouped($parentpath)) {
 153                 return $parentpath;
 154             }
 155             $parentpath = progressive_parser::dirname($parentpath);
 156         }
 157         return false;
 158     }
 159
 160     /**
 161      * Function that will look for any grouped
 162      * child for the given path, returning it if found,
 163      * false if not
 164      */
 165     protected function grouped_child_exists($path) {
 166         $childpath = $path . '/';
 167         foreach ($this->groupedpaths as $groupedpath) {
 168             if (strpos($groupedpath, $childpath) === 0) {
 169                 return $groupedpath;
 170             }
 171         }
 172         return false;
 173     }
 174
 175     /**
 176      * This function will accumulate the chunk into the specified
 177      * grouped element for later dispatching once it is complete
 178      */
 179     protected function build_currentdata($grouped, $data) {
 180         // Check the grouped already exists into currentdata
 181         if (!is_array($this->currentdata) or !array_key_exists($grouped, $this->currentdata)) {
 182             $a = new stdclass();
 183             $a->grouped = $grouped;
 184             $a->child = $data['path'];
 185             throw new progressive_parser_exception('xml_cannot_add_to_grouped', $a);
 186         }
 187         $this->add_missing_sub($grouped, $data['path'], $data['tags']);
 188     }
 189
 190     /**
 191      * Add non-existing subarray elements
 192      */
 193     protected function add_missing_sub($grouped, $path, $tags) {
 194
 195         // Remember tag being processed
 196         $processedtag = basename($path);
 197
 198         $info =& $this->currentdata[$grouped]['tags'];
 199         $hierarchyarr = explode('/', str_replace($grouped . '/', '', $path));
 200
 201         $previouselement = '';
 202         $currentpath = '';
 203
 204         foreach ($hierarchyarr as $index => $element) {
 205
 206             $currentpath = $currentpath . '/' . $element;
 207
 208             // If element is already set and it's not
 209             // the processed one (with tags) fast move the $info
 210             // pointer and continue
 211             if ($element !== $processedtag && isset($info[$element])) {
 212                 $previouselement = $element;
 213                 $info =& $info[$element];
 214                 continue;
 215             }
 216
 217             // If previous element already has occurrences
 218             // we move $info pointer there (only if last is
 219             // numeric occurrence)
 220             if (!empty($previouselement) && is_array($info) && count($info) > 0) {
 221                 end($info);
 222                 $key = key($info);
 223                 if ((int) $key === $key) {
 224                     $info =& $info[$key];
 225                 }
 226             }
 227
 228             // Create element if not defined
 229             if (!isset($info[$element])) {
 230                 // First into last element if present
 231                 $info[$element] = array();
 232             }
 233
 234             // If element is the current one, add information
 235             if ($element === $processedtag) {
 236                 $info[$element][] = $tags;
 237             }
 238
 239             $previouselement = $element;
 240             $info =& $info[$element];
 241         }
 242     }
 243 }