lib/portfolio/plugin.php

   1 <?php
   2 /**
   3  * Moodle - Modular Object-Oriented Dynamic Learning Environment
   4  *          http://moodle.org
   5  * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
   6  *
   7  * This program is free software: you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation, either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * @package    core
  21  * @subpackage portfolio
  22  * @author     Penny Leach <penny@catalyst.net.nz>
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
  24  * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
  25  *
  26  * This file contains the base classes for portfolio plugins to inherit from:
  27  * portfolio_plugin_pull_base and portfolio_plugin_push_base
  28  * which both in turn inherit from portfolio_plugin_base.
  29  * See http://docs.moodle.org/en/Development:Writing_a_Portfolio_Plugin
  30  */
  31
  32 defined('MOODLE_INTERNAL') || die();
  33
  34 /**
  35 * the base class for portfolio plugins
  36 * all plugins must subclass this
  37 * either via {@see portfolio_plugin_pull_base} or {@see portfolio_plugin_push_base}
  38 */
  39 abstract class portfolio_plugin_base {
  40
  41     /**
  42     * whether this object needs writing out to the database
  43     * @var boolean $dirty
  44     */
  45     protected $dirty;
  46
  47     /**
  48     * id of instance
  49     * @var integer $id
  50     */
  51     protected $id;
  52
  53     /**
  54     * name of instance
  55     * @var string $name
  56     */
  57     protected $name;
  58
  59     /**
  60     * plugin this instance belongs to
  61     * @var string $plugin
  62     */
  63     protected $plugin;
  64
  65     /**
  66     * whether this instance is visible or not
  67     * @var boolean $visible
  68     */
  69     protected $visible;
  70
  71     /**
  72     * named array
  73     * admin configured config
  74     * use {@link set_config} and {@get_config} to access
  75     */
  76     protected $config;
  77
  78     /**
  79     *
  80     * user config cache
  81     * named array of named arrays
  82     * keyed on userid and then on config field => value
  83     * use {@link get_user_config} and {@link set_user_config} to access.
  84     */
  85     protected $userconfig;
  86
  87     /**
  88     * named array
  89     * export config during export
  90     * use {@link get_export_config} and {@link set export_config} to access.
  91     */
  92     protected $exportconfig;
  93
  94     /**
  95     * stdclass object
  96     * user currently exporting data
  97     */
  98     protected $user;
  99
 100     /**
 101     * a reference to the exporter object
 102     */
 103     protected $exporter;
 104
 105     /**
 106     * array of formats this portfolio supports
 107     * the intersection of what this function returns
 108     * and what the caller supports will be used
 109     * use the constants PORTFOLIO_FORMAT_*
 110     *
 111     * @return array list of formats
 112     */
 113     public function supported_formats() {
 114         return array(PORTFOLIO_FORMAT_FILE, PORTFOLIO_FORMAT_RICH);
 115     }
 116
 117     /**
 118     * override this if you are supporting the 'file' type (or a subformat)
 119     * but have restrictions on mimetypes
 120     *
 121     * @return boolean
 122     */
 123     public static function file_mime_check($mimetype) {
 124         return true;
 125     }
 126
 127
 128     /**
 129     * how long does this reasonably expect to take..
 130     * should we offer the user the option to wait..
 131     * this is deliberately nonstatic so it can take filesize into account
 132     *
 133     * @param string $callertime - what the caller thinks
 134     *                             the portfolio plugin instance
 135     *                             is given the final say
 136     *                             because it might be (for example) download.
 137     * @return string (see PORTFOLIO_TIME_* constants)
 138     */
 139     public abstract function expected_time($callertime);
 140
 141     /**
 142     * is this plugin push or pill.
 143     * if push, cleanup will be called directly after send_package
 144     * if not, cleanup will be called after portfolio/file.php is requested
 145     *
 146     * @return boolean
 147     */
 148     public abstract function is_push();
 149
 150     /**
 151      * returns the user-friendly name for this plugin
 152      * usually just get_string('pluginname', 'portfolio_something')
 153      *
 154      * @return string
 155      */
 156     public static function get_name() {
 157         throw new coding_exception('get_name() method needs to be overridden in each subclass of portfolio_plugin_base');
 158     }
 159
 160     /**
 161     * check sanity of plugin
 162     * if this function returns something non empty, ALL instances of your plugin
 163     * will be set to invisble and not be able to be set back until it's fixed
 164     *
 165     * @return mixed - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
 166     */
 167     public static function plugin_sanity_check() {
 168         return 0;
 169     }
 170
 171     /**
 172     * check sanity of instances
 173     * if this function returns something non empty, the instance will be
 174     * set to invislbe and not be able to be set back until it's fixed.
 175     *
 176     * @return mixed - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
 177     */
 178     public function instance_sanity_check() {
 179         return 0;
 180     }
 181
 182     /**
 183     * does this plugin need any configuration by the administrator?
 184     *
 185     * if you override this to return true,
 186     * you <b>must</b> implement {@see admin_config_form}
 187     */
 188     public static function has_admin_config() {
 189         return false;
 190     }
 191
 192     /**
 193     * can this plugin be configured by the user in their profile?
 194     *
 195     * if you override this to return true,
 196     * you <b>must</b> implement {@see user_config_form}
 197     */
 198     public function has_user_config() {
 199         return false;
 200     }
 201
 202     /**
 203     * does this plugin need configuration during export time?
 204     *
 205     * if you override this to return true,
 206     * you <b>must</b> implement {@see export_config_form}
 207     */
 208     public function has_export_config() {
 209         return false;
 210     }
 211
 212     /**
 213     * just like the moodle form validation function
 214     * this is passed in the data array from the form
 215     * and if a non empty array is returned, form processing will stop.
 216     *
 217     * @param array $data data from form.
 218     * @return array keyvalue pairs - form element => error string
 219     */
 220     public function export_config_validation(array $data) {}
 221
 222     /**
 223     * just like the moodle form validation function
 224     * this is passed in the data array from the form
 225     * and if a non empty array is returned, form processing will stop.
 226     *
 227     * @param array $data data from form.
 228     * @return array keyvalue pairs - form element => error string
 229     */
 230     public function user_config_validation(array $data) {}
 231
 232     /**
 233     * sets the export time config from the moodle form.
 234     * you can also use this to set export config that
 235     * isn't actually controlled by the user
 236     * eg things that your subclasses want to keep in state
 237     * across the export.
 238     * keys must be in {@see get_allowed_export_config}
 239     *
 240     * this is deliberately not final (see boxnet plugin)
 241     *
 242     * @param array $config named array of config items to set.
 243     */
 244     public function set_export_config($config) {
 245         $allowed = array_merge(
 246             array('wait', 'hidewait', 'format', 'hideformat'),
 247             $this->get_allowed_export_config()
 248         );
 249         foreach ($config as $key => $value) {
 250             if (!in_array($key, $allowed)) {
 251                 $a = (object)array('property' => $key, 'class' => get_class($this));
 252                 throw new portfolio_export_exception($this->get('exporter'), 'invalidexportproperty', 'portfolio', null, $a);
 253             }
 254             $this->exportconfig[$key] = $value;
 255         }
 256     }
 257
 258     /**
 259     * gets an export time config value.
 260     * subclasses should not override this.
 261     *
 262     * @param string key field to fetch
 263     *
 264     * @return string config value
 265     *
 266     */
 267     public final function get_export_config($key) {
 268         $allowed = array_merge(
 269             array('hidewait', 'wait', 'format', 'hideformat'),
 270             $this->get_allowed_export_config()
 271         );
 272         if (!in_array($key, $allowed)) {
 273             $a = (object)array('property' => $key, 'class' => get_class($this));
 274             throw new portfolio_export_exception($this->get('exporter'), 'invalidexportproperty', 'portfolio', null, $a);
 275         }
 276         if (!array_key_exists($key, $this->exportconfig)) {
 277             return null;
 278         }
 279         return $this->exportconfig[$key];
 280     }
 281
 282     /**
 283     * after the user submits their config
 284     * they're given a confirm screen
 285     * summarising what they've chosen.
 286     *
 287     * this function should return a table of nice strings => values
 288     * of what they've chosen
 289     * to be displayed in a table.
 290     *
 291     * @return array array of config items.
 292     */
 293     public function get_export_summary() {
 294         return false;
 295     }
 296
 297     /**
 298     * called after the caller has finished having control
 299     * of its prepare_package function.
 300     * this function should read all the files from the portfolio
 301     * working file area and zip them and send them or whatever it wants.
 302     * {@see get_tempfiles} to get the list of files.
 303     *
 304     */
 305     public abstract function prepare_package();
 306
 307     /**
 308     * this is the function that is responsible for sending
 309     * the package to the remote system,
 310     * or whatever request is necessary to initiate the transfer.
 311     *
 312     * @return boolean success
 313     */
 314     public abstract function send_package();
 315
 316
 317     /**
 318     * once everything is done and the user
 319     * has the finish page displayed to them
 320     * the base class takes care of printing them
 321     * "return to where you are" or "continue to portfolio" links
 322     * this function allows for exta finish options from the plugin
 323     *
 324     * @return array named array of links => titles
 325     */
 326     public function get_extra_finish_options() {
 327         return false;
 328     }
 329
 330     /**
 331     * the url for the user to continue to their portfolio
 332     * during the lifecycle of the request
 333     *
 334     * @return string url or false.
 335     */
 336     public abstract function get_interactive_continue_url();
 337
 338     /**
 339      * the url to save in the log as the continue url
 340      * this is passed through resolve_static_continue_url()
 341      * at display time to the user.
 342      */
 343     public function get_static_continue_url() {
 344         return $this->get_interactive_continue_url();
 345     }
 346
 347     /**
 348      * override this function if you need to add something on to the url
 349      * for post-export continues (eg from the log page)
 350      * mahara does this, for example, to start a jump session
 351      */
 352     public function resolve_static_continue_url($url) {
 353         return $url;
 354     }
 355
 356     /**
 357     * mform to display to the user in their profile
 358     * if your plugin can't be configured by the user,
 359     * (see {@link has_user_config})
 360     * don't bother overriding this function
 361     *
 362     * @param moodleform $mform passed by reference, add elements to it
 363     */
 364     public function user_config_form(&$mform) {}
 365
 366     /**
 367     * mform to display to the admin configuring the plugin.
 368     * if your plugin can't be configured by the admin,
 369     * (see {@link} has_admin_config)
 370     * don't bother overriding this function
 371     *
 372     * this function can be called statically or non statically,
 373     * depending on whether it's creating a new instance (statically),
 374     * or editing an existing one (non statically)
 375     *
 376     * @param moodleform $mform passed by reference, add elements to it.
 377     */
 378     public function admin_config_form(&$mform) {}
 379
 380     /**
 381     * just like the moodle form validation function
 382     * this is passed in the data array from the form
 383     * and if a non empty array is returned, form processing will stop.
 384     *
 385     * @param array $data data from form.
 386     * @return array keyvalue pairs - form element => error string
 387     */
 388     public function admin_config_validation($data) {}
 389     /**
 390     * mform to display to the user exporting data using this plugin.
 391     * if your plugin doesn't need user input at this time,
 392     * (see {@link has_export_config}
 393     * don't bother overrideing this function
 394     *
 395     * @param moodleform $mform passed by reference, add elements to it.
 396     */
 397     public function export_config_form(&$mform) {}
 398
 399     /**
 400     * override this if your plugin doesn't allow multiple instances
 401     *
 402     * @return boolean
 403     */
 404     public static function allows_multiple_instances() {
 405         return true;
 406     }
 407
 408     /**
 409     *
 410     * If at any point the caller wants to steal control
 411     * it can, by returning something that isn't false
 412     * in this function
 413     * The controller will redirect to whatever url
 414     * this function returns.
 415     * Afterwards, you can redirect back to portfolio/add.php?postcontrol=1
 416     * and {@link post_control} is called before the rest of the processing
 417     * for the stage is done
 418     *
 419     * @param int stage to steal control *before* (see constants PARAM_STAGE_*}
 420     *
 421     * @return boolean or string url
 422     */
 423     public function steal_control($stage) {
 424         return false;
 425     }
 426
 427     /**
 428     * after a plugin has elected to steal control,
 429     * and control returns to portfolio/add.php|postcontrol=1,
 430     * this function is called, and passed the stage that was stolen control from
 431     * and the request (get and post but not cookie) parameters
 432     * this is useful for external systems that need to redirect the user back
 433     * with some extra data in the url (like auth tokens etc)
 434     * for an example implementation, see boxnet portfolio plugin.
 435     *
 436     * @param int $stage the stage before control was stolen
 437     * @param array $params a merge of $_GET and $_POST
 438     *
 439     */
 440
 441     public function post_control($stage, $params) { }
 442
 443     /**
 444     * this function creates a new instance of a plugin
 445     * saves it in the database, saves the config
 446     * and returns it.
 447     * you shouldn't need to override it
 448     * unless you're doing something really funky
 449     *
 450     * @param string $plugin portfolio plugin to create
 451     * @param string $name name of new instance
 452     * @param array $config what the admin config form returned
 453     *
 454     * @return object subclass of portfolio_plugin_base
 455     */
 456     public static function create_instance($plugin, $name, $config) {
 457         global $DB, $CFG;
 458         $new = (object)array(
 459             'plugin' => $plugin,
 460             'name'   => $name,
 461         );
 462         if (!portfolio_static_function($plugin, 'allows_multiple_instances')) {
 463             // check we don't have one already
 464             if ($DB->record_exists('portfolio_instance', array('plugin' => $plugin))) {
 465                 throw new portfolio_exception('multipleinstancesdisallowed', 'portfolio', '', $plugin);
 466             }
 467         }
 468         $newid = $DB->insert_record('portfolio_instance', $new);
 469         require_once($CFG->dirroot . '/portfolio/' . $plugin . '/lib.php');
 470         $classname = 'portfolio_plugin_'  . $plugin;
 471         $obj = new $classname($newid);
 472         $obj->set_config($config);
 473         $obj->save();
 474         return $obj;
 475     }
 476
 477     /**
 478     * construct a plugin instance
 479     * subclasses should not need  to override this unless they're doing something special
 480     * and should call parent::__construct afterwards
 481     *
 482     * @param int $instanceid id of plugin instance to construct
 483     * @param mixed $record stdclass object or named array - use this i you already have the record to avoid another query
 484     *
 485     * @return object subclass of portfolio_plugin_base
 486     */
 487     public function __construct($instanceid, $record=null) {
 488         global $DB;
 489         if (!$record) {
 490             if (!$record = $DB->get_record('portfolio_instance', array('id' => $instanceid))) {
 491                 throw new portfolio_exception('invalidinstance', 'portfolio');
 492             }
 493         }
 494         foreach ((array)$record as $key =>$value) {
 495             if (property_exists($this, $key)) {
 496                 $this->{$key} = $value;
 497             }
 498         }
 499         $this->config = new StdClass;
 500         $this->userconfig = array();
 501         $this->exportconfig = array();
 502         foreach ($DB->get_records('portfolio_instance_config', array('instance' => $instanceid)) as $config) {
 503             $this->config->{$config->name} = $config->value;
 504         }
 505         $this->init();
 506         return $this;
 507     }
 508
 509     /**
 510      * called after __construct - allows plugins to perform initialisation tasks
 511      * without having to override the constructor.
 512      */
 513     protected function init() { }
 514
 515     /**
 516     * a list of fields that can be configured per instance.
 517     * this is used for the save handlers of the config form
 518     * and as checks in set_config and get_config
 519     *
 520     * @return array array of strings (config item names)
 521     */
 522     public static function get_allowed_config() {
 523         return array();
 524     }
 525
 526     /**
 527     * a list of fields that can be configured by the user.
 528     * this is used for the save handlers in the config form
 529     * and as checks in set_user_config and get_user_config.
 530     *
 531     * @return array array of strings (config field names)
 532     */
 533     public function get_allowed_user_config() {
 534         return array();
 535     }
 536
 537     /**
 538     * a list of fields that can be configured by the user.
 539     * this is used for the save handlers in the config form
 540     * and as checks in set_export_config and get_export_config.
 541     *
 542     * @return array array of strings (config field names)
 543     */
 544     public function get_allowed_export_config() {
 545         return array();
 546     }
 547
 548     /**
 549     * saves (or updates) the config stored in portfolio_instance_config.
 550     * you shouldn't need to override this unless you're doing something funky.
 551     *
 552     * @param array $config array of config items.
 553     */
 554     public final function set_config($config) {
 555         global $DB;
 556         foreach ($config as $key => $value) {
 557             // try set it in $this first
 558             try {
 559                 $this->set($key, $value);
 560                 continue;
 561             } catch (portfolio_exception $e) { }
 562             if (!in_array($key, $this->get_allowed_config())) {
 563                 $a = (object)array('property' => $key, 'class' => get_class($this));
 564                 throw new portfolio_export_exception($this->get('exporter'), 'invalidconfigproperty', 'portfolio', null, $a);
 565             }
 566             if (!isset($this->config->{$key})) {
 567                 $DB->insert_record('portfolio_instance_config', (object)array(
 568                     'instance' => $this->id,
 569                     'name' => $key,
 570                     'value' => $value,
 571                 ));
 572             } else if ($this->config->{$key} != $value) {
 573                 $DB->set_field('portfolio_instance_config', 'value', $value, array('name' => $key, 'instance' => $this->id));
 574             }
 575             $this->config->{$key} = $value;
 576         }
 577     }
 578
 579     /**
 580     * gets the value of a particular config item
 581     *
 582     * @param string $key key to fetch
 583     *
 584     * @return string the corresponding value
 585     */
 586     public final function get_config($key) {
 587         if (!in_array($key, $this->get_allowed_config())) {
 588             $a = (object)array('property' => $key, 'class' => get_class($this));
 589             throw new portfolio_export_exception($this->get('exporter'), 'invalidconfigproperty', 'portfolio', null, $a);
 590         }
 591         if (isset($this->config->{$key})) {
 592             return $this->config->{$key};
 593         }
 594         return null;
 595     }
 596
 597     /**
 598     * get the value of a config item for a particular user
 599     *
 600     * @param string $key key to fetch
 601     * @param integer $userid id of user (defaults to current)
 602     *
 603     * @return string the corresponding value
 604     *
 605     */
 606     public final function get_user_config($key, $userid=0) {
 607         global $DB;
 608
 609         if (empty($userid)) {
 610             $userid = $this->user->id;
 611         }
 612
 613         if ($key != 'visible') { // handled by the parent class
 614             if (!in_array($key, $this->get_allowed_user_config())) {
 615                 $a = (object)array('property' => $key, 'class' => get_class($this));
 616                 throw new portfolio_export_exception($this->get('exporter'), 'invaliduserproperty', 'portfolio', null, $a);
 617             }
 618         }
 619         if (!array_key_exists($userid, $this->userconfig)) {
 620             $this->userconfig[$userid] = (object)array_fill_keys(array_merge(array('visible'), $this->get_allowed_user_config()), null);
 621             foreach ($DB->get_records('portfolio_instance_user', array('instance' => $this->id, 'userid' => $userid)) as $config) {
 622                 $this->userconfig[$userid]->{$config->name} = $config->value;
 623             }
 624         }
 625         if ($this->userconfig[$userid]->visible === null) {
 626             $this->set_user_config(array('visible' => 1), $userid);
 627         }
 628         return $this->userconfig[$userid]->{$key};
 629
 630     }
 631
 632     /**
 633     *
 634     * sets config options for a given user
 635     *
 636     * @param mixed $config array or stdclass containing key/value pairs to set
 637     * @param integer $userid userid to set config for (defaults to current)
 638     *
 639     */
 640     public final function set_user_config($config, $userid=0) {
 641         global $DB;
 642
 643         if (empty($userid)) {
 644             $userid = $this->user->id;
 645         }
 646
 647         foreach ($config as $key => $value) {
 648             if ($key != 'visible' && !in_array($key, $this->get_allowed_user_config())) {
 649                 $a = (object)array('property' => $key, 'class' => get_class($this));
 650                 throw new portfolio_export_exception($this->get('exporter'), 'invaliduserproperty', 'portfolio', null, $a);
 651             }
 652             if (!$existing = $DB->get_record('portfolio_instance_user', array('instance'=> $this->id, 'userid' => $userid, 'name' => $key))) {
 653                 $DB->insert_record('portfolio_instance_user', (object)array(
 654                     'instance' => $this->id,
 655                     'name' => $key,
 656                     'value' => $value,
 657                     'userid' => $userid,
 658                 ));
 659             } else if ($existing->value != $value) {
 660                 $DB->set_field('portfolio_instance_user', 'value', $value, array('name' => $key, 'instance' => $this->id, 'userid' => $userid));
 661             }
 662             $this->userconfig[$userid]->{$key} = $value;
 663         }
 664
 665     }
 666
 667     /**
 668     * generic getter for properties belonging to this instance
 669     * <b>outside</b> the subclasses
 670     * like name, visible etc.
 671     *
 672     */
 673     public final function get($field) {
 674         if (property_exists($this, $field)) {
 675             return $this->{$field};
 676         }
 677         $a = (object)array('property' => $field, 'class' => get_class($this));
 678         throw new portfolio_export_exception($this->get('exporter'), 'invalidproperty', 'portfolio', null, $a);
 679     }
 680
 681     /**
 682     * generic setter for properties belonging to this instance
 683     * <b>outside</b> the subclass
 684     * like name, visible, etc.
 685     *
 686     */
 687     public final function set($field, $value) {
 688         if (property_exists($this, $field)) {
 689             $this->{$field} =& $value;
 690             $this->dirty = true;
 691             return true;
 692         }
 693         $a = (object)array('property' => $field, 'class' => get_class($this));
 694         if ($this->get('exporter')) {
 695             throw new portfolio_export_exception($this->get('exporter'), 'invalidproperty', 'portfolio', null, $a);
 696         }
 697         throw new portfolio_exception('invalidproperty', 'portfolio', null, $a); // this happens outside export (eg admin settings)
 698
 699     }
 700
 701     /**
 702     * saves stuff that's been stored in the object to the database
 703     * you shouldn't need to override this
 704     * unless you're doing something really funky.
 705     * and if so, call parent::save when you're done.
 706     */
 707     public function save() {
 708         global $DB;
 709         if (!$this->dirty) {
 710             return true;
 711         }
 712         $fordb = new StdClass();
 713         foreach (array('id', 'name', 'plugin', 'visible') as $field) {
 714             $fordb->{$field} = $this->{$field};
 715         }
 716         $DB->update_record('portfolio_instance', $fordb);
 717         $this->dirty = false;
 718         return true;
 719     }
 720
 721     /**
 722     * deletes everything from the database about this plugin instance.
 723     * you shouldn't need to override this unless you're storing stuff
 724     * in your own tables.  and if so, call parent::delete when you're done.
 725     */
 726     public function delete() {
 727         global $DB;
 728         $DB->delete_records('portfolio_instance_config', array('instance' => $this->get('id')));
 729         $DB->delete_records('portfolio_instance_user', array('instance' => $this->get('id')));
 730         $DB->delete_records('portfolio_tempdata', array('instance' => $this->get('id')));
 731         $DB->delete_records('portfolio_instance', array('id' => $this->get('id')));
 732         $this->dirty = false;
 733         return true;
 734     }
 735
 736     /**
 737     * perform any required cleanup functions
 738     */
 739     public function cleanup() {
 740         return true;
 741     }
 742
 743     /**
 744      * whether this plugin supports multiple exports in the same session
 745      * most plugins should handle this, but some that require a redirect for authentication
 746      * and then don't support dynamically constructed urls to return to (eg box.net)
 747      * need to override this to return false.
 748      * this means that moodle will prevent multiple exports of this *type* of plugin
 749      * occurring in the same session.
 750      *
 751      * @return boolean
 752      */
 753     public static function allows_multiple_exports() {
 754         return true;
 755     }
 756
 757     /**
 758     * return a string to put at the header summarising this export
 759     * by default, just the plugin instance name
 760     *
 761     * @return string
 762     */
 763     public function heading_summary() {
 764         return get_string('exportingcontentto', 'portfolio', $this->name);
 765     }
 766 }
 767
 768 /**
 769 * class to inherit from for 'push' type plugins
 770 * eg those that send the file via a HTTP post or whatever
 771 */
 772 abstract class portfolio_plugin_push_base extends portfolio_plugin_base {
 773
 774     public function is_push() {
 775         return true;
 776     }
 777 }
 778
 779 /**
 780 * class to inherit from for 'pull' type plugins
 781 * eg those that write a file and wait for the remote system to request it
 782 * from portfolio/file.php
 783 * if you're using this you must do $this->set('file', $file) so that it can be served.
 784 */
 785 abstract class portfolio_plugin_pull_base extends portfolio_plugin_base {
 786
 787     protected $file;
 788
 789     public function is_push() {
 790         return false;
 791     }
 792
 793     /**
 794     * the base part of the download file url to pull files from
 795     * your plugin might need to add &foo=bar on the end
 796     * {@see verify_file_request_params}
 797     *
 798     * @return string the url
 799     */
 800     public function get_base_file_url() {
 801         global $CFG;
 802         return $CFG->wwwroot . '/portfolio/file.php?id=' . $this->exporter->get('id');
 803     }
 804
 805     /**
 806     * before sending the file when the pull is requested, verify the request parameters
 807     * these might include a token of some sort of whatever
 808     *
 809     * @param array request parameters (POST wins over GET)
 810     */
 811     public abstract function verify_file_request_params($params);
 812
 813     /**
 814     * called from portfolio/file.php
 815     * this function sends the stored file out to the browser
 816     * the default is to just use send_stored_file,
 817     * but other implementations might do something different
 818     * for example, send back the file base64 encoded and encrypted
 819     * mahara does this but in the response to an xmlrpc request
 820     * rather than through file.php
 821     */
 822     public function send_file() {
 823         $file = $this->get('file');
 824         if (!($file instanceof stored_file)) {
 825             throw new portfolio_export_exception($this->get('exporter'), 'filenotfound', 'portfolio');
 826         }
 827         // the last 'true' on the end of this means don't die(); afterwards, so we can clean up.
 828         send_stored_file($file, 0, 0, true, null, true);
 829         $this->get('exporter')->log_transfer();
 830     }
 831
 832 }