MDL-71981 dataformat: indicate HTML support in writer callback.
[moodle.git] / lib / classes / dataformat.php
CommitLineData
8844cb82
PH
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/>.
16
17/**
18 * Class containing utility methods for dataformats
19 *
20 * @package core
c1c57e81 21 * @copyright 2020 Paul Holden <paulh@moodle.com>
8844cb82 22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
8844cb82
PH
23 */
24
25namespace core;
26
27use coding_exception;
28use core_php_time_limit;
b670d3ad 29use stored_file;
8844cb82
PH
30
31/**
32 * Dataformat utility class
33 *
34 * @package core
c1c57e81 35 * @copyright 2020 Paul Holden <paulh@moodle.com>
8844cb82 36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
8844cb82
PH
37 */
38class dataformat {
39
40 /**
c1c57e81 41 * Return an instance of a dataformat writer from given dataformat type
8844cb82
PH
42 *
43 * @param string $dataformat
44 * @return dataformat\base
45 * @throws coding_exception
46 */
47 protected static function get_format_instance(string $dataformat): \core\dataformat\base {
48 $classname = 'dataformat_' . $dataformat . '\writer';
49 if (!class_exists($classname)) {
50 throw new coding_exception('Invalid dataformat', $dataformat);
51 }
52
53 return new $classname();
54 }
55
56 /**
57 * Sends a formatted data file to the browser
58 *
59 * @param string $filename
60 * @param string $dataformat
61 * @param array $columns
62 * @param Iterable $iterator
f3b3684e
PH
63 * @param callable|null $callback Optional callback method to apply to each record prior to writing, which accepts two
64 * parameters as such: function($record, bool $supportshtml) returning formatted record
8844cb82
PH
65 * @throws coding_exception
66 */
67 public static function download_data(string $filename, string $dataformat, array $columns, Iterable $iterator,
68 callable $callback = null): void {
69
70 if (ob_get_length()) {
71 throw new coding_exception('Output can not be buffered before calling download_data()');
72 }
73
74 $format = self::get_format_instance($dataformat);
75
76 // The data format export could take a while to generate.
77 core_php_time_limit::raise();
78
79 // Close the session so that the users other tabs in the same session are not blocked.
80 \core\session\manager::write_close();
81
82 // If this file was requested from a form, then mark download as complete (before sending headers).
83 \core_form\util::form_download_complete();
84
85 $format->set_filename($filename);
86 $format->send_http_headers();
87
88 $format->start_output();
89 $format->start_sheet($columns);
90
91 $rownum = 0;
92 foreach ($iterator as $row) {
93 if (is_callable($callback)) {
f3b3684e 94 $row = $callback($row, $format->supports_html());
8844cb82
PH
95 }
96 if ($row === null) {
97 continue;
98 }
99 $format->write_record($row, $rownum++);
100 }
101
102 $format->close_sheet($columns);
103 $format->close_output();
104 }
105
106 /**
107 * Writes a formatted data file with specified filename
108 *
109 * @param string $filename
110 * @param string $dataformat
111 * @param array $columns
112 * @param Iterable $iterator
113 * @param callable|null $callback
114 * @return string Complete path to the file on disk
115 */
116 public static function write_data(string $filename, string $dataformat, array $columns, Iterable $iterator,
117 callable $callback = null): string {
118
119 $format = self::get_format_instance($dataformat);
120
121 // The data format export could take a while to generate.
122 core_php_time_limit::raise();
123
124 // Close the session so that the users other tabs in the same session are not blocked.
125 \core\session\manager::write_close();
126
127 $filepath = make_request_directory() . '/' . $filename . $format->get_extension();
128 $format->set_filepath($filepath);
129
130 $format->start_output_to_file();
131 $format->start_sheet($columns);
132
133 $rownum = 0;
134 foreach ($iterator as $row) {
135 if (is_callable($callback)) {
f3b3684e 136 $row = $callback($row, $format->supports_html());
8844cb82
PH
137 }
138 if ($row === null) {
139 continue;
140 }
141 $format->write_record($row, $rownum++);
142 }
143
144 $format->close_sheet($columns);
145 $format->close_output_to_file();
146
147 return $filepath;
148 }
b670d3ad
PH
149
150 /**
151 * Writes a formatted data file to file storage
152 *
153 * @param array $filerecord File record for storage, 'filename' extension should be omitted as it's added by the dataformat
154 * @param string $dataformat
155 * @param array $columns
156 * @param Iterable $iterator Iterable set of records to write
157 * @param callable|null $callback Optional callback method to apply to each record prior to writing
158 * @return stored_file
159 */
160 public static function write_data_to_filearea(array $filerecord, string $dataformat, array $columns, Iterable $iterator,
161 callable $callback = null): stored_file {
162
163 $filepath = self::write_data($filerecord['filename'], $dataformat, $columns, $iterator, $callback);
164
165 // Update filename of returned file record.
166 $filerecord['filename'] = basename($filepath);
167
168 return get_file_storage()->create_file_from_pathname($filerecord, $filepath);
169 }
8844cb82 170}