Your IP : 192.168.165.1
<?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 base classes for portfolio plugins to inherit from:
*
* portfolio_plugin_pull_base and portfolio_plugin_push_base
* which both in turn inherit from portfolio_plugin_base.
* {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin}
*
* @package core_portfolio
* @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
* Martin Dougiamas <http://dougiamas.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();
/**
* The base class for portfolio plugins.
*
* All plugins must subclass this
* either via portfolio_plugin_pull_base or portfolio_plugin_push_base
* @see portfolio_plugin_pull_base
* @see portfolio_plugin_push_base
*
* @package core_portfolio
* @category portfolio
* @copyright 2008 Penny Leach <penny@catalyst.net.nz>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class portfolio_plugin_base {
/** @var bool whether this object needs writing out to the database */
protected $dirty;
/** @var integer id of instance */
protected $id;
/** @var string name of instance */
protected $name;
/** @var string plugin this instance belongs to */
protected $plugin;
/** @var bool whether this instance is visible or not */
protected $visible;
/** @var array admin configured config use {@link set_config} and {@get_config} to access */
protected $config;
/** @var array user config cache. keyed on userid and then on config field => value use {@link get_user_config} and {@link set_user_config} to access. */
protected $userconfig;
/** @var array export config during export use {@link get_export_config} and {@link set export_config} to access. */
protected $exportconfig;
/** @var stdClass user currently exporting data */
protected $user;
/** @var stdClass a reference to the exporter object */
protected $exporter;
/**
* Array of formats this portfolio supports
* the intersection of what this function returns
* and what the caller supports will be used.
* Use the constants PORTFOLIO_FORMAT_*
*
* @return array list of formats
*/
public function supported_formats() {
return array(PORTFOLIO_FORMAT_FILE, PORTFOLIO_FORMAT_RICH);
}
/**
* Override this if you are supporting the 'file' type (or a subformat)
* but have restrictions on mimetypes
*
* @param string $mimetype file type or subformat
* @return bool
*/
public static function file_mime_check($mimetype) {
return true;
}
/**
* How long does this reasonably expect to take..
* Should we offer the user the option to wait..
* This is deliberately nonstatic so it can take filesize into account
*
* @param string $callertime - what the caller thinks
* the portfolio plugin instance
* is given the final say
* because it might be (for example) download.
*/
public abstract function expected_time($callertime);
/**
* Is this plugin push or pull.
* If push, cleanup will be called directly after send_package
* If not, cleanup will be called after portfolio/file.php is requested
*/
public abstract function is_push();
/**
* Returns the user-friendly name for this plugin.
* Usually just get_string('pluginname', 'portfolio_something')
*/
public static function get_name() {
throw new coding_exception('get_name() method needs to be overridden in each subclass of portfolio_plugin_base');
}
/**
* Check sanity of plugin.
* If this function returns something non empty, ALL instances of your plugin
* will be set to invisble and not be able to be set back until it's fixed
*
* @return string|int|bool - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
*/
public static function plugin_sanity_check() {
return 0;
}
/**
* Check sanity of instances.
* If this function returns something non empty, the instance will be
* set to invislbe and not be able to be set back until it's fixed.
*
* @return int|string|bool - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
*/
public function instance_sanity_check() {
return 0;
}
/**
* Does this plugin need any configuration by the administrator?
* If you override this to return true,
* you <b>must</b> implement admin_config_form.
* @see admin_config_form
*
* @return bool
*/
public static function has_admin_config() {
return false;
}
/**
* Can this plugin be configured by the user in their profile?
* If you override this to return true,
* you <b>must</b> implement user_config_form
* @see user_config_form
*
* @return bool
*/
public function has_user_config() {
return false;
}
/**
* Does this plugin need configuration during export time?
* If you override this to return true,
* you <b>must</b> implement export_config_form.
* @see export_config_form
*
* @return bool
*/
public function has_export_config() {
return false;
}
/**
* Just like the moodle form validation function.
* This is passed in the data array from the form
* and if a non empty array is returned, form processing will stop.
*
* @param array $data data from form.
*/
public function export_config_validation(array $data) {}
/**
* Just like the moodle form validation function.
* This is passed in the data array from the form
* and if a non empty array is returned, form processing will stop.
*
* @param array $data data from form.
*/
public function user_config_validation(array $data) {}
/**
* Sets the export time config from the moodle form.
* You can also use this to set export config that
* isn't actually controlled by the user.
* Eg: things that your subclasses want to keep in state
* across the export.
* Keys must be in get_allowed_export_config
* This is deliberately not final (see boxnet plugin)
* @see get_allowed_export_config
*
* @param array $config named array of config items to set.
*/
public function set_export_config($config) {
$allowed = array_merge(
array('wait', 'hidewait', 'format', 'hideformat'),
$this->get_allowed_export_config()
);
foreach ($config as $key => $value) {
if (!in_array($key, $allowed)) {
$a = (object)array('property' => $key, 'class' => get_class($this));
throw new portfolio_export_exception($this->get('exporter'), 'invalidexportproperty', 'portfolio', null, $a);
}
$this->exportconfig[$key] = $value;
}
}
/**
* Gets an export time config value.
* Subclasses should not override this.
*
* @param string $key field to fetch
* @return null|string config value
*/
public final function get_export_config($key) {
$allowed = array_merge(
array('hidewait', 'wait', 'format', 'hideformat'),
$this->get_allowed_export_config()
);
if (!in_array($key, $allowed)) {
$a = (object)array('property' => $key, 'class' => get_class($this));
throw new portfolio_export_exception($this->get('exporter'), 'invalidexportproperty', 'portfolio', null, $a);
}
if (!array_key_exists($key, $this->exportconfig)) {
return null;
}
return $this->exportconfig[$key];
}
/**
* After the user submits their config,
* they're given a confirm screen
* summarising what they've chosen.
* This function should return a table of nice strings => values
* of what they've chosen
* to be displayed in a table.
*
* @return bool
*/
public function get_export_summary() {
return false;
}
/**
* Called after the caller has finished having control
* of its prepare_package function.
* This function should read all the files from the portfolio
* working file area and zip them and send them or whatever it wants.
* get_tempfiles to get the list of files.
* @see get_tempfiles
*
*/
public abstract function prepare_package();
/**
* This is the function that is responsible for sending
* the package to the remote system,
* or whatever request is necessary to initiate the transfer.
*
* @return bool success
*/
public abstract function send_package();
/**
* Once everything is done and the user
* has the finish page displayed to them.
* The base class takes care of printing them
* "return to where you are" or "continue to portfolio" links.
* This function allows for exta finish options from the plugin
*
* @return bool
*/
public function get_extra_finish_options() {
return false;
}
/**
* The url for the user to continue to their portfolio
* during the lifecycle of the request
*/
public abstract function get_interactive_continue_url();
/**
* The url to save in the log as the continue url.
* This is passed through resolve_static_continue_url()
* at display time to the user.
*
* @return string
*/
public function get_static_continue_url() {
return $this->get_interactive_continue_url();
}
/**
* Override this function if you need to add something on to the url
* for post-export continues (eg from the log page).
* Mahara does this, for example, to start a jump session.
*
* @param string $url static continue url
* @return string
*/
public function resolve_static_continue_url($url) {
return $url;
}
/**
* mform to display to the user in their profile
* if your plugin can't be configured by the user,
* @see has_user_config.
* Don't bother overriding this function
*
* @param moodleform $mform passed by reference, add elements to it
*/
public function user_config_form(&$mform) {}
/**
* mform to display to the admin configuring the plugin.
* If your plugin can't be configured by the admin,
* @see has_admin_config
* Don't bother overriding this function.
* This function can be called statically or non statically,
* depending on whether it's creating a new instance (statically),
* or editing an existing one (non statically)
*
* @param moodleform $mform passed by reference, add elements to it.
*/
public static function admin_config_form(&$mform) {}
/**
* Just like the moodle form validation function,
* this is passed in the data array from the form
* and if a non empty array is returned, form processing will stop.
*
* @param array $data data from form.
*/
public static function admin_config_validation($data) {}
/**
* mform to display to the user exporting data using this plugin.
* If your plugin doesn't need user input at this time,
* @see has_export_config.
* Don't bother overrideing this function
*
* @param moodleform $mform passed by reference, add elements to it.
*/
public function export_config_form(&$mform) {}
/**
* Override this if your plugin doesn't allow multiple instances
*
* @return bool
*/
public static function allows_multiple_instances() {
return true;
}
/**
* If at any point the caller wants to steal control,
* it can, by returning something that isn't false
* in this function
* The controller will redirect to whatever url
* this function returns.
* Afterwards, you can redirect back to portfolio/add.php?postcontrol=1
* and post_control is called before the rest of the processing
* for the stage is done,
* @see post_control
*
* @param int $stage to steal control *before* (see constants PARAM_STAGE_*}
* @return bool
*/
public function steal_control($stage) {
return false;
}
/**
* After a plugin has elected to steal control,
* and control returns to portfolio/add.php|postcontrol=1,
* this function is called, and passed the stage that was stolen control from
* and the request (get and post but not cookie) parameters.
* This is useful for external systems that need to redirect the user back
* with some extra data in the url (like auth tokens etc)
* for an example implementation, see boxnet portfolio plugin.
*
* @param int $stage the stage before control was stolen
* @param array $params a merge of $_GET and $_POST
*/
public function post_control($stage, $params) { }
/**
* This function creates a new instance of a plugin
* saves it in the database, saves the config
* and returns it.
* You shouldn't need to override it
* unless you're doing something really funky
*
* @param string $plugin portfolio plugin to create
* @param string $name name of new instance
* @param array $config what the admin config form returned
* @return object subclass of portfolio_plugin_base
*/
public static function create_instance($plugin, $name, $config) {
global $DB, $CFG;
$new = (object)array(
'plugin' => $plugin,
'name' => $name,
);
if (!portfolio_static_function($plugin, 'allows_multiple_instances')) {
// check we don't have one already
if ($DB->record_exists('portfolio_instance', array('plugin' => $plugin))) {
throw new portfolio_exception('multipleinstancesdisallowed', 'portfolio', '', $plugin);
}
}
$newid = $DB->insert_record('portfolio_instance', $new);
require_once($CFG->dirroot . '/portfolio/' . $plugin . '/lib.php');
$classname = 'portfolio_plugin_' . $plugin;
$obj = new $classname($newid);
$obj->set_config($config);
$obj->save();
return $obj;
}
/**
* Construct a plugin instance.
* Subclasses should not need to override this unless they're doing something special
* and should call parent::__construct afterwards.
*
* @param int $instanceid id of plugin instance to construct
* @param mixed $record stdclass object or named array - use this if you already have the record to avoid another query
* @return portfolio_plugin_base
*/
public function __construct($instanceid, $record=null) {
global $DB;
if (!$record) {
if (!$record = $DB->get_record('portfolio_instance', array('id' => $instanceid))) {
throw new portfolio_exception('invalidinstance', 'portfolio');
}
}
foreach ((array)$record as $key =>$value) {
if (property_exists($this, $key)) {
$this->{$key} = $value;
}
}
$this->config = new StdClass;
$this->userconfig = array();
$this->exportconfig = array();
foreach ($DB->get_records('portfolio_instance_config', array('instance' => $instanceid)) as $config) {
$this->config->{$config->name} = $config->value;
}
$this->init();
return $this;
}
/**
* Called after __construct - allows plugins to perform initialisation tasks
* without having to override the constructor.
*/
protected function init() { }
/**
* A list of fields that can be configured per instance.
* This is used for the save handlers of the config form
* and as checks in set_config and get_config.
*
* @return array array of strings (config item names)
*/
public static function get_allowed_config() {
return array();
}
/**
* A list of fields that can be configured by the user.
* This is used for the save handlers in the config form
* and as checks in set_user_config and get_user_config.
*
* @return array array of strings (config field names)
*/
public function get_allowed_user_config() {
return array();
}
/**
* A list of fields that can be configured by the user.
* This is used for the save handlers in the config form
* and as checks in set_export_config and get_export_config.
*
* @return array array of strings (config field names)
*/
public function get_allowed_export_config() {
return array();
}
/**
* Saves (or updates) the config stored in portfolio_instance_config.
* You shouldn't need to override this unless you're doing something funky.
*
* @param array $config array of config items.
*/
public final function set_config($config) {
global $DB;
foreach ($config as $key => $value) {
// try set it in $this first
try {
$this->set($key, $value);
continue;
} catch (portfolio_exception $e) { }
if (!in_array($key, $this->get_allowed_config())) {
$a = (object)array('property' => $key, 'class' => get_class($this));
throw new portfolio_export_exception($this->get('exporter'), 'invalidconfigproperty', 'portfolio', null, $a);
}
if (!isset($this->config->{$key})) {
$DB->insert_record('portfolio_instance_config', (object)array(
'instance' => $this->id,
'name' => $key,
'value' => $value,
));
} else if ($this->config->{$key} != $value) {
$DB->set_field('portfolio_instance_config', 'value', $value, array('name' => $key, 'instance' => $this->id));
}
$this->config->{$key} = $value;
}
}
/**
* Gets the value of a particular config item
*
* @param string $key key to fetch
* @return null|mixed the corresponding value
*/
public final function get_config($key) {
if (!in_array($key, $this->get_allowed_config())) {
$a = (object)array('property' => $key, 'class' => get_class($this));
throw new portfolio_export_exception($this->get('exporter'), 'invalidconfigproperty', 'portfolio', null, $a);
}
if (isset($this->config->{$key})) {
return $this->config->{$key};
}
return null;
}
/**
* Get the value of a config item for a particular user.
*
* @param string $key key to fetch
* @param int $userid id of user (defaults to current)
* @return string the corresponding value
*
*/
public final function get_user_config($key, $userid=0) {
global $DB;
if (empty($userid)) {
$userid = $this->user->id;
}
if ($key != 'visible') { // handled by the parent class
if (!in_array($key, $this->get_allowed_user_config())) {
$a = (object)array('property' => $key, 'class' => get_class($this));
throw new portfolio_export_exception($this->get('exporter'), 'invaliduserproperty', 'portfolio', null, $a);
}
}
if (!array_key_exists($userid, $this->userconfig)) {
$this->userconfig[$userid] = (object)array_fill_keys(array_merge(array('visible'), $this->get_allowed_user_config()), null);
foreach ($DB->get_records('portfolio_instance_user', array('instance' => $this->id, 'userid' => $userid)) as $config) {
$this->userconfig[$userid]->{$config->name} = $config->value;
}
}
if ($this->userconfig[$userid]->visible === null) {
$this->set_user_config(array('visible' => 1), $userid);
}
return $this->userconfig[$userid]->{$key};
}
/**
* Sets config options for a given user.
*
* @param array $config array containing key/value pairs to set
* @param int $userid userid to set config for (defaults to current)
*
*/
public final function set_user_config($config, $userid=0) {
global $DB;
if (empty($userid)) {
$userid = $this->user->id;
}
foreach ($config as $key => $value) {
if ($key != 'visible' && !in_array($key, $this->get_allowed_user_config())) {
$a = (object)array('property' => $key, 'class' => get_class($this));
throw new portfolio_export_exception($this->get('exporter'), 'invaliduserproperty', 'portfolio', null, $a);
}
if (!$existing = $DB->get_record('portfolio_instance_user', array('instance'=> $this->id, 'userid' => $userid, 'name' => $key))) {
$DB->insert_record('portfolio_instance_user', (object)array(
'instance' => $this->id,
'name' => $key,
'value' => $value,
'userid' => $userid,
));
} else if ($existing->value != $value) {
$DB->set_field('portfolio_instance_user', 'value', $value, array('name' => $key, 'instance' => $this->id, 'userid' => $userid));
}
$this->userconfig[$userid]->{$key} = $value;
}
}
/**
* Generic getter for properties belonging to this instance
* <b>outside</b> the subclasses
* like name, visible etc.
*
* @param string $field property name
* @return array|string|int|boolean value of the field
*/
public final function get($field) {
// This is a legacy change to the way files are get/set.
// We now only set $this->file to the id of the \stored_file. So, we need to convert that id back to a \stored_file here.
if ($field === 'file') {
return $this->get_file();
}
if (property_exists($this, $field)) {
return $this->{$field};
}
$a = (object)array('property' => $field, 'class' => get_class($this));
throw new portfolio_export_exception($this->get('exporter'), 'invalidproperty', 'portfolio', null, $a);
}
/**
* Generic setter for properties belonging to this instance
* <b>outside</b> the subclass
* like name, visible, etc.
*
* @param string $field property's name
* @param string $value property's value
* @return bool
*/
public final function set($field, $value) {
// This is a legacy change to the way files are get/set.
// Make sure we never save the \stored_file object. Instead, use the id from $file->get_id() - set_file() does this for us.
if ($field === 'file') {
$this->set_file($value);
return true;
}
if (property_exists($this, $field)) {
$this->{$field} =& $value;
$this->dirty = true;
return true;
}
$a = (object)array('property' => $field, 'class' => get_class($this));
if ($this->get('exporter')) {
throw new portfolio_export_exception($this->get('exporter'), 'invalidproperty', 'portfolio', null, $a);
}
throw new portfolio_exception('invalidproperty', 'portfolio', null, $a); // this happens outside export (eg admin settings)
}
/**
* Saves stuff that's been stored in the object to the database.
* You shouldn't need to override this
* unless you're doing something really funky.
* and if so, call parent::save when you're done.
*
* @return bool
*/
public function save() {
global $DB;
if (!$this->dirty) {
return true;
}
$fordb = new StdClass();
foreach (array('id', 'name', 'plugin', 'visible') as $field) {
$fordb->{$field} = $this->{$field};
}
$DB->update_record('portfolio_instance', $fordb);
$this->dirty = false;
return true;
}
/**
* Deletes everything from the database about this plugin instance.
* You shouldn't need to override this unless you're storing stuff
* in your own tables. and if so, call parent::delete when you're done.
*
* @return bool
*/
public function delete() {
global $DB;
$DB->delete_records('portfolio_instance_config', array('instance' => $this->get('id')));
$DB->delete_records('portfolio_instance_user', array('instance' => $this->get('id')));
$DB->delete_records('portfolio_tempdata', array('instance' => $this->get('id')));
$DB->delete_records('portfolio_instance', array('id' => $this->get('id')));
$this->dirty = false;
return true;
}
/**
* Perform any required cleanup functions
*
* @return bool
*/
public function cleanup() {
return true;
}
/**
* Whether this plugin supports multiple exports in the same session
* most plugins should handle this, but some that require a redirect for authentication
* and then don't support dynamically constructed urls to return to (eg box.net)
* need to override this to return false.
* This means that moodle will prevent multiple exports of this *type* of plugin
* occurring in the same session.
*
* @return bool
*/
public static function allows_multiple_exports() {
return true;
}
/**
* Return a string to put at the header summarising this export
* by default, just the plugin instance name
*
* @return string
*/
public function heading_summary() {
return get_string('exportingcontentto', 'portfolio', $this->name);
}
}
/**
* Class to inherit from for 'push' type plugins
*
* Eg: those that send the file via a HTTP post or whatever
*
* @package core_portfolio
* @category portfolio
* @copyright 2008 Penny Leach <penny@catalyst.net.nz>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class portfolio_plugin_push_base extends portfolio_plugin_base {
/**
* Get the capability to push
*
* @return bool
*/
public function is_push() {
return true;
}
}
/**
* Class to inherit from for 'pull' type plugins.
*
* Eg: those that write a file and wait for the remote system to request it
* from portfolio/file.php.
* If you're using this you must do $this->set('file', $file) so that it can be served.
*
* @package core_portfolio
* @category portfolio
* @copyright 2008 Penny Leach <penny@catalyst.net.nz>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class portfolio_plugin_pull_base extends portfolio_plugin_base {
/** @var int $file the id of a single file */
protected $file;
/**
* return the enablelity to push
*
* @return bool
*/
public function is_push() {
return false;
}
/**
* The base part of the download file url to pull files from
* your plugin might need to add &foo=bar on the end
* @see verify_file_request_params
*
* @return string the url
*/
public function get_base_file_url() {
global $CFG;
return $CFG->wwwroot . '/portfolio/file.php?id=' . $this->exporter->get('id');
}
/**
* Before sending the file when the pull is requested, verify the request parameters.
* These might include a token of some sort of whatever
*
* @param array $params request parameters (POST wins over GET)
*/
public abstract function verify_file_request_params($params);
/**
* Called from portfolio/file.php.
* This function sends the stored file out to the browser.
* The default is to just use send_stored_file,
* but other implementations might do something different,
* for example, send back the file base64 encoded and encrypted
* mahara does this but in the response to an xmlrpc request
* rather than through file.php
*/
public function send_file() {
$file = $this->get('file');
if (!($file instanceof stored_file)) {
throw new portfolio_export_exception($this->get('exporter'), 'filenotfound', 'portfolio');
}
// don't die(); afterwards, so we can clean up.
send_stored_file($file, 0, 0, true, array('dontdie' => true));
$this->get('exporter')->log_transfer();
}
/**
* Sets the $file instance var to the id of the supplied \stored_file.
* This helper allows the $this->get('file') call to return a \stored_file, but means that we only ever record an id reference
* in the $file instance var.
*
* @param \stored_file $file The stored_file instance.
* @return void
*/
protected function set_file(\stored_file $file) {
$fileid = $file->get_id();
if (empty($fileid)) {
debugging('stored_file->id should not be empty');
$this->file = null;
} else {
$this->file = $fileid;
}
}
/**
* Gets the \stored_file object from the file id in the $file instance var.
*
* @return stored_file|null the \stored_file object if it exists, null otherwise.
*/
protected function get_file() {
if (!$this->file) {
return null;
}
// The get_file_by_id call can return false, so normalise to null.
$file = get_file_storage()->get_file_by_id($this->file);
return ($file) ? $file : null;
}
}