Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
core_media_manager Class Reference

Manager for media files. More...

Public Member Functions

 can_embed_url (moodle_url $url, $options=array())
 Checks whether a file can be embedded.
 
 can_embed_urls (array $urls, $options=array())
 Checks whether a file can be embedded.
 
 embed_alternatives ($alternatives, $name='', $width=0, $height=0, $options=array())
 Renders media files (audio or video) using suitable embedded player.
 
 embed_url (moodle_url $url, $name='', $width=0, $height=0, $options=array())
 Renders a media file (audio or video) using suitable embedded player.
 
 get_embeddable_markers ()
 Obtains a list of markers that can be used in a regular expression when searching for URLs that can be embedded by any player type.
 
 get_extension (moodle_url $url)
 Returns the file extension for a URL.
 
 get_filename (moodle_url $url)
 Obtains the filename from the moodle_url.
 
 get_mimetype (moodle_url $url)
 Guesses MIME type for a moodle_url based on file extension.
 
 setup ()
 
 split_alternatives ($combinedurl, &$width, &$height)
 Given a string containing multiple URLs separated by #, this will split it into an array of moodle_url objects suitable for using when calling embed_alternatives.
 

Static Public Member Functions

static instance ($page=null)
 Returns a singleton instance of a manager.
 
static reset_caches ()
 Resets cached singleton instance.
 

Public Attributes

const OPTION_BLOCK = 'block'
 Option: Put a div around the output (if not blank) so that it displays as a block using the 'resourcecontent' CSS class.
 
const OPTION_FALLBACK_TO_BLANK = 'embedorblank'
 Option: When embedding, if there is no matching embed, do not use the default link fallback player; instead return blank.
 
const OPTION_NO_LINK = 'nolink'
 Option: Disable text link fallback.
 
const OPTION_ORIGINAL_TEXT = 'originaltext'
 Option: When the request for media players came from a text filter this option will contain the original HTML snippet, usually one of the tags: or <video> or <audio>
 
const OPTION_TRUSTED = 'trusted'
 Option: Enable players which are only suitable for use when we trust the user who embedded the content.
 

Detailed Description

Manager for media files.

Used in file resources, media filter, and any other places that need to output embedded media.

Usage: $manager = core_media_manager\instance();

Author
2011 The Open University
License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ can_embed_url()

core_media_manager::can_embed_url ( moodle_url $url,
$options = array() )

Checks whether a file can be embedded.

If this returns true you will get an embedded player; if this returns false, you will just get a download link.

This is a wrapper for can_embed_urls.

Parameters
moodle_url$urlURL of media file
array$optionsOptions (same as when embedding)
Return values
boolTrue if file can be embedded

◆ can_embed_urls()

core_media_manager::can_embed_urls ( array $urls,
$options = array() )

Checks whether a file can be embedded.

If this returns true you will get an embedded player; if this returns false, you will just get a download link.

Parameters
array$urlsURL of media file and any alternatives (moodle_url)
array$optionsOptions (same as when embedding)
Return values
boolTrue if file can be embedded

◆ embed_alternatives()

core_media_manager::embed_alternatives ( $alternatives,
$name = '',
$width = 0,
$height = 0,
$options = array() )

Renders media files (audio or video) using suitable embedded player.

The list of URLs should be alternative versions of the same content in multiple formats. If there is only one format it should have a single entry.

If the media files are not in a supported format, this will give students a download link to each format. The download link uses the filename unless you supply the optional name parameter.

Width and height are optional. If specified, these are suggested sizes and should be the exact values supplied by the user, if they come from user input. These will be treated as relating to the size of the video content, not including any player control bar.

For audio files, height will be ignored. For video files, a few formats work if you specify only width, but in general if you specify width you must specify height as well.

The $options array is passed through to the core_media_player classes that render the object tag. The keys can contain values from core_media\OPTION_xx.

Parameters
array$alternativesArray of moodle_url to media files
string$nameOptional user-readable name to display in download link
int$widthWidth in pixels (optional)
int$heightHeight in pixels (optional)
array$optionsArray of key/value pairs
Return values
stringHTML content of embed

◆ embed_url()

core_media_manager::embed_url ( moodle_url $url,
$name = '',
$width = 0,
$height = 0,
$options = array() )

