Merge branch 'MDL-62285-master' of git://github.com/ryanwyllie/moodle
[moodle.git] / privacy / classes / local / request / moodle_content_writer.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * This file contains the moodle format implementation of the content writer.
19  *
20  * @package core_privacy
21  * @copyright 2018 Andrew Nicols <andrew@nicols.co.uk>
22  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
24 namespace core_privacy\local\request;
26 defined('MOODLE_INTERNAL') || die();
28 /**
29  * The moodle_content_writer is the default Moodle implementation of a content writer.
30  *
31  * It exports data to a rich tree structure using Moodle's context system,
32  * and produces a single zip file with all content.
33  *
34  * Objects of data are stored as JSON.
35  *
36  * @copyright 2018 Andrew Nicols <andrew@nicols.co.uk>
37  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38  */
39 class moodle_content_writer implements content_writer {
40     /**
41      * @var string The base path on disk for this instance.
42      */
43     protected $path = null;
45     /**
46      * @var \context The current context of the writer.
47      */
48     protected $context = null;
50     /**
51      * @var \stored_file[] The list of files to be exported.
52      */
53     protected $files = [];
55     /**
56      * Constructor for the content writer.
57      *
58      * Note: The writer factory must be passed.
59      *
60      * @param   writer          $writer     The factory.
61      */
62     public function __construct(writer $writer) {
63         $this->path = make_request_directory();
64     }
66     /**
67      * Set the context for the current item being processed.
68      *
69      * @param   \context        $context    The context to use
70      */
71     public function set_context(\context $context) : content_writer {
72         $this->context = $context;
74         return $this;
75     }
77     /**
78      * Export the supplied data within the current context, at the supplied subcontext.
79      *
80      * @param   array           $subcontext The location within the current context that this data belongs.
81      * @param   \stdClass       $data       The data to be exported
82      * @return  content_writer
83      */
84     public function export_data(array $subcontext, \stdClass $data) : content_writer {
85         $path = $this->get_path($subcontext, 'data.json');
87         $this->write_data($path, json_encode($data, JSON_UNESCAPED_UNICODE));
89         return $this;
90     }
92     /**
93      * Export metadata about the supplied subcontext.
94      *
95      * Metadata consists of a key/value pair and a description of the value.
96      *
97      * @param   array           $subcontext The location within the current context that this data belongs.
98      * @param   string          $key        The metadata name.
99      * @param   string          $value      The metadata value.
100      * @param   string          $description    The description of the value.
101      * @return  content_writer
102      */
103     public function export_metadata(array $subcontext, string $key, $value, string $description) : content_writer {
104         $path = $this->get_full_path($subcontext, 'metadata.json');
106         if (file_exists($path)) {
107             $data = json_decode(file_get_contents($path));
108         } else {
109             $data = (object) [];
110         }
112         $data->$key = (object) [
113             'value' => $value,
114             'description' => $description,
115         ];
117         $path = $this->get_path($subcontext, 'metadata.json');
118         $this->write_data($path, json_encode($data, JSON_UNESCAPED_UNICODE));
120         return $this;
121     }
123     /**
124      * Export a piece of related data.
125      *
126      * @param   array           $subcontext The location within the current context that this data belongs.
127      * @param   string          $name       The name of the file to be exported.
128      * @param   \stdClass       $data       The related data to export.
129      * @return  content_writer
130      */
131     public function export_related_data(array $subcontext, $name, $data) : content_writer {
132         $path = $this->get_path($subcontext, "{$name}.json");
134         $this->write_data($path, json_encode($data, JSON_UNESCAPED_UNICODE));
136         return $this;
137     }
139     /**
140      * Export a piece of data in a custom format.
141      *
142      * @param   array           $subcontext The location within the current context that this data belongs.
143      * @param   string          $filename   The name of the file to be exported.
144      * @param   string          $filecontent    The content to be exported.
145      */
146     public function export_custom_file(array $subcontext, $filename, $filecontent) : content_writer {
147         $filename = clean_param($filename, PARAM_FILE);
148         $path = $this->get_path($subcontext, $filename);
149         $this->write_data($path, $filecontent);
151         return $this;
152     }
154     /**
155      * Prepare a text area by processing pluginfile URLs within it.
156      *
157      * @param   array           $subcontext The location within the current context that this data belongs.
158      * @param   string          $component  The name of the component that the files belong to.
159      * @param   string          $filearea   The filearea within that component.
160      * @param   string          $itemid     Which item those files belong to.
161      * @param   string          $text       The text to be processed
162      * @return  string                      The processed string
163      */
164     public function rewrite_pluginfile_urls(array $subcontext, $component, $filearea, $itemid, $text) : string {
165         return str_replace('@@PLUGINFILE@@/', $this->get_files_target_path($component, $filearea, $itemid).'/', $text);
166     }
168     /**
169      * Export all files within the specified component, filearea, itemid combination.
170      *
171      * @param   array           $subcontext The location within the current context that this data belongs.
172      * @param   string          $component  The name of the component that the files belong to.
173      * @param   string          $filearea   The filearea within that component.
174      * @param   string          $itemid     Which item those files belong to.
175      */
176     public function export_area_files(array $subcontext, $component, $filearea, $itemid) : content_writer {
177         $fs = get_file_storage();
178         $files = $fs->get_area_files($this->context->id, $component, $filearea, $itemid);
179         foreach ($files as $file) {
180             $this->export_file($subcontext, $file);
181         }
183         return $this;
184     }
186     /**
187      * Export the specified file in the target location.
188      *
189      * @param   array           $subcontext The location within the current context that this data belongs.
190      * @param   \stored_file    $file       The file to be exported.
191      */
192     public function export_file(array $subcontext, \stored_file $file) : content_writer {
193         if (!$file->is_directory()) {
194             $pathitems = array_merge(
195                 $subcontext,
196                 [$this->get_files_target_path($file->get_component(), $file->get_filearea(), $file->get_itemid())],
197                 [$file->get_filepath()]
198             );
199             $path = $this->get_path($pathitems, $file->get_filename());
200             check_dir_exists(dirname($path), true, true);
201             $this->files[$path] = $file;
202         }
204         return $this;
205     }
207     /**
208      * Export the specified user preference.
209      *
210      * @param   string          $component  The name of the component.
211      * @param   string          $key        The name of th key to be exported.
212      * @param   string          $value      The value of the preference
213      * @param   string          $description    A description of the value
214      * @return  content_writer
215      */
216     public function export_user_preference(string $component, string $key, string $value, string $description) : content_writer {
217         $subcontext = [
218             get_string('userpreferences'),
219         ];
220         $fullpath = $this->get_full_path($subcontext, "{$component}.json");
221         $path = $this->get_path($subcontext, "{$component}.json");
223         if (file_exists($fullpath)) {
224             $data = json_decode(file_get_contents($fullpath));
225         } else {
226             $data = (object) [];
227         }
229         $data->$key = (object) [
230             'value' => $value,
231             'description' => $description,
232         ];
233         $this->write_data($path, json_encode($data, JSON_UNESCAPED_UNICODE));
235         return $this;
236     }
238     /**
239      * Determine the path for the current context.
240      *
241      * @return  array                       The context path.
242      */
243     protected function get_context_path() : Array {
244         $path = [];
245         $contexts = array_reverse($this->context->get_parent_contexts(true));
246         foreach ($contexts as $context) {
247             $name = $context->get_context_name();
248             $id = $context->id;
249             $path[] = shorten_filename(clean_param("{$name} {$id}", PARAM_FILE), MAX_FILENAME_SIZE, true);
250         }
252         return $path;
253     }
255     /**
256      * Get the relative file path within the current context, and subcontext, using the specified filename.
257      *
258      * @param   string[]        $subcontext The location within the current context to export this data.
259      * @param   string          $name       The intended filename, including any extensions.
260      * @return  string                      The fully-qualfiied file path.
261      */
262     protected function get_path(array $subcontext, string $name) : string {
263         $subcontext = shorten_filenames($subcontext, MAX_FILENAME_SIZE, true);
264         $name = shorten_filename($name, MAX_FILENAME_SIZE, true);
266         // Combine the context path, and the subcontext data.
267         $path = array_merge(
268             $this->get_context_path(),
269             $subcontext
270         );
272         // Join the directory together with the name.
273         $filepath = implode(DIRECTORY_SEPARATOR, $path) . DIRECTORY_SEPARATOR . $name;
275         return preg_replace('@' . DIRECTORY_SEPARATOR . '+@', DIRECTORY_SEPARATOR, $filepath);
276     }
278     /**
279      * Get the fully-qualified file path within the current context, and subcontext, using the specified filename.
280      *
281      * @param   string[]        $subcontext The location within the current context to export this data.
282      * @param   string          $name       The intended filename, including any extensions.
283      * @return  string                      The fully-qualfiied file path.
284      */
285     protected function get_full_path(array $subcontext, string $name) : string {
286         $path = array_merge(
287             [$this->path],
288             [$this->get_path($subcontext, $name)]
289         );
291         // Join the directory together with the name.
292         $filepath = implode(DIRECTORY_SEPARATOR, $path);
294         return preg_replace('@' . DIRECTORY_SEPARATOR . '+@', DIRECTORY_SEPARATOR, $filepath);
295     }
297     /**
298      * Get a path within a subcontext where exported files should be written to.
299      *
300      * @param string $component The name of the component that the files belong to.
301      * @param string $filearea The filearea within that component.
302      * @param string $itemid Which item those files belong to.
303      * @return string The path
304      */
305     protected function get_files_target_path($component, $filearea, $itemid) : string {
307         // We do not need to include the component because we organise things by context.
308         $parts = ['_files', $filearea];
310         if (!empty($itemid)) {
311             $parts[] = $itemid;
312         }
314         return implode(DIRECTORY_SEPARATOR, $parts);
315     }
317     /**
318      * Write the data to the specified path.
319      *
320      * @param   string          $path       The path to export the data at.
321      * @param   string          $data       The data to be exported.
322      */
323     protected function write_data(string $path, string $data) {
324         $targetpath = $this->path . DIRECTORY_SEPARATOR . $path;
325         check_dir_exists(dirname($targetpath), true, true);
326         file_put_contents($targetpath, $data);
327         $this->files[$path] = $targetpath;
328     }
330     /**
331      * Perform any required finalisation steps and return the location of the finalised export.
332      *
333      * @return  string
334      */
335     public function finalise_content() : string {
336         $exportfile = make_request_directory() . '/export.zip';
338         $fp = get_file_packer();
339         $fp->archive_to_pathname($this->files, $exportfile);
341         // Reset the writer to prevent any further writes.
342         writer::reset();
344         return $exportfile;
345     }