2989d26660bbb2be02fd5800aae4e0c63f54e228
[moodle.git] / backup / util / xml / parser / processors / grouped_parser_processor.class.php
1 <?php
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/>.
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  */
25 require_once($CFG->dirroot.'/backup/util/xml/parser/processors/simplified_parser_processor.class.php');
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 {
43     protected $groupedpaths; // Paths we are requesting grouped
44     protected $currentdata;  // Where we'll be acummulating data
46     public function __construct(array $paths = array()) {
47         $this->groupedpaths = array();
48         $this->currentdata = null;
49         parent::__construct($paths);
50     }
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     }
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     }
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     }
117 // Protected API starts here
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;
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
134         // No grouped nor child of grouped, dispatch it
135         } else {
136             $this->dispatch_chunk($data);
137         }
138     }
140     protected function path_is_grouped($path) {
141         return in_array($path, $this->groupedpaths);
142     }
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     }
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     }
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     }
190     /**
191      * Add non-existing subarray elements
192      */
193     protected function add_missing_sub($grouped, $path, $tags) {
195         // Remember tag being processed
196         $processedtag = basename($path);
198         $info =& $this->currentdata[$grouped]['tags'];
199         $hierarchyarr = explode('/', str_replace($grouped . '/', '', $path));
201         $previouselement = '';
202         $currentpath = '';
204         foreach ($hierarchyarr as $index => $element) {
206             $currentpath = $currentpath . '/' . $element;
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             }
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             }
228             // Create element if not defined
229             if (!isset($info[$element])) {
230                 // First into last element if present
231                 $info[$element] = array();
232             }
234             // If element is the current one, add information
235             if ($element === $processedtag) {
236                 $info[$element][] = $tags;
237             }
239             $previouselement = $element;
240             $info =& $info[$element];
241         }
242     }