Renders a media file (audio or video) using suitable embedded player.

See embed_alternatives function for full description of parameters. This function calls through to that one.

When using this function you can also specify width and height in the URL by including ?d=100x100 at the end. If specified in the URL, this will override the $width and $height parameters.

Parameters
moodle_url$urlFull URL of media file
string$nameOptional user-readable name to display in download link
int$widthWidth in pixels (optional)
int$heightHeight in pixels (optional)
array$optionsArray of key/value pairs
Return values
stringHTML content of embed

◆ get_embeddable_markers()

core_media_manager::get_embeddable_markers ( )

Obtains a list of markers that can be used in a regular expression when searching for URLs that can be embedded by any player type.

This string is used to improve peformance of regex matching by ensuring that the (presumably C) regex code can do a quick keyword check on the URL part of a link to see if it matches one of these, rather than having to go into PHP code for every single link to see if it can be embedded.

Return values
stringString suitable for use in regex such as '(::.mp4|.flv)'

◆ get_extension()

core_media_manager::get_extension ( moodle_url $url)

Returns the file extension for a URL.

Parameters
moodle_url$urlURL

◆ get_filename()

core_media_manager::get_filename ( moodle_url $url)

Obtains the filename from the moodle_url.

Parameters
moodle_url$urlURL
Return values
stringFilename only (not escaped)

◆ get_mimetype()

core_media_manager::get_mimetype ( moodle_url $url)

Guesses MIME type for a moodle_url based on file extension.

Parameters
moodle_url$urlURL
Return values
stringMIME type

◆ instance()

static core_media_manager::instance ( $page = null)
static

Returns a singleton instance of a manager.

Note as of Moodle 3.3, this will call setup for you.

Return values
core_media_manager

◆ reset_caches()

static core_media_manager::reset_caches ( )
static

Resets cached singleton instance.

To be used after $CFG->media_plugins_sortorder is modified

◆ setup()

core_media_manager::setup ( )
Deprecated
since Moodle 3.3. The setup is now done in instance() so there is no need to call this.

◆ split_alternatives()

core_media_manager::split_alternatives ( $combinedurl,
& $width,
& $height )

Given a string containing multiple URLs separated by #, this will split it into an array of moodle_url objects suitable for using when calling embed_alternatives.

Note that the input string should NOT be html-escaped (i.e. if it comes from html, call html_entity_decode first).

Parameters
string$combinedurlString of 1 or more alternatives separated by #
int$widthOutput variable: width (will be set to 0 if not specified)
int$heightOutput variable: height (0 if not specified)
Return values
arrayArray of 1 or more moodle_url objects

Member Data Documentation

◆ OPTION_BLOCK

const core_media_manager::OPTION_BLOCK = 'block'

Option: Put a div around the output (if not blank) so that it displays as a block using the 'resourcecontent' CSS class.

To enable, set value to true.

◆ OPTION_FALLBACK_TO_BLANK

const core_media_manager::OPTION_FALLBACK_TO_BLANK = 'embedorblank'

Option: When embedding, if there is no matching embed, do not use the default link fallback player; instead return blank.

This is different from OPTION_NO_LINK because this option still uses the fallback link if there is some kind of embedding. Use this option if you are going to check if the return value is blank and handle it specially.

To enable, set value to true.

◆ OPTION_NO_LINK

const core_media_manager::OPTION_NO_LINK = 'nolink'

Option: Disable text link fallback.

Use this option if you are going to print a visible link anyway so it is pointless to have one as fallback.

To enable, set value to true.

◆ OPTION_ORIGINAL_TEXT

const core_media_manager::OPTION_ORIGINAL_TEXT = 'originaltext'

Option: When the request for media players came from a text filter this option will contain the original HTML snippet, usually one of the tags: or <video> or <audio>

Players that support other HTML5 features such as tracks may find them in this option.

◆ OPTION_TRUSTED

const core_media_manager::OPTION_TRUSTED = 'trusted'

Option: Enable players which are only suitable for use when we trust the user who embedded the content.

In the past, this option enabled the SWF player (which was removed). However, this setting will remain because it might be used by third-party plugins.

To enable, set value to true.


The documentation for this class was generated from the following file: