[Summary view] [Print] [Text view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * This file contains all global functions to do with manipulating portfolios.
  19   *
  20   * Everything else that is logically namespaced by class is in its own file
  21   * in lib/portfolio/ directory.
  22   *
  23   * Major Contributors
  24   *     - Penny Leach <penny@catalyst.net.nz>
  25   *
  26   * @package core_portfolio
  27   * @category portfolio
  28   * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  29   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  30   */
  31  
  32  defined('MOODLE_INTERNAL') || die();
  33  
  34  // require some of the sublibraries first.
  35  // this is not an exhaustive list, the others are pulled in as they're needed
  36  // so we don't have to always include everything unnecessarily for performance
  37  
  38  // very lightweight list of constants. always needed and no further dependencies
  39  require_once($CFG->libdir . '/portfolio/constants.php');
  40  // a couple of exception deinitions. always needed and no further dependencies
  41  require_once($CFG->libdir . '/portfolio/exceptions.php');  // exception classes used by portfolio code
  42  // The base class for the caller classes. We always need this because we're either drawing a button,
  43  // in which case the button needs to know the calling class definition, which requires the base class,
  44  // or we're exporting, in which case we need the caller class anyway.
  45  require_once($CFG->libdir . '/portfolio/caller.php');
  46  
  47  // the other dependencies are included on demand:
  48  // libdir/portfolio/formats.php  - the classes for the export formats
  49  // libdir/portfolio/forms.php    - all portfolio form classes (requires formslib)
  50  // libdir/portfolio/plugin.php   - the base class for the export plugins
  51  // libdir/portfolio/exporter.php - the exporter class
  52  
  53  
  54  /**
  55   * Use this to add a portfolio button or icon or form to a page.
  56   *
  57   * These class methods do not check permissions. the caller must check permissions first.
  58   * Later, during the export process, the caller class is instantiated and the check_permissions method is called
  59   * If you are exporting a single file, you should always call set_format_by_file($file)
  60   * This class can be used like this:
  61   * <code>
  62   * $button = new portfolio_add_button();
  63   * $button->set_callback_options('name_of_caller_class', array('id' => 6), 'yourcomponent'); eg. mod_forum
  64   * $button->render(PORTFOLIO_ADD_FULL_FORM, get_string('addeverythingtoportfolio', 'yourcomponent'));
  65   * </code>
  66   * or like this:
  67   * <code>
  68   * $button = new portfolio_add_button(array('callbackclass' => 'name_of_caller_class', 'callbackargs' => array('id' => 6), 'callbackcomponent' => 'yourcomponent')); eg. mod_forum
  69   * $somehtml .= $button->to_html(PORTFOLIO_ADD_TEXT_LINK);
  70   * </code>
  71   *{@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} for more information
  72   *
  73   * @package core_portfolio
  74   * @category portfolio
  75   * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  76   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  77   */
  78  class portfolio_add_button {
  79  
  80      /** @var string the name of the callback functions */
  81      private $callbackclass;
  82  
  83      /** @var array can be an array of arguments to pass back to the callback functions (passed by reference)*/
  84      private $callbackargs;
  85  
  86      /** @var string caller file */
  87      private $callbackcomponent;
  88  
  89      /** @var array array of more specific formats (eg based on mime detection) */
  90      private $formats;
  91  
  92      /** @var array array of portfolio instances */
  93      private $instances;
  94  
  95      /** @var stored_file for single-file exports */
  96      private $file;
  97  
  98      /** @var string for writing specific types of files*/
  99      private $intendedmimetype;
 100  
 101      /**
 102       * Constructor. Either pass the options here or set them using the helper methods.
 103       * Generally the code will be clearer if you use the helper methods.
 104       *
 105       * @param array $options keyed array of options:
 106       *                       key 'callbackclass': name of the caller class (eg forum_portfolio_caller')
 107       *                       key 'callbackargs': the array of callback arguments your caller class wants passed to it in the constructor
 108       *                       key 'callbackcomponent': the file containing the class definition of your caller class.
 109       *                       See set_callback_options for more information on these three.
 110       *                       key 'formats': an array of PORTFOLIO_FORMATS this caller will support
 111       *                       See set_formats or set_format_by_file for more information on this.
 112       */
 113      public function __construct($options=null) {
 114          global $SESSION, $CFG;
 115  
 116          if (empty($CFG->enableportfolios)) {
 117              debugging('Building portfolio add button while portfolios is disabled. This code can be optimised.', DEBUG_DEVELOPER);
 118          }
 119  
 120          $this->instances = portfolio_instances();
 121          if (empty($options)) {
 122              return true;
 123          }
 124          $constructoroptions = array('callbackclass', 'callbackargs', 'callbackcomponent');
 125          foreach ((array)$options as $key => $value) {
 126              if (!in_array($key, $constructoroptions)) {
 127                  throw new portfolio_button_exception('invalidbuttonproperty', 'portfolio', $key);
 128              }
 129          }
 130  
 131          $this->set_callback_options($options['callbackclass'], $options['callbackargs'], $options['callbackcomponent']);
 132      }
 133  
 134      /**
 135       * Function to set the callback options
 136       *
 137       * @param string $class Name of the class containing the callback functions
 138       *      activity components should ALWAYS use their name_portfolio_caller
 139       *      other locations must use something unique
 140       * @param array $argarray This can be an array or hash of arguments to pass
 141       *      back to the callback functions (passed by reference)
 142       *      these MUST be primatives to be added as hidden form fields.
 143       *      and the values get cleaned to PARAM_ALPHAEXT or PARAM_FLOAT or PARAM_PATH
 144       * @param string $component This is the name of the component in Moodle, eg 'mod_forum'
 145       */
 146      public function set_callback_options($class, array $argarray, $component) {
 147          global $CFG;
 148  
 149          // Require the base class first before any other files.
 150          require_once($CFG->libdir . '/portfolio/caller.php');
 151  
 152          // Include any potential callback files and check for errors.
 153          portfolio_include_callback_file($component, $class);
 154  
 155          // This will throw exceptions but should not actually do anything other than verify callbackargs.
 156          $test = new $class($argarray);
 157          unset($test);
 158  
 159          $this->callbackcomponent = $component;
 160          $this->callbackclass = $class;
 161          $this->callbackargs = $argarray;
 162      }
 163  
 164      /**
 165       * Sets the available export formats for this content.
 166       * This function will also poll the static function in the caller class
 167       * and make sure we're not overriding a format that has nothing to do with mimetypes.
 168       * Eg: if you pass IMAGE here but the caller can export LEAP2A it will keep LEAP2A as well.
 169       * @see portfolio_most_specific_formats for more information
 170       * @see portfolio_format_from_mimetype
 171       *
 172       * @param array $formats if the calling code knows better than the static method on the calling class (base_supported_formats).
 173       *                       Eg: if it's going to be a single file, or if you know it's HTML, you can pass it here instead.
 174       *                       This is almost always the case so it should be use all the times
 175       *                       portfolio_format_from_mimetype for how to get the appropriate formats to pass here for uploaded files.
 176       *                       or just call set_format_by_file instead
 177       */
 178      public function set_formats($formats=null) {
 179          if (is_string($formats)) {
 180              $formats = array($formats);
 181          }
 182          if (empty($formats)) {
 183              $formats = array();
 184          }
 185          if (empty($this->callbackclass)) {
 186              throw new portfolio_button_exception('noclassbeforeformats', 'portfolio');
 187          }
 188          $callerformats = call_user_func(array($this->callbackclass, 'base_supported_formats'));
 189          $this->formats = portfolio_most_specific_formats($formats, $callerformats);
 190      }
 191  
 192      /**
 193       * Reset formats to the default,
 194       * which is usually what base_supported_formats returns
 195       */
 196      public function reset_formats() {
 197          $this->set_formats();
 198      }
 199  
 200  
 201      /**
 202       * If we already know we have exactly one file,
 203       * bypass set_formats and just pass the file
 204       * so we can detect the formats by mimetype.
 205       *
 206       * @param stored_file $file file to set the format from
 207       * @param array $extraformats any additional formats other than by mimetype
 208       *                            eg leap2a etc
 209       */
 210      public function set_format_by_file(stored_file $file, $extraformats=null) {
 211          $this->file = $file;
 212          $fileformat = portfolio_format_from_mimetype($file->get_mimetype());
 213          if (is_string($extraformats)) {
 214              $extraformats = array($extraformats);
 215          } else if (!is_array($extraformats)) {
 216              $extraformats = array();
 217          }
 218          $this->set_formats(array_merge(array($fileformat), $extraformats));
 219      }
 220  
 221      /**
 222       * Correllary this is use to set_format_by_file, but it is also used when there is no stored_file and
 223       * when we're writing out a new type of file (like csv or pdf)
 224       *
 225       * @param string $extn the file extension we intend to generate
 226       * @param array  $extraformats any additional formats other than by mimetype
 227       *                             eg leap2a etc
 228       */
 229      public function set_format_by_intended_file($extn, $extraformats=null) {
 230          $mimetype = mimeinfo('type', 'something. ' . $extn);
 231          $fileformat = portfolio_format_from_mimetype($mimetype);
 232          $this->intendedmimetype = $fileformat;
 233          if (is_string($extraformats)) {
 234              $extraformats = array($extraformats);
 235          } else if (!is_array($extraformats)) {
 236              $extraformats = array();
 237          }
 238          $this->set_formats(array_merge(array($fileformat), $extraformats));
 239      }
 240  
 241      /**
 242       * Echo the form/button/icon/text link to the page
 243       *
 244       * @param int $format format to display the button or form or icon or link.
 245       *                    See constants PORTFOLIO_ADD_XXX for more info.
 246       *                    optional, defaults to PORTFOLIO_ADD_FULL_FORM
 247       * @param string $addstr string to use for the button or icon alt text or link text.
 248       *                       this is whole string, not key. optional, defaults to 'Export to portfolio';
 249       */
 250      public function render($format=null, $addstr=null) {
 251          echo $this->to_html($format, $addstr);
 252      }
 253  
 254      /**
 255       * Returns the form/button/icon/text link as html
 256       *
 257       * @param int $format format to display the button or form or icon or link.
 258       *                    See constants PORTFOLIO_ADD_XXX for more info.
 259       *                    Optional, defaults to PORTFOLIO_ADD_FULL_FORM
 260       * @param string $addstr string to use for the button or icon alt text or link text.
 261       *                       This is whole string, not key.  optional, defaults to 'Add to portfolio';
 262       * @return void|string
 263       */
 264      public function to_html($format=null, $addstr=null) {
 265          global $CFG, $COURSE, $OUTPUT, $USER;
 266          if (!$this->is_renderable()) {
 267              return;
 268          }
 269          if (empty($this->callbackclass) || empty($this->callbackcomponent)) {
 270              throw new portfolio_button_exception('mustsetcallbackoptions', 'portfolio');
 271          }
 272          if (empty($this->formats)) {
 273              // use the caller defaults
 274              $this->set_formats();
 275          }
 276          $url = new moodle_url('/portfolio/add.php');
 277          foreach ($this->callbackargs as $key => $value) {
 278              if (!empty($value) && !is_string($value) && !is_numeric($value)) {
 279                  $a = new stdClass();
 280                  $a->key = $key;
 281                  $a->value = print_r($value, true);
 282                  debugging(get_string('nonprimative', 'portfolio', $a));
 283                  return;
 284              }
 285              $url->param('ca_' . $key, $value);
 286          }
 287          $url->param('sesskey', sesskey());
 288          $url->param('callbackcomponent', $this->callbackcomponent);
 289          $url->param('callbackclass', $this->callbackclass);
 290          $url->param('course', (!empty($COURSE)) ? $COURSE->id : 0);
 291          $url->param('callerformats', implode(',', $this->formats));
 292          $mimetype = null;
 293          if ($this->file instanceof stored_file) {
 294              $mimetype = $this->file->get_mimetype();
 295          } else if ($this->intendedmimetype) {
 296              $mimetype = $this->intendedmimetype;
 297          }
 298          $selectoutput = '';
 299          if (count($this->instances) == 1) {
 300              $tmp = array_values($this->instances);
 301              $instance = $tmp[0];
 302  
 303              $formats = portfolio_supported_formats_intersect($this->formats, $instance->supported_formats());
 304              if (count($formats) == 0) {
 305                  // bail. no common formats.
 306                  //debugging(get_string('nocommonformats', 'portfolio', (object)array('location' => $this->callbackclass, 'formats' => implode(',', $this->formats))));
 307                  return;
 308              }
 309              if ($error = portfolio_instance_sanity_check($instance)) {
 310                  // bail, plugin is misconfigured
 311                  //debugging(get_string('instancemisconfigured', 'portfolio', get_string($error[$instance->get('id')], 'portfolio_' . $instance->get('plugin'))));
 312                  return;
 313              }
 314              if (!$instance->allows_multiple_exports() && $already = portfolio_existing_exports($USER->id, $instance->get('plugin'))) {
 315                  //debugging(get_string('singleinstancenomultiallowed', 'portfolio'));
 316                  return;
 317              }
 318              if ($mimetype&& !$instance->file_mime_check($mimetype)) {
 319                  // bail, we have a specific file or mimetype and this plugin doesn't support it
 320                  //debugging(get_string('mimecheckfail', 'portfolio', (object)array('plugin' => $instance->get('plugin'), 'mimetype' => $mimetype)));
 321                  return;
 322              }
 323              $url->param('instance', $instance->get('id'));
 324          }
 325          else {
 326              if (!$selectoutput = portfolio_instance_select($this->instances, $this->formats, $this->callbackclass, $mimetype, 'instance', true)) {
 327                  return;
 328              }
 329          }
 330          // if we just want a url to redirect to, do it now
 331          if ($format == PORTFOLIO_ADD_FAKE_URL) {
 332              return $url->out(false);
 333          }
 334  
 335          if (empty($addstr)) {
 336              $addstr = get_string('addtoportfolio', 'portfolio');
 337          }
 338          if (empty($format)) {
 339              $format = PORTFOLIO_ADD_FULL_FORM;
 340          }
 341  
 342          $formoutput = '<form method="post" action="' . $CFG->wwwroot . '/portfolio/add.php" id="portfolio-add-button">' . "\n";
 343          $formoutput .= html_writer::input_hidden_params($url);
 344          $linkoutput = '';
 345  
 346          switch ($format) {
 347              case PORTFOLIO_ADD_FULL_FORM:
 348                  $formoutput .= $selectoutput;
 349                  $formoutput .= "\n" . '<input type="submit" value="' . $addstr .'" />';
 350                  $formoutput .= "\n" . '</form>';
 351              break;
 352              case PORTFOLIO_ADD_ICON_FORM:
 353                  $formoutput .= $selectoutput;
 354                  $formoutput .= "\n" . '<input class="portfolio-add-icon" type="image" src="' . $OUTPUT->pix_url('t/portfolioadd') . '" alt=' . $addstr .'" />';
 355                  $formoutput .= "\n" . '</form>';
 356              break;
 357              case PORTFOLIO_ADD_ICON_LINK:
 358                  $linkoutput = $OUTPUT->action_icon($url, new pix_icon('t/portfolioadd', $addstr, '',
 359                      array('class' => 'portfolio-add-icon smallicon')));
 360              break;
 361              case PORTFOLIO_ADD_TEXT_LINK:
 362                  $linkoutput = html_writer::link($url, $addstr, array('class' => 'portfolio-add-link',
 363                      'title' => $addstr));
 364              break;
 365              default:
 366                  debugging(get_string('invalidaddformat', 'portfolio', $format));
 367          }
 368          $output = (in_array($format, array(PORTFOLIO_ADD_FULL_FORM, PORTFOLIO_ADD_ICON_FORM)) ? $formoutput : $linkoutput);
 369          return $output;
 370      }
 371  
 372      /**
 373       * Perform some internal checks.
 374       * These are not errors, just situations
 375       * where it's not appropriate to add the button
 376       *
 377       * @return bool
 378       */
 379      private function is_renderable() {
 380          global $CFG;
 381          if (empty($CFG->enableportfolios)) {
 382              return false;
 383          }
 384          if (defined('PORTFOLIO_INTERNAL')) {
 385              // something somewhere has detected a risk of this being called during inside the preparation
 386              // eg forum_print_attachments
 387              return false;
 388          }
 389          if (empty($this->instances) || count($this->instances) == 0) {
 390              return false;
 391          }
 392          return true;
 393      }
 394  
 395      /**
 396       * Getter for $format property
 397       *
 398       * @return array
 399       */
 400      public function get_formats() {
 401          return $this->formats;
 402      }
 403  
 404      /**
 405       * Getter for $callbackargs property
 406       *
 407       * @return array
 408       */
 409      public function get_callbackargs() {
 410          return $this->callbackargs;
 411      }
 412  
 413      /**
 414       * Getter for $callbackcomponent property
 415       *
 416       * @return string
 417       */
 418      public function get_callbackcomponent() {
 419          return $this->callbackcomponent;
 420      }
 421  
 422      /**
 423       * Getter for $callbackclass property
 424       *
 425       * @return string
 426       */
 427      public function get_callbackclass() {
 428          return $this->callbackclass;
 429      }
 430  }
 431  
 432  /**
 433   * Returns a drop menu with a list of available instances.
 434   *
 435   * @param array          $instances      array of portfolio plugin instance objects - the instances to put in the menu
 436   * @param array          $callerformats  array of PORTFOLIO_FORMAT_XXX constants - the formats the caller supports (this is used to filter plugins)
 437   * @param string         $callbackclass  the callback class name - used for debugging only for when there are no common formats
 438   * @param string         $mimetype       if we already know we have exactly one file, or are going to write one, pass it here to do mime filtering.
 439   * @param string         $selectname     the name of the select element. Optional, defaults to instance.
 440   * @param bool           $return         whether to print or return the output. Optional, defaults to print.
 441   * @param bool           $returnarray    if returning, whether to return the HTML or the array of options. Optional, defaults to HTML.
 442   * @return void|array|string the html, from <select> to </select> inclusive.
 443   */
 444  function portfolio_instance_select($instances, $callerformats, $callbackclass, $mimetype=null, $selectname='instance', $return=false, $returnarray=false) {
 445      global $CFG, $USER;
 446  
 447      if (empty($CFG->enableportfolios)) {
 448          return;
 449      }
 450  
 451      $insane = portfolio_instance_sanity_check();
 452      $pinsane = portfolio_plugin_sanity_check();
 453  
 454      $count = 0;
 455      $selectoutput = "\n" . '<label class="accesshide" for="instanceid">' . get_string('plugin', 'portfolio') . '</label>';
 456      $selectoutput .= "\n" . '<select id="instanceid" name="' . $selectname . '">' . "\n";
 457      $existingexports = portfolio_existing_exports_by_plugin($USER->id);
 458      foreach ($instances as $instance) {
 459          $formats = portfolio_supported_formats_intersect($callerformats, $instance->supported_formats());
 460          if (count($formats) == 0) {
 461              // bail. no common formats.
 462              continue;
 463          }
 464          if (array_key_exists($instance->get('id'), $insane)) {
 465              // bail, plugin is misconfigured
 466              //debugging(get_string('instanceismisconfigured', 'portfolio', get_string($insane[$instance->get('id')], 'portfolio_' . $instance->get('plugin'))));
 467              continue;
 468          } else if (array_key_exists($instance->get('plugin'), $pinsane)) {
 469              // bail, plugin is misconfigured
 470              //debugging(get_string('pluginismisconfigured', 'portfolio', get_string($pinsane[$instance->get('plugin')], 'portfolio_' . $instance->get('plugin'))));
 471              continue;
 472          }
 473          if (!$instance->allows_multiple_exports() && in_array($instance->get('plugin'), $existingexports)) {
 474              // bail, already exporting something with this plugin and it doesn't support multiple exports
 475              continue;
 476          }
 477          if ($mimetype && !$instance->file_mime_check($mimetype)) {
 478              //debugging(get_string('mimecheckfail', 'portfolio', (object)array('plugin' => $instance->get('plugin'), 'mimetype' => $mimetype())));
 479              // bail, we have a specific file and this plugin doesn't support it
 480              continue;
 481          }
 482          $count++;
 483          $selectoutput .= "\n" . '<option value="' . $instance->get('id') . '">' . $instance->get('name') . '</option>' . "\n";
 484          $options[$instance->get('id')] = $instance->get('name');
 485      }
 486      if (empty($count)) {
 487          // bail. no common formats.
 488          //debugging(get_string('nocommonformats', 'portfolio', (object)array('location' => $callbackclass, 'formats' => implode(',', $callerformats))));
 489          return;
 490      }
 491      $selectoutput .= "\n" . "</select>\n";
 492      if (!empty($returnarray)) {
 493          return $options;
 494      }
 495      if (!empty($return)) {
 496          return $selectoutput;
 497      }
 498      echo $selectoutput;
 499  }
 500  
 501  /**
 502   * Return all portfolio instances
 503   *
 504   * @todo MDL-15768 - check capabilities here
 505   * @param bool $visibleonly Don't include hidden instances. Defaults to true and will be overridden to true if the next parameter is true
 506   * @param bool $useronly    Check the visibility preferences and permissions of the logged in user. Defaults to true.
 507   * @return array of portfolio instances (full objects, not just database records)
 508   */
 509  function portfolio_instances($visibleonly=true, $useronly=true) {
 510  
 511      global $DB, $USER;
 512  
 513      $values = array();
 514      $sql = 'SELECT * FROM {portfolio_instance}';
 515  
 516      if ($visibleonly || $useronly) {
 517          $values[] = 1;
 518          $sql .= ' WHERE visible = ?';
 519      }
 520      if ($useronly) {
 521          $sql .= ' AND id NOT IN (
 522                  SELECT instance FROM {portfolio_instance_user}
 523                  WHERE userid = ? AND name = ? AND ' . $DB->sql_compare_text('value') . ' = ?
 524              )';
 525          $values = array_merge($values, array($USER->id, 'visible', 0));
 526      }
 527      $sql .= ' ORDER BY name';
 528  
 529      $instances = array();
 530      foreach ($DB->get_records_sql($sql, $values) as $instance) {
 531          $instances[$instance->id] = portfolio_instance($instance->id, $instance);
 532      }
 533      return $instances;
 534  }
 535  
 536  /**
 537   * Return whether there are visible instances in portfolio.
 538   *
 539   * @return bool true when there are some visible instances.
 540   */
 541  function portfolio_has_visible_instances() {
 542      global $DB;
 543      return $DB->record_exists('portfolio_instance', array('visible' => 1));
 544  }
 545  
 546  /**
 547   * Supported formats currently in use.
 548   * Canonical place for a list of all formats
 549   * that portfolio plugins and callers
 550   * can use for exporting content
 551   *
 552   * @return array keyed array of all the available export formats (constant => classname)
 553   */
 554  function portfolio_supported_formats() {
 555      return array(
 556          PORTFOLIO_FORMAT_FILE         => 'portfolio_format_file',
 557          PORTFOLIO_FORMAT_IMAGE        => 'portfolio_format_image',
 558          PORTFOLIO_FORMAT_RICHHTML     => 'portfolio_format_richhtml',
 559          PORTFOLIO_FORMAT_PLAINHTML    => 'portfolio_format_plainhtml',
 560          PORTFOLIO_FORMAT_TEXT         => 'portfolio_format_text',
 561          PORTFOLIO_FORMAT_VIDEO        => 'portfolio_format_video',
 562          PORTFOLIO_FORMAT_PDF          => 'portfolio_format_pdf',
 563          PORTFOLIO_FORMAT_DOCUMENT     => 'portfolio_format_document',
 564          PORTFOLIO_FORMAT_SPREADSHEET  => 'portfolio_format_spreadsheet',
 565          PORTFOLIO_FORMAT_PRESENTATION => 'portfolio_format_presentation',
 566          /*PORTFOLIO_FORMAT_MBKP, */ // later
 567          PORTFOLIO_FORMAT_LEAP2A       => 'portfolio_format_leap2a',
 568          PORTFOLIO_FORMAT_RICH         => 'portfolio_format_rich',
 569      );
 570  }
 571  
 572  /**
 573   * Deduce export format from file mimetype
 574   * This function returns the revelant portfolio export format
 575   * which is used to determine which portfolio plugins can be used
 576   * for exporting this content
 577   * according to the given mime type
 578   * this only works when exporting exactly <b>one</b> file, or generating a new one
 579   * (like a pdf or csv export)
 580   *
 581   * @param string $mimetype (usually $file->get_mimetype())
 582   * @return string the format constant (see PORTFOLIO_FORMAT_XXX constants)
 583   */
 584  function portfolio_format_from_mimetype($mimetype) {
 585      global $CFG;
 586      static $alreadymatched;
 587      if (empty($alreadymatched)) {
 588          $alreadymatched = array();
 589      }
 590      if (array_key_exists($mimetype, $alreadymatched)) {
 591          return $alreadymatched[$mimetype];
 592      }
 593      $allformats = portfolio_supported_formats();
 594      require_once($CFG->libdir . '/portfolio/formats.php');
 595      foreach ($allformats as $format => $classname) {
 596          $supportedmimetypes = call_user_func(array($classname, 'mimetypes'));
 597          if (!is_array($supportedmimetypes)) {
 598              debugging("one of the portfolio format classes, $classname, said it supported something funny for mimetypes, should have been array...");
 599              debugging(print_r($supportedmimetypes, true));
 600              continue;
 601          }
 602          if (in_array($mimetype, $supportedmimetypes)) {
 603              $alreadymatched[$mimetype] = $format;
 604              return $format;
 605          }
 606      }
 607      return PORTFOLIO_FORMAT_FILE; // base case for files...
 608  }
 609  
 610  /**
 611   * Intersection of plugin formats and caller formats.
 612   * Walks both the caller formats and portfolio plugin formats
 613   * and looks for matches (walking the hierarchy as well)
 614   * and returns the intersection
 615   *
 616   * @param array $callerformats formats the caller supports
 617   * @param array $pluginformats formats the portfolio plugin supports
 618   * @return array
 619   */
 620  function portfolio_supported_formats_intersect($callerformats, $pluginformats) {
 621      global $CFG;
 622      $allformats = portfolio_supported_formats();
 623      $intersection = array();
 624      foreach ($callerformats as $cf) {
 625          if (!array_key_exists($cf, $allformats)) {
 626              if (!portfolio_format_is_abstract($cf)) {
 627                  debugging(get_string('invalidformat', 'portfolio', $cf));
 628              }
 629              continue;
 630          }
 631          require_once($CFG->libdir . '/portfolio/formats.php');
 632          $cfobj = new $allformats[$cf]();
 633          foreach ($pluginformats as $p => $pf) {
 634              if (!array_key_exists($pf, $allformats)) {
 635                  if (!portfolio_format_is_abstract($pf)) {
 636                      debugging(get_string('invalidformat', 'portfolio', $pf));
 637                  }
 638                  unset($pluginformats[$p]); // to avoid the same warning over and over
 639                  continue;
 640              }
 641              if ($cfobj instanceof $allformats[$pf]) {
 642                  $intersection[] = $cf;
 643              }
 644          }
 645      }
 646      return $intersection;
 647  }
 648  
 649  /**
 650   * Tiny helper to figure out whether a portfolio format is abstract
 651   *
 652   * @param string $format the format to test
 653   * @return bool
 654   */
 655  function portfolio_format_is_abstract($format) {
 656      if (class_exists($format)) {
 657          $class = $format;
 658      } else if (class_exists('portfolio_format_' . $format)) {
 659          $class = 'portfolio_format_' . $format;
 660      } else {
 661          $allformats = portfolio_supported_formats();
 662          if (array_key_exists($format, $allformats)) {
 663              $class = $allformats[$format];
 664          }
 665      }
 666      if (empty($class)) {
 667          return true; // it may as well be, we can't instantiate it :)
 668      }
 669      $rc = new ReflectionClass($class);
 670      return $rc->isAbstract();
 671  }
 672  
 673  /**
 674   * Return the combination of the two arrays of formats with duplicates in terms of specificity removed
 675   * and also removes conflicting formats.
 676   * Use case: a module is exporting a single file, so the general formats would be FILE and MBKP
 677   *           while the specific formats would be the specific subclass of FILE based on mime (say IMAGE)
 678   *           and this function would return IMAGE and MBKP
 679   *
 680   * @param array $specificformats array of more specific formats (eg based on mime detection)
 681   * @param array $generalformats  array of more general formats (usually more supported)
 682   * @return array merged formats with dups removed
 683   */
 684  function portfolio_most_specific_formats($specificformats, $generalformats) {
 685      global $CFG;
 686      $allformats = portfolio_supported_formats();
 687      if (empty($specificformats)) {
 688          return $generalformats;
 689      } else if (empty($generalformats)) {
 690          return $specificformats;
 691      }
 692      $removedformats = array();
 693      foreach ($specificformats as $k => $f) {
 694          // look for something less specific and remove it, ie outside of the inheritance tree of the current formats.
 695          if (!array_key_exists($f, $allformats)) {
 696              if (!portfolio_format_is_abstract($f)) {
 697                  throw new portfolio_button_exception('invalidformat', 'portfolio', $f);
 698              }
 699          }
 700          if (in_array($f, $removedformats)) {
 701              // already been removed from the general list
 702              //debugging("skipping $f because it was already removed");
 703              unset($specificformats[$k]);
 704          }
 705          require_once($CFG->libdir . '/portfolio/formats.php');
 706          $fobj = new $allformats[$f];
 707          foreach ($generalformats as $key => $cf) {
 708              if (in_array($cf, $removedformats)) {
 709                  //debugging("skipping $cf because it was already removed");
 710                  continue;
 711              }
 712              $cfclass = $allformats[$cf];
 713              $cfobj = new $allformats[$cf];
 714              if ($fobj instanceof $cfclass && $cfclass != get_class($fobj)) {
 715                  //debugging("unsetting $key $cf because it's not specific enough ($f is better)");
 716                  unset($generalformats[$key]);
 717                  $removedformats[] = $cf;
 718                  continue;
 719              }
 720              // check for conflicts
 721              if ($fobj->conflicts($cf)) {
 722                  //debugging("unsetting $key $cf because it conflicts with $f");
 723                  unset($generalformats[$key]);
 724                  $removedformats[] = $cf;
 725                  continue;
 726              }
 727              if ($cfobj->conflicts($f)) {
 728                  //debugging("unsetting $key $cf because it reverse-conflicts with $f");
 729                  $removedformats[] = $cf;
 730                  unset($generalformats[$key]);
 731                  continue;
 732              }
 733          }
 734          //debugging('inside loop');
 735          //print_object($generalformats);
 736      }
 737  
 738      //debugging('final formats');
 739      $finalformats =  array_unique(array_merge(array_values($specificformats), array_values($generalformats)));
 740      //print_object($finalformats);
 741      return $finalformats;
 742  }
 743  
 744  /**
 745   * Helper function to return a format object from the constant
 746   *
 747   * @param string $name the constant PORTFOLIO_FORMAT_XXX
 748   * @return portfolio_format
 749   */
 750  function portfolio_format_object($name) {
 751      global $CFG;
 752      require_once($CFG->libdir . '/portfolio/formats.php');
 753      $formats = portfolio_supported_formats();
 754      return new $formats[$name];
 755  }
 756  
 757  /**
 758   * Helper function to return an instance of a plugin (with config loaded)
 759   *
 760   * @param int   $instanceid id of instance
 761   * @param object $record database row that corresponds to this instance
 762   *                       this is passed to avoid unnecessary lookups
 763   *                       Optional, and the record will be retrieved if null.
 764   * @return object of portfolio_plugin_XXX
 765   */
 766  function portfolio_instance($instanceid, $record=null) {
 767      global $DB, $CFG;
 768  
 769      if ($record) {
 770          $instance  = $record;
 771      } else {
 772          if (!$instance = $DB->get_record('portfolio_instance', array('id' => $instanceid))) {
 773              throw new portfolio_exception('invalidinstance', 'portfolio');
 774          }
 775      }
 776      require_once($CFG->libdir . '/portfolio/plugin.php');
 777      require_once($CFG->dirroot . '/portfolio/'. $instance->plugin . '/lib.php');
 778      $classname = 'portfolio_plugin_' . $instance->plugin;
 779      return new $classname($instanceid, $instance);
 780  }
 781  
 782  /**
 783   * Helper function to call a static function on a portfolio plugin class.
 784   * This will figure out the classname and require the right file and call the function.
 785   * You can send a variable number of arguments to this function after the first two
 786   * and they will be passed on to the function you wish to call.
 787   *
 788   * @param string $plugin   name of plugin
 789   * @param string $function function to call
 790   * @return mixed
 791   */
 792  function portfolio_static_function($plugin, $function) {
 793      global $CFG;
 794  
 795      $pname = null;
 796      if (is_object($plugin) || is_array($plugin)) {
 797          $plugin = (object)$plugin;
 798          $pname = $plugin->name;
 799      } else {
 800          $pname = $plugin;
 801      }
 802  
 803      $args = func_get_args();
 804      if (count($args) <= 2) {
 805          $args = array();
 806      }
 807      else {
 808          array_shift($args);
 809          array_shift($args);
 810      }
 811  
 812      require_once($CFG->libdir . '/portfolio/plugin.php');
 813      require_once($CFG->dirroot . '/portfolio/' . $plugin .  '/lib.php');
 814      return call_user_func_array(array('portfolio_plugin_' . $plugin, $function), $args);
 815  }
 816  
 817  /**
 818   * Helper function to check all the plugins for sanity and set any insane ones to invisible.
 819   *
 820   * @param array $plugins array of supported plugin types
 821   * @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
 822   */
 823  function portfolio_plugin_sanity_check($plugins=null) {
 824      global $DB;
 825      if (is_string($plugins)) {
 826          $plugins = array($plugins);
 827      } else if (empty($plugins)) {
 828          $plugins = core_component::get_plugin_list('portfolio');
 829          $plugins = array_keys($plugins);
 830      }
 831  
 832      $insane = array();
 833      foreach ($plugins as $plugin) {
 834          if ($result = portfolio_static_function($plugin, 'plugin_sanity_check')) {
 835              $insane[$plugin] = $result;
 836          }
 837      }
 838      if (empty($insane)) {
 839          return array();
 840      }
 841      list($where, $params) = $DB->get_in_or_equal(array_keys($insane));
 842      $where = ' plugin ' . $where;
 843      $DB->set_field_select('portfolio_instance', 'visible', 0, $where, $params);
 844      return $insane;
 845  }
 846  
 847  /**
 848   * Helper function to check all the instances for sanity and set any insane ones to invisible.
 849   *
 850   * @param array $instances array of plugin instances
 851   * @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
 852   */
 853  function portfolio_instance_sanity_check($instances=null) {
 854      global $DB;
 855      if (empty($instances)) {
 856          $instances = portfolio_instances(false);
 857      } else if (!is_array($instances)) {
 858          $instances = array($instances);
 859      }
 860  
 861      $insane = array();
 862      foreach ($instances as $instance) {
 863          if (is_object($instance) && !($instance instanceof portfolio_plugin_base)) {
 864              $instance = portfolio_instance($instance->id, $instance);
 865          } else if (is_numeric($instance)) {
 866              $instance = portfolio_instance($instance);
 867          }
 868          if (!($instance instanceof portfolio_plugin_base)) {
 869              debugging('something weird passed to portfolio_instance_sanity_check, not subclass or id');
 870              continue;
 871          }
 872          if ($result = $instance->instance_sanity_check()) {
 873              $insane[$instance->get('id')] = $result;
 874          }
 875      }
 876      if (empty($insane)) {
 877          return array();
 878      }
 879      list ($where, $params) = $DB->get_in_or_equal(array_keys($insane));
 880      $where = ' id ' . $where;
 881      $DB->set_field_select('portfolio_instance', 'visible', 0, $where, $params);
 882      portfolio_insane_notify_admins($insane, true);
 883      return $insane;
 884  }
 885  
 886  /**
 887   * Helper function to display a table of plugins (or instances) and reasons for disabling
 888   *
 889   * @param array $insane array of portfolio plugin
 890   * @param array $instances if reporting instances rather than whole plugins, pass the array (key = id, value = object) here
 891   * @param bool $return option to deliver the report in html format or print it out directly to the page.
 892   * @return void|string of portfolio report in html table format
 893   */
 894  function portfolio_report_insane($insane, $instances=false, $return=false) {
 895      global $OUTPUT;
 896      if (empty($insane)) {
 897          return;
 898      }
 899  
 900      static $pluginstr;
 901      if (empty($pluginstr)) {
 902          $pluginstr = get_string('plugin', 'portfolio');
 903      }
 904      if ($instances) {
 905          $headerstr = get_string('someinstancesdisabled', 'portfolio');
 906      } else {
 907          $headerstr = get_string('somepluginsdisabled', 'portfolio');
 908      }
 909  
 910      $output = $OUTPUT->notification($headerstr, 'notifyproblem');
 911      $table = new html_table();
 912      $table->head = array($pluginstr, '');
 913      $table->data = array();
 914      foreach ($insane as $plugin => $reason) {
 915          if ($instances) {
 916              $instance = $instances[$plugin];
 917              $plugin   = $instance->get('plugin');
 918              $name     = $instance->get('name');
 919          } else {
 920              $name = $plugin;
 921          }
 922          $table->data[] = array($name, get_string($reason, 'portfolio_' . $plugin));
 923      }
 924      $output .= html_writer::table($table);
 925      $output .= '<br /><br /><br />';
 926  
 927      if ($return) {
 928          return $output;
 929      }
 930      echo $output;
 931  }
 932  
 933  /**
 934   * Main portfolio cronjob.
 935   * Currently just cleans up expired transfer records.
 936   */
 937  function portfolio_cron() {
 938      global $DB, $CFG;
 939  
 940      require_once($CFG->libdir . '/portfolio/exporter.php');
 941      if ($expired = $DB->get_records_select('portfolio_tempdata', 'expirytime < ?', array(time()), '', 'id')) {
 942          foreach ($expired as $d) {
 943              try {
 944                  $e = portfolio_exporter::rewaken_object($d->id);
 945                  $e->process_stage_cleanup(true);
 946              } catch (Exception $e) {
 947                  mtrace('Exception thrown in portfolio cron while cleaning up ' . $d->id . ': ' . $e->getMessage());
 948              }
 949          }
 950      }
 951  
 952      $process = $DB->get_records('portfolio_tempdata', array('queued' => 1), 'id ASC', 'id');
 953      foreach ($process as $d) {
 954          try {
 955              $exporter = portfolio_exporter::rewaken_object($d->id);
 956              $exporter->process_stage_package();
 957              $exporter->process_stage_send();
 958              $exporter->save();
 959              $exporter->process_stage_cleanup();
 960          } catch (Exception $e) {
 961              // This will get probably retried in the next cron until it is discarded by the code above.
 962              mtrace('Exception thrown in portfolio cron while processing ' . $d->id . ': ' . $e->getMessage());
 963          }
 964      }
 965  }
 966  
 967  /**
 968   * Helper function to rethrow a caught portfolio_exception as an export exception.
 969   * Used because when a portfolio_export exception is thrown the export is cancelled
 970   * throws portfolio_export_exceptiog
 971   *
 972   * @param portfolio_exporter $exporter  current exporter object
 973   * @param object             $exception exception to rethrow
 974   */
 975  function portfolio_export_rethrow_exception($exporter, $exception) {
 976      throw new portfolio_export_exception($exporter, $exception->errorcode, $exception->module, $exception->link, $exception->a);
 977  }
 978  
 979  /**
 980   * Try and determine expected_time for purely file based exports
 981   * or exports that might include large file attachments.
 982   *
 983   * @param stored_file|array $totest - either an array of stored_file objects or a single stored_file object
 984   * @return string PORTFOLIO_TIME_XXX
 985   */
 986  function portfolio_expected_time_file($totest) {
 987      global $CFG;
 988      if ($totest instanceof stored_file) {
 989          $totest = array($totest);
 990      }
 991      $size = 0;
 992      foreach ($totest as $file) {
 993          if (!($file instanceof stored_file)) {
 994              debugging('something weird passed to portfolio_expected_time_file - not stored_file object');
 995              debugging(print_r($file, true));
 996              continue;
 997          }
 998          $size += $file->get_filesize();
 999      }
1000  
1001      $fileinfo = portfolio_filesize_info();
1002  
1003      $moderate = $high = 0; // avoid warnings
1004  
1005      foreach (array('moderate', 'high') as $setting) {
1006          $settingname = 'portfolio_' . $setting . '_filesize_threshold';
1007          if (empty($CFG->{$settingname}) || !array_key_exists($CFG->{$settingname}, $fileinfo['options'])) {
1008              debugging("weird or unset admin value for $settingname, using default instead");
1009              $$setting = $fileinfo[$setting];
1010          } else {
1011              $$setting = $CFG->{$settingname};
1012          }
1013      }
1014  
1015      if ($size < $moderate) {
1016          return PORTFOLIO_TIME_LOW;
1017      } else if ($size < $high) {
1018          return PORTFOLIO_TIME_MODERATE;
1019      }
1020      return PORTFOLIO_TIME_HIGH;
1021  }
1022  
1023  
1024  /**
1025   * The default filesizes and threshold information for file based transfers.
1026   * This shouldn't need to be used outside the admin pages and the portfolio code
1027   *
1028   * @return array
1029   */
1030  function portfolio_filesize_info() {
1031      $filesizes = array();
1032      $sizelist = array(10240, 51200, 102400, 512000, 1048576, 2097152, 5242880, 10485760, 20971520, 52428800);
1033      foreach ($sizelist as $size) {
1034          $filesizes[$size] = display_size($size);
1035      }
1036      return array(
1037          'options' => $filesizes,
1038          'moderate' => 1048576,
1039          'high'     => 5242880,
1040      );
1041  }
1042  
1043  /**
1044   * Try and determine expected_time for purely database based exports
1045   * or exports that might include large parts of a database.
1046   *
1047   * @param int $recordcount number of records trying to export
1048   * @return string PORTFOLIO_TIME_XXX
1049   */
1050  function portfolio_expected_time_db($recordcount) {
1051      global $CFG;
1052  
1053      if (empty($CFG->portfolio_moderate_dbsize_threshold)) {
1054          set_config('portfolio_moderate_dbsize_threshold', 10);
1055      }
1056      if (empty($CFG->portfolio_high_dbsize_threshold)) {
1057          set_config('portfolio_high_dbsize_threshold', 50);
1058      }
1059      if ($recordcount < $CFG->portfolio_moderate_dbsize_threshold) {
1060          return PORTFOLIO_TIME_LOW;
1061      } else if ($recordcount < $CFG->portfolio_high_dbsize_threshold) {
1062          return PORTFOLIO_TIME_MODERATE;
1063      }
1064      return PORTFOLIO_TIME_HIGH;
1065  }
1066  
1067  /**
1068   * Function to send portfolio report to admins
1069   *
1070   * @param array $insane array of insane plugins
1071   * @param array $instances (optional) if reporting instances rather than whole plugins
1072   */
1073  function portfolio_insane_notify_admins($insane, $instances=false) {
1074  
1075      global $CFG;
1076  
1077      if (defined('ADMIN_EDITING_PORTFOLIO')) {
1078          return true;
1079      }
1080  
1081      $admins = get_admins();
1082  
1083      if (empty($admins)) {
1084          return;
1085      }
1086      if ($instances) {
1087          $instances = portfolio_instances(false, false);
1088      }
1089  
1090      $site = get_site();
1091  
1092      $a = new StdClass;
1093      $a->sitename = format_string($site->fullname, true, array('context' => context_course::instance(SITEID)));
1094      $a->fixurl   = "$CFG->wwwroot/$CFG->admin/settings.php?section=manageportfolios";
1095      $a->htmllist = portfolio_report_insane($insane, $instances, true);
1096      $a->textlist = '';
1097  
1098      foreach ($insane as $k => $reason) {
1099          if ($instances) {
1100              $a->textlist = $instances[$k]->get('name') . ': ' . $reason . "\n";
1101          } else {
1102              $a->textlist = $k . ': ' . $reason . "\n";
1103          }
1104      }
1105  
1106      $subject   = get_string('insanesubject', 'portfolio');
1107      $plainbody = get_string('insanebody', 'portfolio', $a);
1108      $htmlbody  = get_string('insanebodyhtml', 'portfolio', $a);
1109      $smallbody = get_string('insanebodysmall', 'portfolio', $a);
1110  
1111      foreach ($admins as $admin) {
1112          $eventdata = new stdClass();
1113          $eventdata->modulename = 'portfolio';
1114          $eventdata->component = 'portfolio';
1115          $eventdata->name = 'notices';
1116          $eventdata->userfrom = get_admin();
1117          $eventdata->userto = $admin;
1118          $eventdata->subject = $subject;
1119          $eventdata->fullmessage = $plainbody;
1120          $eventdata->fullmessageformat = FORMAT_PLAIN;
1121          $eventdata->fullmessagehtml = $htmlbody;
1122          $eventdata->smallmessage = $smallbody;
1123          message_send($eventdata);
1124      }
1125  }
1126  
1127  /**
1128   * Setup page export
1129   *
1130   * @param moodle_page $PAGE global variable from page object
1131   * @param portfolio_caller_base $caller plugin type caller
1132   */
1133  function portfolio_export_pagesetup($PAGE, $caller) {
1134      // set up the context so that build_navigation works nice
1135      $caller->set_context($PAGE);
1136  
1137      list($extranav, $cm) = $caller->get_navigation();
1138  
1139      // and now we know the course for sure and maybe the cm, call require_login with it
1140      require_login($PAGE->course, false, $cm);
1141  
1142      foreach ($extranav as $navitem) {
1143          $PAGE->navbar->add($navitem['name']);
1144      }
1145      $PAGE->navbar->add(get_string('exporting', 'portfolio'));
1146  }
1147  
1148  /**
1149   * Get export type id
1150   *
1151   * @param string $type plugin type
1152   * @param int $userid the user to check for
1153   * @return mixed|bool
1154   */
1155  function portfolio_export_type_to_id($type, $userid) {
1156      global $DB;
1157      $sql = 'SELECT t.id FROM {portfolio_tempdata} t JOIN {portfolio_instance} i ON t.instance = i.id WHERE t.userid = ? AND i.plugin = ?';
1158      return $DB->get_field_sql($sql, array($userid, $type));
1159  }
1160  
1161  /**
1162   * Return a list of current exports for the given user.
1163   * This will not go through and call rewaken_object, because it's heavy.
1164   * It's really just used to figure out what exports are currently happening.
1165   * This is useful for plugins that don't support multiple exports per session
1166   *
1167   * @param int $userid the user to check for
1168   * @param string $type (optional) the portfolio plugin to filter by
1169   * @return array
1170   */
1171  function portfolio_existing_exports($userid, $type=null) {
1172      global $DB;
1173      $sql = 'SELECT t.*,t.instance,i.plugin,i.name FROM {portfolio_tempdata} t JOIN {portfolio_instance} i ON t.instance = i.id WHERE t.userid = ? ';
1174      $values = array($userid);
1175      if ($type) {
1176          $sql .= ' AND i.plugin = ?';
1177          $values[] = $type;
1178      }
1179      return $DB->get_records_sql($sql, $values);
1180  }
1181  
1182  /**
1183   * Return an array of existing exports by type for a given user.
1184   * This is much more lightweight than existing_exports because it only returns the types, rather than the whole serialised data
1185   * so can be used for checking availability of multiple plugins at the same time.
1186   * @see existing_exports
1187   *
1188   * @param int $userid the user to check for
1189   * @return array
1190   */
1191  function portfolio_existing_exports_by_plugin($userid) {
1192      global $DB;
1193      $sql = 'SELECT t.id,i.plugin FROM {portfolio_tempdata} t JOIN {portfolio_instance} i ON t.instance = i.id WHERE t.userid = ? ';
1194      $values = array($userid);
1195      return $DB->get_records_sql_menu($sql, $values);
1196  }
1197  
1198  /**
1199   * Return default common options for {@link format_text()} when preparing a content to be exported.
1200   * It is important not to apply filters and not to clean the HTML in format_text()
1201   *
1202   * @return stdClass
1203   */
1204  function portfolio_format_text_options() {
1205  
1206      $options                = new stdClass();
1207      $options->para          = false;
1208      $options->newlines      = true;
1209      $options->filter        = false;
1210      $options->noclean       = true;
1211      $options->overflowdiv   = false;
1212  
1213      return $options;
1214  }
1215  
1216  /**
1217   * callback function from {@link portfolio_rewrite_pluginfile_urls}
1218   * looks through preg_replace matches and replaces content with whatever the active portfolio export format says
1219   *
1220   * @param int $contextid module context id
1221   * @param string $component module name (eg:mod_assignment)
1222   * @param string $filearea normal file_area arguments
1223   * @param int $itemid component item id
1224   * @param portfolio_format $format exporter format type
1225   * @param array $options extra options to pass through to the file_output function in the format (optional)
1226   * @param array $matches internal matching
1227   * @return object|array|string
1228   */
1229  function portfolio_rewrite_pluginfile_url_callback($contextid, $component, $filearea, $itemid, $format, $options, $matches) {
1230      $matches = $matches[0]; // No internal matching.
1231  
1232      // Loads the HTML.
1233      $dom = new DomDocument();
1234      if (!$dom->loadHTML($matches)) {
1235          return $matches;
1236      }
1237  
1238      // Navigates to the node.
1239      $xpath = new DOMXPath($dom);
1240      $nodes = $xpath->query('/html/body/child::*');
1241      if (empty($nodes) || count($nodes) > 1) {
1242          // Unexpected sequence, none or too many nodes.
1243          return $matches;
1244      }
1245      $dom = $nodes->item(0);
1246  
1247      $attributes = array();
1248      foreach ($dom->attributes as $attr => $node) {
1249          $attributes[$attr] = $node->value;
1250      }
1251      // now figure out the file
1252      $fs = get_file_storage();
1253      $key = 'href';
1254      if (!array_key_exists('href', $attributes) && array_key_exists('src', $attributes)) {
1255          $key = 'src';
1256      }
1257      if (!array_key_exists($key, $attributes)) {
1258          debugging('Couldn\'t find an attribute to use that contains @@PLUGINFILE@@ in portfolio_rewrite_pluginfile');
1259          return $matches;
1260      }
1261      $filename = substr($attributes[$key], strpos($attributes[$key], '@@PLUGINFILE@@') + strlen('@@PLUGINFILE@@'));
1262      $filepath = '/';
1263      if (strpos($filename, '/') !== 0) {
1264          $bits = explode('/', $filename);
1265          $filename = array_pop($bits);
1266          $filepath = implode('/', $bits);
1267      }
1268      if (!$file = $fs->get_file($contextid, $component, $filearea, $itemid, $filepath, urldecode($filename))) {
1269          debugging("Couldn't find a file from the embedded path info context $contextid component $component filearea $filearea itemid $itemid filepath $filepath name $filename");
1270          return $matches;
1271      }
1272      if (empty($options)) {
1273          $options = array();
1274      }
1275      $options['attributes'] = $attributes;
1276      return $format->file_output($file, $options);
1277  }
1278  
1279  /**
1280   * Function to require any potential callback files, throwing exceptions
1281   * if an issue occurs.
1282   *
1283   * @param string $component This is the name of the component in Moodle, eg 'mod_forum'
1284   * @param string $class Name of the class containing the callback functions
1285   *     activity components should ALWAYS use their name_portfolio_caller
1286   *     other locations must use something unique
1287   */
1288  function portfolio_include_callback_file($component, $class = null) {
1289      global $CFG;
1290      require_once($CFG->libdir . '/adminlib.php');
1291  
1292      // It's possible that they are passing a file path rather than passing a component.
1293      // We want to try and convert this to a component name, eg. mod_forum.
1294      $pos = strrpos($component, '/');
1295      if ($pos !== false) {
1296          // Get rid of the first slash (if it exists).
1297          $component = ltrim($component, '/');
1298          // Get a list of valid plugin types.
1299          $plugintypes = core_component::get_plugin_types();
1300          // Assume it is not valid for now.
1301          $isvalid = false;
1302          // Go through the plugin types.
1303          foreach ($plugintypes as $type => $path) {
1304              // Getting the path relative to the dirroot.
1305              $path = preg_replace('|^' . preg_quote($CFG->dirroot, '|') . '/|', '', $path);
1306              if (strrpos($component, $path) === 0) {
1307                  // Found the plugin type.
1308                  $isvalid = true;
1309                  $plugintype = $type;
1310                  $pluginpath = $path;
1311              }
1312          }
1313          // Throw exception if not a valid component.
1314          if (!$isvalid) {
1315              throw new coding_exception('Somehow a non-valid plugin path was passed, could be a hackz0r attempt, exiting.');
1316          }
1317          // Remove the file name.
1318          $component = trim(substr($component, 0, $pos), '/');
1319          // Replace the path with the type.
1320          $component = str_replace($pluginpath, $plugintype, $component);
1321          // Ok, replace '/' with '_'.
1322          $component = str_replace('/', '_', $component);
1323          // Place a debug message saying the third parameter should be changed.
1324          debugging('The third parameter sent to the function set_callback_options should be the component name, not a file path, please update this.', DEBUG_DEVELOPER);
1325      }
1326  
1327      // Check that it is a valid component.
1328      if (!get_component_version($component)) {
1329          throw new portfolio_button_exception('nocallbackcomponent', 'portfolio', '', $component);
1330      }
1331  
1332      // Obtain the component's location.
1333      if (!$componentloc = core_component::get_component_directory($component)) {
1334          throw new portfolio_button_exception('nocallbackcomponent', 'portfolio', '', $component);
1335      }
1336  
1337      // Check if the component contains the necessary file for the portfolio plugin.
1338      // These are locallib.php, portfoliolib.php and portfolio_callback.php.
1339      $filefound = false;
1340      if (file_exists($componentloc . '/locallib.php')) {
1341          $filefound = true;
1342          require_once($componentloc . '/locallib.php');
1343      }
1344      if (file_exists($componentloc . '/portfoliolib.php')) {
1345          $filefound = true;
1346          debugging('Please standardise your plugin by renaming your portfolio callback file to locallib.php, or if that file already exists moving the portfolio functionality there.', DEBUG_DEVELOPER);
1347          require_once ($componentloc . '/portfoliolib.php');
1348      }
1349      if (file_exists($componentloc . '/portfolio_callback.php')) {
1350          $filefound = true;
1351          debugging('Please standardise your plugin by renaming your portfolio callback file to locallib.php, or if that file already exists moving the portfolio functionality there.', DEBUG_DEVELOPER);
1352          require_once($componentloc . '/portfolio_callback.php');
1353      }
1354  
1355      // Ensure that we found a file we can use, if not throw an exception.
1356      if (!$filefound) {
1357          throw new portfolio_button_exception('nocallbackfile', 'portfolio', '', $component);
1358      }
1359  
1360      if (!is_null($class) && !class_exists($class)) {
1361          throw new portfolio_button_exception('nocallbackclass', 'portfolio', '', $class);
1362      }
1363  }
1364  
1365  /**
1366   * Go through all the @@PLUGINFILE@@ matches in some text,
1367   * extract the file information and pass it back to the portfolio export format
1368   * to regenerate the html to output
1369   *
1370   * @param string $text the text to search through
1371   * @param int $contextid normal file_area arguments
1372   * @param string $component module name
1373   * @param string $filearea normal file_area arguments
1374   * @param int $itemid normal file_area arguments
1375   * @param portfolio_format $format the portfolio export format
1376   * @param array $options additional options to be included in the plugin file url (optional)
1377   * @return mixed
1378   */
1379  function portfolio_rewrite_pluginfile_urls($text, $contextid, $component, $filearea, $itemid, $format, $options=null) {
1380      $patterns = array(
1381          '(<(a|A)[^<]*?href="@@PLUGINFILE@@/[^>]*?>.*?</(a|A)>)',
1382          '(<(img|IMG)\s[^<]*?src="@@PLUGINFILE@@/[^>]*?/?>)',
1383      );
1384      $pattern = '~' . implode('|', $patterns) . '~';
1385      $callback = partial('portfolio_rewrite_pluginfile_url_callback', $contextid, $component, $filearea, $itemid, $format, $options);
1386      return preg_replace_callback($pattern, $callback, $text);
1387  }
1388  // this function has to go last, because the regexp screws up syntax highlighting in some editors
1389