Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
  • Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * This file contains the LEAP2a writer used by portfolio_format_leap2a
 *
 * @package core_portfolio
 * @copyright 2009 Penny Leach (penny@liip.ch), Martin Dougiamas
 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 *
 */

defined('MOODLE_INTERNAL') || die();

/**
 * Object to encapsulate the writing of leap2a.
 *
 * Should be used like:
 * $writer = portfolio_format_leap2a::leap2a_writer($USER);
 * $entry = new portfolio_format_leap2a_entry('forumpost6', $title, 'leap2', 'somecontent')
 * $entry->add_link('something', 'has_part')->add_link('somethingelse', 'has_part');
 * .. etc
 * $writer->add_entry($entry);
 * $xmlstr = $writer->to_xml();
 *
 * @todo MDL-31287 - find a way to ensure that all referenced files are included
 * @package core_portfolio
 * @category portfolio
 * @copyright 2009 Penny Leach
 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class portfolio_format_leap2a_writer {

    /** @var DomDocument the domdocument object used to create elements */
    private $dom;

    /** @var DOMElement the top level feed element */
    private $feed;

    /** @var stdClass the user exporting data */
    private $user;

< /** @var string the id of the feed - this is unique to the user and date and used for portfolio ns as well as feed id */ < private $id; <
/** @var array the entries for the feed - keyed on id */ private $entries = array(); /** * Constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER); * * @todo MDL-31302 - add exporter and format * @param stdclass $user the user exporting (almost always $USER) */ public function __construct(stdclass $user) { // todo something else - exporter, format, etc global $CFG; $this->user = $user;
< $this->exporttime = time(); < $this->id = $CFG->wwwroot . '/portfolio/export/leap2a/' . $this->user->id . '/' . $this->exporttime;
> $id = $CFG->wwwroot . '/portfolio/export/leap2a/' . $this->user->id . '/' . time();
$this->dom = new DomDocument('1.0', 'utf-8'); $this->feed = $this->dom->createElement('feed'); $this->feed->setAttribute('xmlns', 'http://www.w3.org/2005/Atom'); $this->feed->setAttribute('xmlns:rdf', 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'); $this->feed->setAttribute('xmlns:leap2', 'http://terms.leapspecs.org/'); $this->feed->setAttribute('xmlns:categories', 'http://wiki.leapspecs.org/2A/categories');
< $this->feed->setAttribute('xmlns:portfolio', $this->id); // this is just a ns for ids of elements for convenience
> $this->feed->setAttribute('xmlns:portfolio', $id); // This is just a ns for ids of elements for convenience.
$this->dom->appendChild($this->feed);
< $this->feed->appendChild($this->dom->createElement('id', $this->id));
> $this->feed->appendChild($this->dom->createElement('id', $id));
$this->feed->appendChild($this->dom->createElement('title', get_string('leap2a_feedtitle', 'portfolio', fullname($this->user)))); $this->feed->appendChild($this->dom->createElement('leap2:version', 'http://www.leapspecs.org/2010-07/2A/')); $generator = $this->dom->createElement('generator', 'Moodle'); $generator->setAttribute('uri', $CFG->wwwroot); $generator->setAttribute('version', $CFG->version); $this->feed->appendChild($generator); $author = $this->dom->createElement('author'); $author->appendChild($this->dom->createElement('name', fullname($this->user))); $author->appendChild($this->dom->createElement('email', $this->user->email)); $author->appendChild($this->dom->CreateElement('uri', $CFG->wwwroot . '/user/view.php?id=' . $this->user->id)); $this->feed->appendChild($author); // header done, we can start appending entry elements now } /** * Adds a entry to the feed ready to be exported * * @param portfolio_format_leap2a_entry $entry new feed entry to add * @return portfolio_format_leap2a_entry */ public function add_entry(portfolio_format_leap2a_entry $entry) { if (array_key_exists($entry->id, $this->entries)) { if (!($entry instanceof portfolio_format_leap2a_file)) { throw new portfolio_format_leap2a_exception('leap2a_entryalreadyexists', 'portfolio', '', $entry->id); } } $this->entries[$entry->id] = $entry; return $entry; } /** * Select an entry that has previously been added into the feed * * @param portfolio_format_leap2a_entry|string $selectionentry the entry to make a selection (id or entry object) * @param array $ids array of ids this selection includes * @param string $selectiontype for selection type, see: http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories/selection_type */ public function make_selection($selectionentry, $ids, $selectiontype) { $selectionid = null; if ($selectionentry instanceof portfolio_format_leap2a_entry) { $selectionid = $selectionentry->id; } else if (is_string($selectionentry)) { $selectionid = $selectionentry; } if (!array_key_exists($selectionid, $this->entries)) { throw new portfolio_format_leap2a_exception('leap2a_invalidentryid', 'portfolio', '', $selectionid); } foreach ($ids as $entryid) { if (!array_key_exists($entryid, $this->entries)) { throw new portfolio_format_leap2a_exception('leap2a_invalidentryid', 'portfolio', '', $entryid); } $this->entries[$selectionid]->add_link($entryid, 'has_part'); $this->entries[$entryid]->add_link($selectionid, 'is_part_of'); } $this->entries[$selectionid]->add_category($selectiontype, 'selection_type'); if ($this->entries[$selectionid]->type != 'selection') { debugging(get_string('leap2a_overwritingselection', 'portfolio', $this->entries[$selectionid]->type)); $this->entries[$selectionid]->type = 'selection'; } } /** * Helper function to link some stored_files into the feed and link them to a particular entry * * @param portfolio_format_leap2a_entry $entry feed object * @param array $files array of stored_files to link */ public function link_files($entry, $files) { foreach ($files as $file) { $fileentry = new portfolio_format_leap2a_file($file->get_filename(), $file); $this->add_entry($fileentry); $entry->add_link($fileentry, 'related'); $fileentry->add_link($entry, 'related'); } } /** * Validate the feed and all entries */ private function validate() { foreach ($this->entries as $entry) { // first call the entry's own validation method // which will throw an exception if there's anything wrong $entry->validate(); // now make sure that all links are in place foreach ($entry->links as $linkedid => $rel) { // the linked to entry exists if (!array_key_exists($linkedid, $this->entries)) { $a = (object)array('rel' => $rel->type, 'to' => $linkedid, 'from' => $entry->id); throw new portfolio_format_leap2a_exception('leap2a_nonexistantlink', 'portfolio', '', $a); } // and contains a link back to us if (!array_key_exists($entry->id, $this->entries[$linkedid]->links)) { } // we could later check that the reltypes were properly inverse, but nevermind for now. } } } /** * Return the entire feed as a string. * Then, it calls for validation * * @return string feeds' content in xml */ public function to_xml() { $this->validate(); foreach ($this->entries as $entry) { $entry->id = 'portfolio:' . $entry->id; $this->feed->appendChild($entry->to_dom($this->dom, $this->user)); } return $this->dom->saveXML(); } } /** * This class represents a single leap2a entry. * * You can create these directly and then add them to the main leap feed object * * @package core_portfolio * @category portfolio * @copyright 2009 Penny Leach * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class portfolio_format_leap2a_entry { /** @var string entry id - something like forumpost6, must be unique to the feed */ public $id; /** @var string title of the entry */ public $title; /** @var string leap2a entry type */ public $type; /** @var string optional author (only if different to feed author) */ public $author; /** @var string summary - for split long content */ public $summary; /** @var mixed main content of the entry. can be html,text,or xhtml. for a stored_file, use portfolio_format_leap2a_file **/ public $content; /** @var int updated date - unix timestamp */ public $updated; /** @var int published date (ctime) - unix timestamp */ public $published; /** @var array the required fields for a leap2a entry */ private $requiredfields = array( 'id', 'title', 'type'); /** @var array extra fields which usually should be set (except author) but are not required */ private $optionalfields = array('author', 'updated', 'published', 'content', 'summary'); /** @var array links from this entry to other entries */ public $links = array(); /** @var array attachments to this entry */ public $attachments = array(); /** @var array categories for this entry */ private $categories = array(); /** * Constructor. All arguments are required (and will be validated) * http://wiki.cetis.ac.uk/2009-03/LEAP2A_types * * @param string $id unique id of this entry. * could be something like forumpost6 for example. * This <b>must</b> be unique to the entire feed. * @param string $title title of the entry. This is pure atom. * @param string $type the leap type of this entry. * @param mixed $content the content of the entry. string (xhtml/html/text) */ public function __construct($id, $title, $type, $content=null) { $this->id = $id; $this->title = $title; $this->type = $type; $this->content = $this->__set('content', $content); } /** * Override __set to do proper dispatching for different things. * Only allows the optional and required leap2a entry fields to be set * * @param string $field property's name * @param mixed $value property's value * @return mixed */ public function __set($field, $value) { // detect the case where content is being set to be a file directly if ($field == 'content' && $value instanceof stored_file) { throw new portfolio_format_leap2a_exception('leap2a_filecontent', 'portfolio'); } if (in_array($field, $this->requiredfields) || in_array($field, $this->optionalfields)) { return $this->{$field} = $value; } throw new portfolio_format_leap2a_exception('leap2a_invalidentryfield', 'portfolio', '', $field); } /** * Validate this entry. * At the moment this just makes sure required fields exist * but it could also check things against a list, for example * * @todo MDL-31303 - add category with a scheme 'selection_type' */ public function validate() { foreach ($this->requiredfields as $key) { if (empty($this->{$key})) { throw new portfolio_format_leap2a_exception('leap2a_missingfield', 'portfolio', '', $key); } } if ($this->type == 'selection') { if (count($this->links) == 0) { throw new portfolio_format_leap2a_exception('leap2a_emptyselection', 'portfolio'); } //TODO make sure we have a category with a scheme 'selection_type' } } /** * Add a link from this entry to another one. * These will be collated at the end of the export (during to_xml) * and validated at that point. This function does no validation * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_relationships} * * @param portfolio_format_leap2a_entry|string $otherentry portfolio_format_leap2a_entry or its id * @param string $reltype (no leap2: ns required) * @param string $displayorder (optional) * @return portfolio_format_leap2a_entry the current entry object. This is so that these calls can be chained * eg $entry->add_link('something6', 'has_part')->add_link('something7', * 'has_part'); */ public function add_link($otherentry, $reltype, $displayorder=null) { if ($otherentry instanceof portfolio_format_leap2a_entry) { $otherentry = $otherentry->id; } if ($otherentry == $this->id) { throw new portfolio_format_leap2a_exception('leap2a_selflink', 'portfolio', '', (object)array('rel' => $reltype, 'id' => $this->id)); } // add on the leap2: ns if required if (!in_array($reltype, array('related', 'alternate', 'enclosure'))) { $reltype = 'leap2:' . $reltype; } $this->links[$otherentry] = (object)array('rel' => $reltype, 'order' => $displayorder); return $this; } /** * Add a category to this entry * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories} * "tags" should just pass a term here and no scheme or label. * They will be automatically normalised if they have spaces. * * @param string $term eg 'Offline' * @param string $scheme (optional) eg resource_type * @param string $label (optional) eg File */ public function add_category($term, $scheme=null, $label=null) { // "normalise" terms and set their label if they have spaces // see http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories#Plain_tags for more information if (empty($scheme) && strpos($term, ' ') !== false) { $label = $term; $term = str_replace(' ', '-', $term); } $this->categories[] = (object)array( 'term' => $term, 'scheme' => $scheme, 'label' => $label, ); } /** * Create an entry element and append all the children * And return it rather than adding it to the dom. * This is handled by the main writer object. * * @param DomDocument $dom use this to create elements * @param stdClass $feedauthor object of author(user) info * @return DOMDocument */ public function to_dom(DomDocument $dom, $feedauthor) { $entry = $dom->createElement('entry'); $entry->appendChild($dom->createElement('id', $this->id)); $entry->appendChild($dom->createElement('title', $this->title)); if ($this->author && $this->author->id != $feedauthor->id) { $author = $dom->createElement('author'); $author->appendChild($dom->createElement('name', fullname($this->author))); $entry->appendChild($author); } // selectively add uncomplicated optional elements foreach (array('updated', 'published') as $field) { if ($this->{$field}) { $date = date(DATE_ATOM, $this->{$field}); $entry->appendChild($dom->createElement($field, $date)); } } if (empty($this->content)) { $entry->appendChild($dom->createElement('content')); } else { $content = $this->create_xhtmlish_element($dom, 'content', $this->content); $entry->appendChild($content); } if (!empty($this->summary)) { $summary = $this->create_xhtmlish_element($dom, 'summary', $this->summary); $entry->appendChild($summary); } $type = $dom->createElement('rdf:type'); $type->setAttribute('rdf:resource', 'leap2:' . $this->type); $entry->appendChild($type); foreach ($this->links as $otherentry => $l) { $link = $dom->createElement('link'); $link->setAttribute('rel', $l->rel); $link->setAttribute('href', 'portfolio:' . $otherentry); if ($l->order) { $link->setAttribute('leap2:display_order', $l->order); } $entry->appendChild($link); } $this->add_extra_links($dom, $entry); // hook for subclass foreach ($this->categories as $category) { $cat = $dom->createElement('category'); $cat->setAttribute('term', $category->term); if ($category->scheme) { $cat->setAttribute('scheme', 'categories:' .$category->scheme . '#'); } if ($category->label && $category->label != $category->term) { $cat->setAttribute('label', $category->label); } $entry->appendChild($cat); } return $entry; } /** * Try to load whatever is in $content into xhtml and add it to the dom. * Failing that, load the html, escape it, and set it as the body of the tag. * Either way it sets the type attribute of the top level element. * Moodle should always provide xhtml content, but user-defined content can't be trusted * * @todo MDL-31304 - convert <html><body> </body></html> to xml * @param DomDocument $dom the dom doc to use * @param string $tagname usually 'content' or 'summary' * @param string $content the content to use, either xhtml or html. * @return DomDocument */ private function create_xhtmlish_element(DomDocument $dom, $tagname, $content) { $topel = $dom->createElement($tagname); $maybexml = true; if (strpos($content, '<') === false && strpos($content, '>') === false) { $maybexml = false; } // try to load content as xml $tmp = new DomDocument(); if ($maybexml && @$tmp->loadXML('<div>' . $content . '</div>')) { $topel->setAttribute('type', 'xhtml'); $content = $dom->importNode($tmp->documentElement, true); $content->setAttribute('xmlns', 'http://www.w3.org/1999/xhtml'); $topel->appendChild($content); // if that fails, it could still be html } else if ($maybexml && @$tmp->loadHTML($content)) { $topel->setAttribute('type', 'html'); $topel->nodeValue = $content; // TODO figure out how to convert this to xml // TODO because we end up with <html><body> </body></html> wrapped around it // which is annoying // either we already know it's text from the first check // or nothing else has worked anyway } else { $topel->nodeValue = $content; $topel->setAttribute('type', 'text'); return $topel; } return $topel; } /** * Hook function for subclasses to add extra links (like for files) * * @param DomDocument $dom feed object * @param DomDocument $entry feed added link */ protected function add_extra_links($dom, $entry) {} } /** * Subclass of entry, purely for dealing with files * * @package core_portfolio * @category portfolio * @copyright 2009 Penny Leach * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class portfolio_format_leap2a_file extends portfolio_format_leap2a_entry { /** @var file_stored for the dealing file */ protected $referencedfile; /** * Overridden constructor to set up the file. * * @param string $title title of the entry * @param stored_file $file file storage instance */ public function __construct($title, stored_file $file) { $id = portfolio_format_leap2a::file_id_prefix() . $file->get_id(); parent::__construct($id, $title, 'resource'); $this->referencedfile = $file; $this->published = $this->referencedfile->get_timecreated(); $this->updated = $this->referencedfile->get_timemodified(); $this->add_category('offline', 'resource_type'); } /** * Implement the hook to add extra links to attach the file in an enclosure * * @param DomDocument $dom feed object * @param DomDocument $entry feed added link */ protected function add_extra_links($dom, $entry) { $link = $dom->createElement('link'); $link->setAttribute('rel', 'enclosure'); $link->setAttribute('href', portfolio_format_leap2a::get_file_directory() . $this->referencedfile->get_filename()); $link->setAttribute('length', $this->referencedfile->get_filesize()); $link->setAttribute('type', $this->referencedfile->get_mimetype()); $entry->appendChild($link); } }