Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 3.9.x will end* 10 May 2021 (12 months).
  • Bug fixes for security issues in 3.9.x will end* 8 May 2023 (36 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
/lib/ -> filterlib.php (source)

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

Library functions for managing text filter plugins.

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

Defines 5 classes

filter_manager:: (14 methods):
  __construct()
  instance()
  reset_caches()
  unload_all_filters()
  load_filters()
  make_filter_object()
  apply_filter_chain()
  get_text_filters()
  get_string_filters()
  filter_text()
  filter_string()
  text_filtering_hash()
  setup_page_for_filters()
  setup_page_for_globally_available_filters()

null_filter_manager:: (3 methods):
  filter_text()
  filter_string()
  text_filtering_hash()

performance_measuring_filter_manager:: (5 methods):
  unload_all_filters()
  make_filter_object()
  filter_text()
  filter_string()
  get_performance_summary()

moodle_text_filter:: (7 methods):
  __construct()
  hash()
  setup()
  filter_stage_pre_format()
  filter_stage_pre_clean()
  filter_stage_post_clean()
  filter_stage_string()

filterobject:: (32 methods):
  __construct()
  filter_get_name()
  filter_get_all_installed()
  filter_set_global_state()
  filter_get_active_state()
  filter_is_enabled()
  filter_get_globally_enabled()
  filter_get_globally_enabled_filters_with_config()
  filter_get_string_filters()
  filter_set_applies_to_strings()
  filter_set_local_state()
  filter_set_local_config()
  filter_unset_local_config()
  filter_get_local_config()
  filter_get_all_local_settings()
  filter_get_active_in_context()
  filter_preload_activities()
  filter_get_available_in_context()
  filter_get_global_states()
  filter_delete_all_for_filter()
  filter_delete_all_for_context()
  filter_has_global_settings()
  filter_has_local_settings()
  filter_context_may_have_filter_settings()
  filter_phrases()
  filter_prepare_phrases_for_filtering()
  filter_prepare_phrase_for_replacement()
  filter_remove_duplicates()
  filter_save_ignore_tags()
  filter_save_tags()
  filter_add_javascript()
  openpopup()


Class: filter_manager  - X-Ref

Class to manage the filtering of strings. It is intended that this class is
only used by weblib.php. Client code should probably be using the
format_text and format_string functions.

This class is a singleton.

__construct()   X-Ref
Constructor. Protected. Use {@link instance()} instead.


instance()   X-Ref
Factory method. Use this to get the filter manager.

return: filter_manager the singleton instance.

reset_caches()   X-Ref
Resets the caches, usually to be called between unit tests


unload_all_filters()   X-Ref
Unloads all filters and other cached information


load_filters($context)   X-Ref
Load all the filters required by this context.

param: context $context the context.

make_filter_object($filtername, $context, $localconfig)   X-Ref
Factory method for creating a filter.

param: string $filtername The filter name, for example 'tex'.
param: context $context context object.
param: array $localconfig array of local configuration variables for this filter.
return: moodle_text_filter The filter, or null, if this type of filter is

apply_filter_chain($text, $filterchain, array $options = array()   X-Ref
Apply a list of filters to some content.

param: string $text
param: moodle_text_filter[] $filterchain array filter name => filter object.
param: array $options options passed to the filters.
param: array $skipfilters of filter names. Any filters that should not be applied to this text.
return: string $text

get_text_filters($context)   X-Ref
Get all the filters that apply to a given context for calls to format_text.

param: context $context
return: moodle_text_filter[] A text filter

get_string_filters($context)   X-Ref
Get all the filters that apply to a given context for calls to format_string.

param: context $context the context.
return: moodle_text_filter[] A text filter

filter_text($text, $context, array $options = array()   X-Ref
Filter some text

param: string $text The text to filter
param: context $context the context.
param: array $options options passed to the filters
param: array $skipfilters of filter names. Any filters that should not be applied to this text.
return: string resulting text

filter_string($string, $context)   X-Ref
Filter a piece of string

param: string $string The text to filter
param: context $context the context.
return: string resulting string

text_filtering_hash()   X-Ref


setup_page_for_filters($page, $context)   X-Ref
Setup page with filters requirements and other prepare stuff.

This method is used by {@see format_text()} and {@see format_string()}
in order to allow filters to setup any page requirement (js, css...)
or perform any action needed to get them prepared before filtering itself
happens by calling to each every active setup() method.

Note it's executed for each piece of text filtered, so filter implementations
are responsible of controlling the cardinality of the executions that may
be different depending of the stuff to prepare.

param: moodle_page $page the page we are going to add requirements to.
param: context $context the context which contents are going to be filtered.

setup_page_for_globally_available_filters($page)   X-Ref
Setup the page for globally available filters.

This helps setting up the page for filters which may be applied to
the page, even if they do not belong to the current context, or are
not yet visible because the content is lazily added (ajax). This method
always uses to the system context which determines the globally
available filters.

This should only ever be called once per request.

param: moodle_page $page The page.

Class: null_filter_manager  - X-Ref

Filter manager subclass that does nothing. Having this simplifies the logic
of format_text, etc.

filter_text($text, $context, array $options = array()   X-Ref
As for the equivalent {@link filter_manager} method.

param: string $text The text to filter
param: context $context not used.
param: array $options not used
param: array $skipfilters not used
return: string resulting text.

filter_string($string, $context)   X-Ref
As for the equivalent {@link filter_manager} method.

param: string $string The text to filter
param: context $context not used.
return: string resulting string

text_filtering_hash()   X-Ref
As for the equivalent {@link filter_manager} method.


Class: performance_measuring_filter_manager  - X-Ref

Filter manager subclass that tracks how much work it does.

unload_all_filters()   X-Ref
No description

make_filter_object($filtername, $context, $localconfig)   X-Ref
No description

filter_text($text, $context, array $options = array()   X-Ref
No description

filter_string($string, $context)   X-Ref
No description

get_performance_summary()   X-Ref
Return performance information, in the form required by {@link get_performance_info()}.

return: array the performance info.

Class: moodle_text_filter  - X-Ref

Base class for text filters. You just need to override this class and
implement the filter method.

__construct($context, array $localconfig)   X-Ref
Set any context-specific configuration for this filter.

param: context $context The current context.
param: array $localconfig Any context-specific configuration for this filter.

hash()   X-Ref


setup($page, $context)   X-Ref
Setup page with filter requirements and other prepare stuff.

Override this method if the filter needs to setup page
requirements or needs other stuff to be executed.

Note this method is invoked from {@see setup_page_for_filters()}
for each piece of text being filtered, so it is responsible
for controlling its own execution cardinality.

param: moodle_page $page the page we are going to add requirements to.
param: context $context the context which contents are going to be filtered.

filter_stage_pre_format(string $text, array $options)   X-Ref
Filter text before changing format to HTML.

param: string $text
param: array $options
return: string

filter_stage_pre_clean(string $text, array $options)   X-Ref
Filter HTML text before sanitising text.

NOTE: this is called even if $options['noclean'] is true and text is not cleaned.

param: string $text
param: array $options
return: string

filter_stage_post_clean(string $text, array $options)   X-Ref
Filter HTML text at the very end after text is sanitised.

NOTE: this is called even if $options['noclean'] is true and text is not cleaned.

param: string $text
param: array $options
return: string

filter_stage_string(string $text, array $options)   X-Ref
Filter simple text coming from format_string().

Note that unless $CFG->formatstringstriptags is disabled
HTML tags are not expected in returned value.

param: string $text
param: array $options
return: string

Class: filterobject  - X-Ref

This is just a little object to define a phrase and some instructions
for how to process it.  Filters can create an array of these to pass
to the @{link filter_phrases()} function below.

Note that although the fields here are public, you almost certainly should
never use that. All that is supported is contructing new instances of this
class, and then passing an array of them to filter_phrases.

__construct($phrase, $hreftagbegin = '<span class="highlight">',$hreftagend = '</span>',$casesensitive = false,$fullmatch = false,$replacementphrase = null,$replacementcallback = null,array $replacementcallbackdata = null)   X-Ref
Constructor.

param: string $phrase this is the phrase that should be matched.
param: string $hreftagbegin HTML to insert before any match. Default '<span class="highlight">'.
param: string $hreftagend HTML to insert after any match. Default '</span>'.
param: bool $casesensitive whether the match needs to be case sensitive
param: bool $fullmatch whether to match complete words. If true, 'T' won't be matched in 'Tim'.
param: mixed $replacementphrase replacement text to go inside begin and end. If not set,
param: callback $replacementcallback if set, then this will be called just before
param: array $replacementcallbackdata data to be passed to $replacementcallback (optional).

filter_get_name($filter)   X-Ref
Look up the name of this filter

param: string $filter the filter name
return: string the human-readable name for this filter.

filter_get_all_installed()   X-Ref
Get the names of all the filters installed in this Moodle.

return: array path => filter name from the appropriate lang file. e.g.

filter_set_global_state($filtername, $state, $move = 0)   X-Ref
Set the global activated state for a text filter.

param: string $filtername The filter name, for example 'tex'.
param: int $state One of the values TEXTFILTER_ON, TEXTFILTER_OFF or TEXTFILTER_DISABLED.
param: int $move -1 means up, 0 means the same, 1 means down

filter_get_active_state(string $filtername, $contextid = null)   X-Ref
Returns the active state for a filter in the given context.

param: string $filtername The filter name, for example 'tex'.
param: integer $contextid The id of the context to get the data for.
return: int value of active field for the given filter.

filter_is_enabled($filtername)   X-Ref

param: string $filtername The filter name, for example 'tex'.
return: boolean is this filter allowed to be used on this site. That is, the

filter_get_globally_enabled()   X-Ref
Return a list of all the filters that may be in use somewhere.

return: array where the keys and values are both the filter name, like 'tex'.

filter_get_globally_enabled_filters_with_config()   X-Ref
Get the globally enabled filters.

This returns the filters which could be used in any context. Essentially
the filters which are not disabled for the entire site.

return: array Keys are filter names, and values the config.

filter_get_string_filters()   X-Ref
Return the names of the filters that should also be applied to strings
(when they are enabled).

return: array where the keys and values are both the filter name, like 'tex'.

filter_set_applies_to_strings($filter, $applytostrings)   X-Ref
Sets whether a particular active filter should be applied to all strings by
format_string, or just used by format_text.

param: string $filter The filter name, for example 'tex'.
param: boolean $applytostrings if true, this filter will apply to format_string

filter_set_local_state($filter, $contextid, $state)   X-Ref
Set the local activated state for a text filter.

param: string $filter The filter name, for example 'tex'.
param: integer $contextid The id of the context to get the local config for.
param: integer $state One of the values TEXTFILTER_ON, TEXTFILTER_OFF or TEXTFILTER_INHERIT.
return: void

filter_set_local_config($filter, $contextid, $name, $value)   X-Ref
Set a particular local config variable for a filter in a context.

param: string $filter The filter name, for example 'tex'.
param: integer $contextid The id of the context to get the local config for.
param: string $name the setting name.
param: string $value the corresponding value.

filter_unset_local_config($filter, $contextid, $name)   X-Ref
Remove a particular local config variable for a filter in a context.

param: string $filter The filter name, for example 'tex'.
param: integer $contextid The id of the context to get the local config for.
param: string $name the setting name.

filter_get_local_config($filter, $contextid)   X-Ref
Get local config variables for a filter in a context. Normally (when your
filter is running) you don't need to call this, becuase the config is fetched
for you automatically. You only need this, for example, when you are getting
the config so you can show the user an editing from.

param: string $filter The filter name, for example 'tex'.
param: integer $contextid The ID of the context to get the local config for.
return: array of name => value pairs.

filter_get_all_local_settings($contextid)   X-Ref
This function is for use by backup. Gets all the filter information specific
to one context.

param: int $contextid
return: array Array with two elements. The first element is an array of objects with

filter_get_active_in_context($context)   X-Ref
Get the list of active filters, in the order that they should be used
for a particular context, along with any local configuration variables.

param: context $context a context
return: array an array where the keys are the filter names, for example

filter_preload_activities(course_modinfo $modinfo)   X-Ref
Preloads the list of active filters for all activities (modules) on the course
using two database queries.

param: course_modinfo $modinfo Course object from get_fast_modinfo

filter_get_available_in_context($context)   X-Ref
List all of the filters that are available in this context, and what the
local and inherited states of that filter are.

param: context $context a context that is not the system context.
return: array an array with filter names, for example 'tex'

filter_get_global_states()   X-Ref
This function is for use by the filter administration page.

return: array 'filtername' => object with fields 'filter' (=filtername), 'active' and 'sortorder'

filter_delete_all_for_filter($filter)   X-Ref
Delete all the data in the database relating to a filter, prior to deleting it.

param: string $filter The filter name, for example 'tex'.

filter_delete_all_for_context($contextid)   X-Ref
Delete all the data in the database relating to a context, used when contexts are deleted.

param: integer $contextid The id of the context being deleted.

filter_has_global_settings($filter)   X-Ref
Does this filter have a global settings page in the admin tree?
(The settings page for a filter must be called, for example, filtersettingfiltertex.)

param: string $filter The filter name, for example 'tex'.
return: boolean Whether there should be a 'Settings' link on the config page.

filter_has_local_settings($filter)   X-Ref
Does this filter have local (per-context) settings?

param: string $filter The filter name, for example 'tex'.
return: boolean Whether there should be a 'Settings' link on the manage filters in context page.

filter_context_may_have_filter_settings($context)   X-Ref
Certain types of context (block and user) may not have local filter settings.
the function checks a context to see whether it may have local config.

param: object $context a context.
return: boolean whether this context may have local filter settings.

filter_phrases($text, $linkarray, $ignoretagsopen = null, $ignoretagsclose = null,$overridedefaultignore = false, $linkarrayalreadyprepared = false)   X-Ref
Process phrases intelligently found within a HTML text (such as adding links).

param: string $text            the text that we are filtering
param: filterobject[] $linkarray an array of filterobjects
param: array $ignoretagsopen   an array of opening tags that we should ignore while filtering
param: array $ignoretagsclose  an array of corresponding closing tags
param: bool $overridedefaultignore True to only use tags provided by arguments
param: bool $linkarrayalreadyprepared True to say that filter_prepare_phrases_for_filtering
return: string

filter_prepare_phrases_for_filtering(array $linkarray)   X-Ref
No description

filter_prepare_phrase_for_replacement(filterobject $linkobject)   X-Ref
Fill in the remaining ->work... fields, that would be needed to replace the phrase.

param: filterobject $linkobject the link object on which to set additional fields.

filter_remove_duplicates($linkarray)   X-Ref
Remove duplicate from a list of {@link filterobject}.

param: filterobject[] $linkarray a list of filterobject.
return: filterobject[] the same list, but with dupicates removed.

filter_save_ignore_tags(&$text, $filterignoretagsopen, $filterignoretagsclose, &$ignoretags)   X-Ref
Extract open/lose tags and their contents to avoid being processed by filters.
Useful to extract pieces of code like <a>...</a> tags. It returns the text
converted with some <#xTEXTFILTER_EXCL_SEPARATORx#> codes replacing the extracted text. Such extracted
texts are returned in the ignoretags array (as values), with codes as keys.

param: string $text                  the text that we are filtering (in/out)
param: array $filterignoretagsopen  an array of open tags to start searching
param: array $filterignoretagsclose an array of close tags to end searching
param: array $ignoretags            an array of saved strings useful to rebuild the original text (in/out)

filter_save_tags(&$text, &$tags)   X-Ref
Extract tags (any text enclosed by < and > to avoid being processed by filters.
It returns the text converted with some <%xTEXTFILTER_EXCL_SEPARATORx%> codes replacing the extracted text. Such extracted
texts are returned in the tags array (as values), with codes as keys.

param: string $text   the text that we are filtering (in/out)
param: array $tags   an array of saved strings useful to rebuild the original text (in/out)

filter_add_javascript($text)   X-Ref
Add missing openpopup javascript to HTML files.

param: string $text
return: string

openpopup(url,name,options,fullscreen)   X-Ref
No description