f2dc77fca076fbe9c63be0d96e2d4454833610f8
[moodle.git] / backup / util / structure / base_nested_element.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 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  */
27 /**
28  * Abstract class representing one nestable element (non final) piece of information
29  */
30 abstract class base_nested_element extends base_final_element {
32     /** @var array final elements of the element (maps to XML final elements of the tag) */
33     private $final_elements;
35     /** @var array children base_elements of this element (describes structure of the XML file) */
36     private $children;
38     /** @var base_optigroup optional group of this element (branches to be processed conditionally) */
39     private $optigroup;
41     /** @var array elements already used by the base_element, to avoid circular references */
42     private $used;
44     /**
45      * Constructor - instantiates one base_nested_element, specifying its basic info.
46      *
47      * @param string $name name of the element
48      * @param array  $attributes attributes this element will handle (optional, defaults to null)
49      * @param array  $final_elements this element will handle (optional, defaults to null)
50      */
51     public function __construct($name, $attributes = null, $final_elements = null) {
52         parent::__construct($name, $attributes);
53         $this->final_elements = array();
54         if (!empty($final_elements)) {
55             $this->add_final_elements($final_elements);
56         }
57         $this->children = array();
58         $this->optigroup = null;
59         $this->used[] = $name;
60     }
62     protected function get_used() {
63         return $this->used;
64     }
66     protected function set_used($used) {
67         $this->used = $used;
68     }
70     protected function add_used($element) {
71         $this->used = array_merge($this->used, $element->get_used());
72     }
74     protected function check_and_set_used($element) {
75         $grandparent = $this->get_grandoptigroupelement_or_grandparent();
76         if ($existing = array_intersect($grandparent->get_used(), $element->get_used())) { // Check the element isn't being used already
77             throw new base_element_struct_exception('baseelementexisting', implode($existing));
78         }
79         $grandparent->add_used($element);
80         // If the parent is one optigroup, add the element useds to it too
81         if ($grandparent->get_parent() instanceof base_optigroup) {
82             $grandparent->get_parent()->add_used($element);
83         }
85     }
87 /// Public API starts here
89     public function get_final_elements() {
90         return $this->final_elements;
91     }
93     public function get_final_element($name) {
94         if (array_key_exists($name, $this->final_elements)) {
95             return $this->final_elements[$name];
96         } else {
97             return null;
98         }
99     }
101     public function get_children() {
102         return $this->children;
103     }
105     public function get_child($name) {
106         if (array_key_exists($name, $this->children)) {
107             return $this->children[$name];
108         } else {
109             return null;
110         }
111     }
113     public function get_optigroup() {
114         return $this->optigroup;
115     }
117     public function add_final_elements($final_elements) {
118         if ($final_elements instanceof base_final_element || is_string($final_elements)) { // Accept 1 final_element, object or string
119             $final_elements = array($final_elements);
120         }
121         if (is_array($final_elements)) {
122             foreach ($final_elements as $final_element) {
123                 if (is_string($final_element)) { // Accept string final_elements
124                     $final_element = $this->get_new_final_element($final_element);
125                 }
126                 if (!($final_element instanceof base_final_element)) {
127                     throw new base_element_struct_exception('baseelementnofinalelement', get_class($final_element));
128                 }
129                 if (array_key_exists($final_element->get_name(), $this->final_elements)) {
130                     throw new base_element_struct_exception('baseelementexists', $final_element->get_name());
131                 }
132                 $this->final_elements[$final_element->get_name()] = $final_element;
133                 $final_element->set_parent($this);
134             }
135         } else {
136             throw new base_element_struct_exception('baseelementincorrect');
137         }
138     }
140     public function add_child($element) {
141         if (!($element instanceof base_nested_element)) { // parameter must be a base_nested_element
142             if (!$found = get_class($element)) {
143                 $found = 'non object';
144             }
145             throw new base_element_struct_exception('nestedelementincorrect', $found);
146         }
147         $this->check_and_set_used($element);
148         $this->children[$element->get_name()] = $element;
149         $element->set_parent($this);
150     }
152     public function add_optigroup($optigroup) {
153         if (!($optigroup instanceof base_optigroup)) { // parameter must be a base_optigroup
154             if (!$found = get_class($optigroup)) {
155                 $found = 'non object';
156             }
157             throw new base_element_struct_exception('optigroupincorrect', $found);
158         }
159         if ($this->optigroup !== null) {
160             throw new base_element_struct_exception('optigroupalreadyset', $found);
161         }
162         $this->check_and_set_used($optigroup);
163         $this->optigroup = $optigroup;
164         $optigroup->set_parent($this);
165     }
167     public function get_value() {
168         throw new base_element_struct_exception('nestedelementnotvalue');
169     }
171     public function set_value($value) {
172         throw new base_element_struct_exception('nestedelementnotvalue');
173     }
175     public function clean_value() {
176         throw new base_element_struct_exception('nestedelementnotvalue');
177     }
179     public function clean_values() {
180         parent::clean_values();
181         if (!empty($this->final_elements)) {
182             foreach ($this->final_elements as $final_element) {
183                 $final_element->clean_values();
184             }
185         }
186         if (!empty($this->children)) {
187             foreach ($this->children as $child) {
188                 $child->clean_values();
189             }
190         }
191         if (!empty($this->optigroup)) {
192             $this->optigroup->clean_values();
193         }
194     }
196     public function to_string($showvalue = false) {
197         $output = parent::to_string($showvalue);
198         if (!empty($this->final_elements)) {
199             foreach ($this->final_elements as $final_element) {
200                 $output .= PHP_EOL . $final_element->to_string($showvalue);
201             }
202         }
203         if (!empty($this->children)) {
204             foreach ($this->children as $child) {
205                 $output .= PHP_EOL . $child->to_string($showvalue);
206             }
207         }
208         if (!empty($this->optigroup)) {
209             $output .= PHP_EOL . $this->optigroup->to_string($showvalue);
210         }
211         return $output;
212     }
214 // Implementable API
216     /**
217      * Returns one instace of the @final_element class to work with
218      * when final_elements are added simply by name
219      */
220     abstract protected function get_new_final_element($name);
223 /**
224  * base_element exception to control all the errors while building the nested tree
225  *
226  * This exception will be thrown each time the base_element class detects some
227  * inconsistency related with the building of the nested tree representing one base part
228  * (invalid objects, circular references, double parents...)
229  */
230 class base_element_struct_exception extends base_atom_exception {
232     /**
233      * Constructor - instantiates one base_element_struct_exception
234      *
235      * @param string $errorcode key for the corresponding error string
236      * @param object $a extra words and phrases that might be required in the error string
237      * @param string $debuginfo optional debugging information
238      */
239     public function __construct($errorcode, $a = null, $debuginfo = null) {
240         parent::__construct($errorcode, $a, $debuginfo);
241     }