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-structure
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 * TODO: Finish phpdocs
25 */
26
27/**
28 * Instantiable class defining the process of backup structures
29 *
30 * This class will process the given backup structure (nested/final/attribute)
31 * based on its definition, triggering as many actions as necessary (pre/post
32 * triggers, ids annotations, deciding based on settings, xml output...). Somehow
33 * one visitor pattern to allow backup structures to work with nice decoupling
34 */
35class backup_structure_processor extends base_processor {
36
37    protected $writer; // xml_writer where the processor is going to output data
38    protected $vars;   // array of backup::VAR_XXX => helper value pairs to be used by source specifications
39
40    /**
41     * @var \core\progress\base Progress tracker (null if none)
42     */
43    protected $progress;
44
45    /**
46     * Constructor.
47     *
48     * @param xml_writer $writer XML writer to save data
49     * @param c\core\progress\base$progress Progress tracker (optional)
50     */
51    public function __construct(xml_writer $writer, \core\progress\base $progress = null) {
52        $this->writer = $writer;
53        $this->progress = $progress;
54        $this->vars = array();
55    }
56
57    public function set_var($key, $value) {
58        if (isset($this->vars[$key])) {
59            throw new backup_processor_exception('processorvariablealreadyset', $key);
60        }
61        $this->vars[$key] = $value;
62    }
63
64    public function get_var($key) {
65        if (!isset($this->vars[$key])) {
66            throw new backup_processor_exception('processorvariablenotfound', $key);
67        }
68        return $this->vars[$key];
69    }
70
71    public function pre_process_nested_element(base_nested_element $nested) {
72        // Send open tag to xml_writer
73        $attrarr = array();
74        foreach ($nested->get_attributes() as $attribute) {
75            $attrarr[$attribute->get_name()] = $attribute->get_value();
76        }
77        $this->writer->begin_tag($nested->get_name(), $attrarr);
78    }
79
80    public function process_nested_element(base_nested_element $nested) {
81        // Proceed with all the file annotations for this element
82        $fileannotations = $nested->get_file_annotations();
83        if ($fileannotations) { // If there are areas to search
84            $backupid  = $this->get_var(backup::VAR_BACKUPID);
85            foreach ($fileannotations as $component => $area) {
86                foreach ($area as $filearea => $info) {
87                    $contextid = !is_null($info->contextid) ? $info->contextid : $this->get_var(backup::VAR_CONTEXTID);
88                    $itemid    = !is_null($info->element) ? $info->element->get_value() : null;
89                    backup_structure_dbops::annotate_files($backupid, $contextid, $component, $filearea, $itemid, $this->progress);
90                }
91            }
92        }
93    }
94
95    public function post_process_nested_element(base_nested_element $nested) {
96        // Send close tag to xml_writer
97        $this->writer->end_tag($nested->get_name());
98        if ($this->progress) {
99            $this->progress->progress();
100        }
101    }
102
103    public function process_final_element(base_final_element $final) {
104        // Send full tag to xml_writer and annotations (only if has value)
105        if ($final->is_set()) {
106            $attrarr = array();
107            foreach ($final->get_attributes() as $attribute) {
108                $attrarr[$attribute->get_name()] = $attribute->get_value();
109            }
110            $this->writer->full_tag($final->get_name(), $final->get_value(), $attrarr);
111            if ($this->progress) {
112                $this->progress->progress();
113            }
114            // Annotate current value if configured to do so
115            $final->annotate($this->get_var(backup::VAR_BACKUPID));
116        }
117    }
118
119    public function process_attribute(base_attribute $attribute) {
120        // Annotate current value if configured to do so
121        $attribute->annotate($this->get_var(backup::VAR_BACKUPID));
122    }
123}
124
125/**
126 * backup_processor exception to control all the errors while working with backup_processors
127 *
128 * This exception will be thrown each time the backup_processors detects some
129 * inconsistency related with the elements to process or its configuration
130 */
131class backup_processor_exception extends base_processor_exception {
132
133    /**
134     * Constructor - instantiates one backup_processor_exception
135     *
136     * @param string $errorcode key for the corresponding error string
137     * @param object $a extra words and phrases that might be required in the error string
138     * @param string $debuginfo optional debugging information
139     */
140    public function __construct($errorcode, $a = null, $debuginfo = null) {
141        parent::__construct($errorcode, $a, $debuginfo);
142    }
143}
144