MDL-33552 - portfolio api E_STRICT fixes
[moodle.git] / lib / portfolio / formats.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 all the class definitions of the export formats.
19  *
20  * They are implemented in php classes rather than just a simpler hash
21  * Because it provides an easy way to do subtyping using php inheritance.
22  *
23  * @package core_portfolio
24  * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
25  *                 Martin Dougiamas <http://dougiamas.com>
26  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
29 defined('MOODLE_INTERNAL') || die();
31 /**
32  * Base class to inherit from.
33  *
34  * Do not use this anywhere in supported_formats
35  *
36  * @package core_portfolio
37  * @category portfolio
38  * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
39  *                 Martin Dougiamas <http://dougiamas.com>
40  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  *
42  */
43 abstract class portfolio_format {
45     /**
46      * Array of mimetypes this format supports
47      *
48      * @throws coding_exception
49      */
50     public static function mimetypes() {
51         throw new coding_exception('mimetypes() method needs to be overridden in each subclass of portfolio_format');
52     }
54     /**
55      * For multipart formats, eg html with attachments,
56      * we need to have a directory to place associated files from
57      * inside the zip file. This is the name of that directory
58      *
59      * @throws coding_exception
60      */
61     public static function get_file_directory() {
62         throw new coding_exception('get_file_directory() method needs to be overridden in each subclass of portfolio_format');
63     }
65     /**
66      * Given a file, return a snippet of markup in whatever format
67      * to link to that file.
68      * Usually involves the path given by get_file_directory.
69      * This is not supported in subclasses of portfolio_format_file
70      * since they're all just single files.
71      * @see get_file_directory
72      *
73      * @param stored_file $file file information object
74      * @param array $options array of options to pass. can contain:
75      *              attributes => hash of existing html attributes (eg title, height, width, etc)
76      *
77      * @throws coding_exception
78      */
79     public static function file_output($file, $options=null) {
80         throw new coding_exception('file_output() method needs to be overridden in each subclass of portfolio_format');
81     }
83     /**
84      * Create portfolio tag
85      *
86      * @param stored_file $file file information object
87      * @param string $path file path
88      * @param array $attributes portfolio attributes
89      * @return string
90      */
91     public static function make_tag($file, $path, $attributes) {
92         $srcattr = 'href';
93         $tag     = 'a';
94         $content = $file->get_filename();
95         if (in_array($file->get_mimetype(), portfolio_format_image::mimetypes())) {
96             $srcattr = 'src';
97             $tag     = 'img';
98             $content = '';
99         }
101         $attributes[$srcattr] = $path; // this will override anything we might have been passed (which is good)
102         $dom = new DomDocument();
103         $elem = null;
104         if ($content) {
105             $elem = $dom->createElement($tag, $content);
106         } else {
107             $elem = $dom->createElement($tag);
108         }
110         foreach ($attributes as $key => $value) {
111             $elem->setAttribute($key, $value);
112         }
113         $dom->appendChild($elem);
114         return $dom->saveXML($elem);
115     }
117     /**
118      * Whether this format conflicts with the given format.
119      * This is used for the case where an export location
120      * "generally" supports something like FORMAT_PLAINHTML
121      * but then in a specific export case, must add attachments,
122      * which means that FORMAT_RICHHTML is supported in that case,
123      * which implies removing support for FORMAT_PLAINHTML.
124      * Note that conflicts don't have to be bi-directional
125      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
126      * but not the other way around) and things within the class hierarchy
127      * are resolved automatically anyway.
128      * This is really just between subclasses of format_rich
129      * and subclasses of format_file.
130      *
131      * @param string $format one of the FORMAT_XX constants
132      * @return bool
133      */
134     public static function conflicts($format) {
135         return false;
136     }
139 /**
140  * The most basic type - pretty much everything is a subtype
141  *
142  * @package core_portfolio
143  * @category portfolio
144  * @copyright 2009 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
145  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
146  */
147 class portfolio_format_file extends portfolio_format {
149     /**
150      * Array of mimetypes this format supports
151      *
152      * @return array
153      */
154     public static function mimetypes() {
155         return array();
156     }
158     /**
159      * For multipart formats, eg html with attachments,
160      * we need to have a directory to place associated files from
161      * inside the zip file. This is the name of that directory
162      *
163      * @return bool
164      */
165     public static function get_file_directory() {
166         return false;
167     }
169     /**
170      * Given a file, return a snippet of markup in whatever format
171      * to link to that file.
172      * Usually involves the path given by get_file_directory.
173      * This is not supported in subclasses of portfolio_format_file
174      * since they're all just single files.
175      * @see get_file_directory
176      *
177      * @param stored_file $file informations object
178      * @param array $options array of options to pass. can contain:
179      *              attributes => hash of existing html attributes (eg title, height, width, etc)
180      */
181     public static function file_output($file, $options=null) {
182         throw new portfolio_exception('fileoutputnotsupported', 'portfolio');
183     }
186 /**
187  * Image format, subtype of file.
188  *
189  * @package core_portfolio
190  * @category portfolio
191  * @copyright 2009 Penny Leach
192  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
193  */
194 class portfolio_format_image extends portfolio_format_file {
195     /**
196      * Return all mimetypes that use image.gif (eg all images)
197      *
198      * @return string
199      */
200     public static function mimetypes() {
201         return file_get_typegroup('type', 'image');
202     }
204     /**
205      * Whether this format conflicts with the given format.
206      * This is used for the case where an export location
207      * "generally" supports something like FORMAT_PLAINHTML
208      * but then in a specific export case, must add attachments,
209      * which means that FORMAT_RICHHTML is supported in that case,
210      * which implies removing support for FORMAT_PLAINHTML.
211      * Note that conflicts don't have to be bi-directional
212      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
213      * but not the other way around) and things within the class hierarchy
214      * are resolved automatically anyway.
215      * This is really just between subclasses of format_rich
216      * and subclasses of format_file.
217      *
218      * @param string $format one of the FORMAT_XX constants
219      * @return bool
220      */
221     public static function conflicts($format) {
222         return ($format == PORTFOLIO_FORMAT_RICHHTML
223             || $format == PORTFOLIO_FORMAT_PLAINHTML);
224     }
227 /**
228  * HTML format
229  *
230  * Could be used for an external cms or something in case we want to be really specific.
231  *
232  * @package core_portfolio
233  * @category portfolio
234  * @copyright 2008 Penny Leach
235  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
236  */
237 class portfolio_format_plainhtml extends portfolio_format_file {
239     /**
240      * Return html mimetype
241      *
242      * @return array
243      */
244     public static function mimetypes() {
245         return array('text/html');
246     }
248     /**
249      * Whether this format conflicts with the given format.
250      * This is used for the case where an export location
251      * "generally" supports something like FORMAT_PLAINHTML
252      * but then in a specific export case, must add attachments,
253      * which means that FORMAT_RICHHTML is supported in that case,
254      * which implies removing support for FORMAT_PLAINHTML.
255      * Note that conflicts don't have to be bi-directional
256      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
257      * but not the other way around) and things within the class hierarchy
258      * are resolved automatically anyway.
259      * This is really just between subclasses of format_rich
260      * and subclasses of format_file.
261      *
262      * @param string $format one of the FORMAT_XX constants
263      * @return bool
264      */
265     public static function conflicts($format) {
266         return ($format == PORTFOLIO_FORMAT_RICHHTML
267             || $format == PORTFOLIO_FORMAT_FILE);
268     }
271 /**
272  * Video format
273  *
274  * For portfolio plugins that support videos specifically
275  *
276  * @package core_portfolio
277  * @category portfolio
278  * @copyright 2008 Penny Leach
279  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
280  */
281 class portfolio_format_video extends portfolio_format_file {
283      /**
284       * Return video mimetypes
285       *
286       * @return array
287       */
288     public static function mimetypes() {
289         return file_get_typegroup('type', 'video');
290     }
293 /**
294  * Class for plain text format.
295  *
296  * Not sure why we would need this yet,
297  * but since resource module wants to export it... we can
298  *
299  * @package core_portfolio
300  * @category portfolio
301  * @copyright 2008 Penny Leach
302  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
303  */
304 class portfolio_format_text extends portfolio_format_file {
306     /**
307      * Return plain text mimetypes
308      *
309      * @return array
310      */
311     public static function mimetypes() {
312         return array('text/plain');
313     }
315     /**
316      * Whether this format conflicts with the given format.
317      * This is used for the case where an export location
318      * "generally" supports something like FORMAT_PLAINHTML
319      * but then in a specific export case, must add attachments,
320      * which means that FORMAT_RICHHTML is supported in that case,
321      * which implies removing support for FORMAT_PLAINHTML.
322      * Note that conflicts don't have to be bi-directional
323      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
324      * but not the other way around) and things within the class hierarchy
325      * are resolved automatically anyway.
326      * This is really just between subclasses of format_rich
327      * and subclasses of format_file.
328      *
329      * @param string $format one of the FORMAT_XX constants
330      * @return bool
331      */
332     public static function conflicts($format ) {
333         return ($format == PORTFOLIO_FORMAT_PLAINHTML
334             || $format == PORTFOLIO_FORMAT_RICHHTML);
335     }
338 /**
339  * Base class for rich formats.
340  *
341  * These are multipart - eg things with attachments
342  *
343  * @package core_portfolio
344  * @category portfolio
345  * @copyright 2009 Penny Leach
346  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
347  */
348 abstract class portfolio_format_rich extends portfolio_format {
350     /**
351      * Return rich text mimetypes
352      *
353      * @return array
354      */
355     public static function mimetypes() {
356         return array();
357     }
361 /**
362  * Richhtml - html with attachments.
363  *
364  * The most commonly used rich format
365  * eg inline images
366  *
367  * @package core_portfolio
368  * @category portfolio
369  * @copyright 2009 Penny Leach
370  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
371  */
372 class portfolio_format_richhtml extends portfolio_format_rich {
374     /**
375      * For multipart formats, eg html with attachments,
376      * we need to have a directory to place associated files from
377      * inside the zip file. this is the name of that directory
378      *
379      * @return string
380      */
381     public static function get_file_directory() {
382         return 'site_files/';
383     }
385     /**
386      * Given a file, return a snippet of markup in whatever format
387      * to link to that file.
388      * Usually involves the path given by get_file_directory.
389      * This is not supported in subclasses of portfolio_format_file
390      * since they're all just single files.
391      * @see get_file_directory
392      *
393      * @param stored_file $file information for existing file
394      * @param array $options array of options to pass. can contain:
395      *              attributes => hash of existing html attributes (eg title, height, width, etc)
396      * @return string
397      */
398     public static function file_output($file, $options=null) {
399         $path = self::get_file_directory() . $file->get_filename();
400         $attributes = array();
401         if (!empty($options['attributes']) && is_array($options['attributes'])) {
402             $attributes = $options['attributes'];
403         }
404         return self::make_tag($file, $path, $attributes);
405     }
407     /**
408      * Whether this format conflicts with the given format.
409      * This is used for the case where an export location
410      * "generally" supports something like FORMAT_PLAINHTML
411      * but then in a specific export case, must add attachments,
412      * which means that FORMAT_RICHHTML is supported in that case,
413      * which implies removing support for FORMAT_PLAINHTML.
414      * Note that conflicts don't have to be bi-directional
415      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
416      * but not the other way around) and things within the class hierarchy
417      * are resolved automatically anyway.
418      * This is really just between subclasses of format_rich
419      * and subclasses of format_file.
420      *
421      * @todo MDL-31305 - revisit the conflict with file, since we zip here
422      * @param string $format one of the FORMAT_XX constants
423      * @return bool
424      */
425     public static function conflicts($format) { // TODO revisit the conflict with file, since we zip here
426         return ($format == PORTFOLIO_FORMAT_PLAINHTML || $format == PORTFOLIO_FORMAT_FILE);
427     }
431 /**
432  * Class used for leap2a format
433  *
434  * @package core_portfolio
435  * @category portfolio
436  * @copyright 2009 Penny Leach
437  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
438  */
439 class portfolio_format_leap2a extends portfolio_format_rich {
441     /**
442      * For multipart formats, eg html with attachments,
443      * we need to have a directory to place associated files from
444      * inside the zip file. this is the name of that directory
445      *
446      * @return string
447      */
448     public static function get_file_directory() {
449         return 'files/';
450     }
452     /**
453      * Return the file prefix
454      *
455      * @return string
456      */
457     public static function file_id_prefix() {
458         return 'storedfile';
459     }
461     /**
462      * Return the link to a file
463      *
464      * @param stored_file $file information for existing file
465      * @param array $options array of options to pass. can contain:
466      *              attributes => hash of existing html attributes (eg title, height, width, etc)
467      * @return string
468      */
469     public static function file_output($file, $options=null) {
470         $id = '';
471         if (!is_array($options)) {
472             $options = array();
473         }
474         if (!array_key_exists('entry', $options)) {
475             $options['entry'] = true;
476         }
477         if (!empty($options['entry'])) {
478             $path = 'portfolio:' . self::file_id_prefix() . $file->get_id();
479         } else {
480             $path = self::get_file_directory() . $file->get_filename();
481         }
482         $attributes = array();
483         if (!empty($options['attributes']) && is_array($options['attributes'])) {
484             $attributes = $options['attributes'];
485         }
486         $attributes['rel']    = 'enclosure';
487         return self::make_tag($file, $path, $attributes);
488     }
490     /**
491      * Generate portfolio_format_leap2a
492      *
493      * @param stdclass $user user information object
494      * @return portfolio_format_leap2a_writer
495      */
496     public static function leap2a_writer(stdclass $user=null) {
497         global $CFG;
498         if (empty($user)) {
499             global $USER;
500             $user = $USER;
501         }
502         require_once($CFG->libdir . '/portfolio/formats/leap2a/lib.php');
503         return new portfolio_format_leap2a_writer($user);
504     }
506     /**
507      * Return the manifest name
508      *
509      * @return string
510      */
511     public static function manifest_name() {
512         return 'leap2a.xml';
513     }
517 // later.... a moodle plugin might support this.
518 // it's commented out in portfolio_supported_formats so cannot currently be used.
519 //class portfolio_format_mbkp extends portfolio_format_rich {}
521 /**
522  * 'PDF format', subtype of file.
523  *
524  * For portfolio plugins that support PDFs specifically.
525  *
526  * @package core_portfolio
527  * @category portfolio
528  * @copyright 2009 Dan Poltawski
529  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
530  */
531 class portfolio_format_pdf extends portfolio_format_file {
533     /**
534      * Return pdf mimetypes
535      *
536      * @return array
537      */
538     public static function mimetypes() {
539         return array('application/pdf');
540     }
543 /**
544  * 'Document format', subtype of file.
545  *
546  * For portfolio plugins that support documents specifically.
547  *
548  * @package core_portfolio
549  * @category portfolio
550  * @copyright 2009 Dan Poltawski
551  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
552  */
553 class portfolio_format_document extends portfolio_format_file {
555     /**
556      * Return documents mimetypes
557      *
558      * @return array of documents mimetypes
559      */
560     public static function mimetypes() {
561         return file_get_typegroup('type', 'document');
562     }
565 /**
566  * 'Spreadsheet format', subtype of file.
567  *
568  * For portfolio plugins that support spreadsheets specifically.
569  *
570  * @package core_portfolio
571  * @category portfolio
572  * @copyright 2009 Dan Poltawski
573  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
574  */
575 class portfolio_format_spreadsheet extends portfolio_format_file {
577     /**
578      * Return spreadsheet spreadsheet mimetypes
579      *
580      * @return array of documents mimetypes
581      */
582     public static function mimetypes() {
583         return file_get_typegroup('type', 'spreadsheet');
584     }
587 /**
588  * 'Presentation format', subtype of file.
589  *
590  * For portfolio plugins that support presentation specifically.
591  *
592  * @package core_portfolio
593  * @category portfolio
594  * @copyright 2009 Dan Poltawski
595  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
596  */
597 class portfolio_format_presentation extends portfolio_format_file {
599     /**
600      * Return presentation documents mimetypes
601      *
602      * @return array presentation document mimetypes
603      */
604     public static function mimetypes() {
605         return file_get_typegroup('type', 'presentation');
606     }