Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

This file contains all global functions to do with manipulating portfolios. Everything else that is logically namespaced by class is in its own file in lib/portfolio/ directory.

Copyright: 1999 onwards Martin Dougiamas {@link http://moodle.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1372 lines (55 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 1 file
 lib/portfoliolib.php

Defines 1 class


Class: portfolio_add_button  - X-Ref

Use this to add a portfolio button or icon or form to a page.

These class methods do not check permissions. the caller must check permissions first.
Later, during the export process, the caller class is instantiated and the check_permissions method is called
If you are exporting a single file, you should always call set_format_by_file($file)
This class can be used like this:
<code>
$button = new portfolio_add_button();
$button->set_callback_options('name_of_caller_class', array('id' => 6), 'yourcomponent'); eg. mod_forum
$button->render(PORTFOLIO_ADD_FULL_FORM, get_string('addeverythingtoportfolio', 'yourcomponent'));
</code>
or like this:
<code>
$button = new portfolio_add_button(array('callbackclass' => 'name_of_caller_class', 'callbackargs' => array('id' => 6), 'callbackcomponent' => 'yourcomponent')); eg. mod_forum
$somehtml .= $button->to_html(PORTFOLIO_ADD_TEXT_LINK);
</code>

__construct($options=null)   X-Ref
Constructor. Either pass the options here or set them using the helper methods.
Generally the code will be clearer if you use the helper methods.

param: array $options keyed array of options:

set_callback_options($class, array $argarray, $component)   X-Ref
Function to set the callback options

param: string $class Name of the class containing the callback functions
param: array $argarray This can be an array or hash of arguments to pass
param: string $component This is the name of the component in Moodle, eg 'mod_forum'

set_formats($formats=null)   X-Ref
Sets the available export formats for this content.
This function will also poll the static function in the caller class
and make sure we're not overriding a format that has nothing to do with mimetypes.
Eg: if you pass IMAGE here but the caller can export LEAP2A it will keep LEAP2A as well.

param: array $formats if the calling code knows better than the static method on the calling class (base_supported_formats).

reset_formats()   X-Ref
Reset formats to the default,
which is usually what base_supported_formats returns


set_format_by_file(stored_file $file, $extraformats=null)   X-Ref
If we already know we have exactly one file,
bypass set_formats and just pass the file
so we can detect the formats by mimetype.

param: stored_file $file file to set the format from
param: array $extraformats any additional formats other than by mimetype

set_format_by_intended_file($extn, $extraformats=null)   X-Ref
Correllary this is use to set_format_by_file, but it is also used when there is no stored_file and
when we're writing out a new type of file (like csv or pdf)

param: string $extn the file extension we intend to generate
param: array  $extraformats any additional formats other than by mimetype

render($format=null, $addstr=null)   X-Ref
Echo the form/button/icon/text link to the page

param: int $format format to display the button or form or icon or link.
param: string $addstr string to use for the button or icon alt text or link text.

to_html($format=null, $addstr=null)   X-Ref
Returns the form/button/icon/text link as html

param: int $format format to display the button or form or icon or link.
param: string $addstr string to use for the button or icon alt text or link text.
return: void|string|moodle_url

is_renderable()   X-Ref
Perform some internal checks.
These are not errors, just situations
where it's not appropriate to add the button

return: bool

get_formats()   X-Ref
Getter for $format property

return: array

get_callbackargs()   X-Ref
Getter for $callbackargs property

return: array

get_callbackcomponent()   X-Ref
Getter for $callbackcomponent property

return: string

get_callbackclass()   X-Ref
Getter for $callbackclass property

return: string

portfolio_instance_select($instances, $callerformats, $callbackclass, $mimetype=null, $selectname='instance', $return=false, $returnarray=false)   X-Ref
Returns a drop menu with a list of available instances.

param: array          $instances      array of portfolio plugin instance objects - the instances to put in the menu
param: array          $callerformats  array of PORTFOLIO_FORMAT_XXX constants - the formats the caller supports (this is used to filter plugins)
param: string         $callbackclass  the callback class name - used for debugging only for when there are no common formats
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.
param: string         $selectname     the name of the select element. Optional, defaults to instance.
param: bool           $return         whether to print or return the output. Optional, defaults to print.
param: bool           $returnarray    if returning, whether to return the HTML or the array of options. Optional, defaults to HTML.
return: void|array|string the html, from <select> to </select> inclusive.

portfolio_instances($visibleonly=true, $useronly=true)   X-Ref
Return all portfolio instances

param: bool $visibleonly Don't include hidden instances. Defaults to true and will be overridden to true if the next parameter is true
param: bool $useronly    Check the visibility preferences and permissions of the logged in user. Defaults to true.
return: array of portfolio instances (full objects, not just database records)

portfolio_has_visible_instances()   X-Ref
Return whether there are visible instances in portfolio.

return: bool true when there are some visible instances.

portfolio_supported_formats()   X-Ref
Supported formats currently in use.
Canonical place for a list of all formats
that portfolio plugins and callers
can use for exporting content

return: array keyed array of all the available export formats (constant => classname)

portfolio_format_from_mimetype($mimetype)   X-Ref
Deduce export format from file mimetype
This function returns the revelant portfolio export format
which is used to determine which portfolio plugins can be used
for exporting this content
according to the given mime type
this only works when exporting exactly <b>one</b> file, or generating a new one
(like a pdf or csv export)

param: string $mimetype (usually $file->get_mimetype())
return: string the format constant (see PORTFOLIO_FORMAT_XXX constants)

portfolio_supported_formats_intersect($callerformats, $pluginformats)   X-Ref
Intersection of plugin formats and caller formats.
Walks both the caller formats and portfolio plugin formats
and looks for matches (walking the hierarchy as well)
and returns the intersection

param: array $callerformats formats the caller supports
param: array $pluginformats formats the portfolio plugin supports
return: array

portfolio_format_is_abstract($format)   X-Ref
Tiny helper to figure out whether a portfolio format is abstract

param: string $format the format to test
return: bool

portfolio_most_specific_formats($specificformats, $generalformats)   X-Ref
Return the combination of the two arrays of formats with duplicates in terms of specificity removed
and also removes conflicting formats.
Use case: a module is exporting a single file, so the general formats would be FILE and MBKP
while the specific formats would be the specific subclass of FILE based on mime (say IMAGE)
and this function would return IMAGE and MBKP

param: array $specificformats array of more specific formats (eg based on mime detection)
param: array $generalformats  array of more general formats (usually more supported)
return: array merged formats with dups removed

portfolio_format_object($name)   X-Ref
Helper function to return a format object from the constant

param: string $name the constant PORTFOLIO_FORMAT_XXX
return: portfolio_format

portfolio_instance($instanceid, $record=null)   X-Ref
Helper function to return an instance of a plugin (with config loaded)

param: int   $instanceid id of instance
param: object $record database row that corresponds to this instance
return: object of portfolio_plugin_XXX

portfolio_static_function($plugin, $function)   X-Ref
Helper function to call a static function on a portfolio plugin class.
This will figure out the classname and require the right file and call the function.
You can send a variable number of arguments to this function after the first two
and they will be passed on to the function you wish to call.

param: string $plugin   name of plugin
param: string $function function to call
return: mixed

portfolio_plugin_sanity_check($plugins=null)   X-Ref
Helper function to check all the plugins for sanity and set any insane ones to invisible.

param: array $plugins array of supported plugin types
return: array array of insane instances (keys= id, values = reasons (keys for plugin lang)

portfolio_instance_sanity_check($instances=null)   X-Ref
Helper function to check all the instances for sanity and set any insane ones to invisible.

param: array $instances array of plugin instances
return: array array of insane instances (keys= id, values = reasons (keys for plugin lang)

portfolio_report_insane($insane, $instances=false, $return=false)   X-Ref
Helper function to display a table of plugins (or instances) and reasons for disabling

param: array $insane array of portfolio plugin
param: array $instances if reporting instances rather than whole plugins, pass the array (key = id, value = object) here
param: bool $return option to deliver the report in html format or print it out directly to the page.
return: void|string of portfolio report in html table format

portfolio_export_rethrow_exception($exporter, $exception)   X-Ref
Helper function to rethrow a caught portfolio_exception as an export exception.
Used because when a portfolio_export exception is thrown the export is cancelled
throws portfolio_export_exceptiog

param: portfolio_exporter $exporter  current exporter object
param: object             $exception exception to rethrow

portfolio_expected_time_file($totest)   X-Ref
Try and determine expected_time for purely file based exports
or exports that might include large file attachments.

param: stored_file|array $totest - either an array of stored_file objects or a single stored_file object
return: string PORTFOLIO_TIME_XXX

portfolio_filesize_info()   X-Ref
The default filesizes and threshold information for file based transfers.
This shouldn't need to be used outside the admin pages and the portfolio code

return: array

portfolio_expected_time_db($recordcount)   X-Ref
Try and determine expected_time for purely database based exports
or exports that might include large parts of a database.

param: int $recordcount number of records trying to export
return: string PORTFOLIO_TIME_XXX

portfolio_insane_notify_admins($insane, $instances=false)   X-Ref
Function to send portfolio report to admins

param: array $insane array of insane plugins
param: array $instances (optional) if reporting instances rather than whole plugins

portfolio_export_pagesetup($PAGE, $caller)   X-Ref
Setup page export

param: moodle_page $PAGE global variable from page object
param: portfolio_caller_base $caller plugin type caller

portfolio_export_type_to_id($type, $userid)   X-Ref
Get export type id

param: string $type plugin type
param: int $userid the user to check for
return: mixed|bool

portfolio_existing_exports($userid, $type=null)   X-Ref
Return a list of current exports for the given user.
This will not go through and call rewaken_object, because it's heavy.
It's really just used to figure out what exports are currently happening.
This is useful for plugins that don't support multiple exports per session

param: int $userid the user to check for
param: string $type (optional) the portfolio plugin to filter by
return: array

portfolio_existing_exports_by_plugin($userid)   X-Ref
Return an array of existing exports by type for a given user.
This is much more lightweight than existing_exports because it only returns the types, rather than the whole serialised data
so can be used for checking availability of multiple plugins at the same time.

param: int $userid the user to check for
return: array

portfolio_format_text_options()   X-Ref
Return default common options for {@link format_text()} when preparing a content to be exported.
It is important not to apply filters and not to clean the HTML in format_text()

return: stdClass

portfolio_rewrite_pluginfile_url_callback($contextid, $component, $filearea, $itemid, $format, $options, $matches)   X-Ref
callback function from {@link portfolio_rewrite_pluginfile_urls}
looks through preg_replace matches and replaces content with whatever the active portfolio export format says

param: int $contextid module context id
param: string $component module name (eg:mod_assignment)
param: string $filearea normal file_area arguments
param: int $itemid component item id
param: portfolio_format $format exporter format type
param: array $options extra options to pass through to the file_output function in the format (optional)
param: array $matches internal matching
return: object|array|string

portfolio_include_callback_file($component, $class = null)   X-Ref
Function to require any potential callback files, throwing exceptions
if an issue occurs.

param: string $component This is the name of the component in Moodle, eg 'mod_forum'
param: string $class Name of the class containing the callback functions

portfolio_rewrite_pluginfile_urls($text, $contextid, $component, $filearea, $itemid, $format, $options=null)   X-Ref
Go through all the @@PLUGINFILE@@ matches in some text,
extract the file information and pass it back to the portfolio export format
to regenerate the html to output

param: string $text the text to search through
param: int $contextid normal file_area arguments
param: string $component module name
param: string $filearea normal file_area arguments
param: int $itemid normal file_area arguments
param: portfolio_format $format the portfolio export format
param: array $options additional options to be included in the plugin file url (optional)
return: mixed