Utility functions for the external API. More...

Static Public Member Functions
static	delete_service_descriptions (string $component)
	Delete all pre-built services, related tokens, and external functions information defined for the specified component.

static	format_string ( $content, $context, $striplinks=true, $options=[])
	Format the string to be returned properly as requested by the either the web service server, either by an internally call.

static	format_text ( $text, $textformat, $context, $component=null, $filearea=null, $itemid=null, $options=null)
	Format the text to be returned properly as requested by the either the web service server, either by an internally call.

static	generate_token (int $tokentype, stdClass $service, int $userid, context $context, int $validuntil=0, string $iprestriction='', string $name='')
	Create and return a session linked token.

static	generate_token_for_current_user (stdClass $service)
	Generate or return an existing token for the current authenticated user.

static	generate_token_name ()
	Generate token name.

static	get_area_files ($contextid, $component, $filearea, $itemid=false, $useitemidinurl=true)
	Returns all area files (optionally limited by itemid).

static	get_service_by_id (int $serviceid)
	Get a service by its id.

static	get_service_by_name (string $name)
	Get a service by its name.

static	log_token_request (stdClass $token)
	Set the last time a token was sent and trigger the core\event\webservice_token_sent event.

static	validate_courses ( $courseids, $courses=[], $addcontext=false, $keepfails=false)
	Validate a list of courses, returning the complete course objects for valid courses.

static	validate_format ($format)
	Validate text field format against known FORMAT_XXX.

Detailed Description

Utility functions for the external API.

Copyright: 2015 Juan Leyva

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ delete_service_descriptions()

static core_external\util::delete_service_descriptions ( string $component )

static

Delete all pre-built services, related tokens, and external functions information defined for the specified component.

Parameters

string $component The frankenstyle component name

◆ format_string()

static core_external\util::format_string	(	$content,
		$context,
		$striplinks = true,
		$options = [] )

static

Format the string to be returned properly as requested by the either the web service server, either by an internally call.

The caller can change the format (raw) with the settings singleton All web service servers must set this singleton when parsing the $_GET and $_POST.

Options are the same that in {See also
 format_string()} with some changes:
     filter      : Can be set to false to force filters off, else observes {

 settings}.

Parameters

  
    string | null $content The string to be filtered. Should be plain text, expect
possibly for multilang tags.

    context $context The id of the context for the string or the context (affects filters).

    boolean $striplinks To strip any link in the result text. Moodle 1.8 default changed from false to true! MDL-8713

    array $options options array/object or courseid

  
  

Return values

  
    string text

◆ format_text()

static core_external\util::format_text	(	$text,
		$textformat,
		$context,
		$component = null,
		$filearea = null,
		$itemid = null,
		$options = null )

static

Format the text to be returned properly as requested by the either the web service server, either by an internally call.

The caller can change the format (raw, filter, file, fileurl) with the core_external\settings singleton All web service servers must set this singleton when parsing the $_GET and $_POST.

Options are the same that in {See also
format_text()} with some changes in defaults to provide backwards compatibility:
trusted : If true the string won't be cleaned. Default false.
noclean : If true the string won't be cleaned only if trusted is also true. Default false.
nocache : If true the string will not be cached and will be formatted every call. Default false.
filter : Can be set to false to force filters off, else observes {

core_external\settings}.
para : If true then the returned string will be wrapped in div tags.
Default (different from format_text) false.
Default changed because div tags are not commonly needed.
newlines : If true then lines newline breaks will be converted to HTML newline breaks. Default true.
context : Not used! Using contextid parameter instead.
overflowdiv : If set to true the formatted text will be encased in a div with the class no-overflow before being
returned. Default false.
allowid : If true then id attributes will not be removed, even when using htmlpurifier. Default (different from
format_text) true. Default changed id attributes are commonly needed.
blanktarget : If true all tags will have target="_blank" added unless target is explicitly specified.

Parameters

string | null $text The content that may contain ULRs in need of rewriting.

string | int | null $textformat The text format.

context $context This parameter and the next two identify the file area to use.

string | null $component
string | null $filearea helps identify the file area.

int | string | null $itemid helps identify the file area.

array | stdClass | null $options text formatting options

Return values

array text + textformat

◆ generate_token()

static core_external\util::generate_token	(	int	$tokentype,
		stdClass	$service,
		int	$userid,
		context	$context,
		int	$validuntil = 0,
		string	$iprestriction = '',
		string	$name = '' )

static

Create and return a session linked token.

Token to be used for html embedded client apps that want to communicate with the Moodle server through web services. The token is linked to the current session for the current page request. It is expected this will be called in the script generating the html page that is embedding the client app and that the returned token will be somehow passed into the client app being embedded in the page.

Parameters

int	$tokentype	EXTERNAL_TOKEN_EMBEDDED\|EXTERNAL_TOKEN_PERMANENT
stdClass	$service	service linked to the token
int	$userid	user linked to the token
context	$context
int	$validuntil	date when the token expired
string	$iprestriction	allowed ip - if 0 or empty then all ips are allowed
string	$name	token name as a note or token identity at the table view.

Return values

string generated token

◆ generate_token_for_current_user()

static core_external\util::generate_token_for_current_user ( stdClass $service )

static

Generate or return an existing token for the current authenticated user.

This function is used for creating a valid token for users authenticathing via places, including:

login/token.php
admin/tool/mobile/launch.php.

Parameters

stdClass $service external service object

Return values

stdClass token object

Exceptions

moodle_exception

◆ generate_token_name()

static core_external\util::generate_token_name ( )

static

Generate token name.

Return values

string

◆ get_area_files()

static core_external\util::get_area_files	(	$contextid,
		$component,
		$filearea,
		$itemid = false,
		$useitemidinurl = true )

static

Returns all area files (optionally limited by itemid).

Parameters

int	$contextid	context ID
string	$component	component
string	$filearea	file area
int	$itemid	item ID or all files if not specified
bool	$useitemidinurl	wether to use the item id in the file URL (modules intro don't use it)

Return values

array of files, compatible with the external_files structure.

Since: Moodle 3.2

◆ get_service_by_id()

static core_external\util::get_service_by_id ( int $serviceid )

static

Get a service by its id.

Parameters

int $serviceid

Return values

stdClass

◆ get_service_by_name()

static core_external\util::get_service_by_name ( string $name )

static

Get a service by its name.

Parameters

string $name The service name.

Return values

stdClass

◆ log_token_request()

static core_external\util::log_token_request ( stdClass $token )

static

Set the last time a token was sent and trigger the core\event\webservice_token_sent event.

This function is used when a token is generated by the user via login/token.php or admin/tool/mobile/launch.php. In order to protect the privatetoken, we remove it from the event params.

Parameters

stdClass $token token object

◆ validate_courses()

static core_external\util::validate_courses	(	$courseids,
		$courses = [],
		$addcontext = false,
		$keepfails = false )

static

Validate a list of courses, returning the complete course objects for valid courses.

Each course has an additional 'contextvalidated' field, this will be set to true unless you set $keepfails, in which case it will be false if validation fails for a course.

Parameters

array	$courseids	A list of course ids
array	$courses	An array of courses already pre-fetched, indexed by course id.
bool	$addcontext	True if the returned course object should include the full context object.
bool	$keepfails	True to keep all the course objects even if validation fails

Return values

array An array of courses and the validation warnings

◆ validate_format()

static core_external\util::validate_format ( $format )

static

Validate text field format against known FORMAT_XXX.

Parameters

string $format the format to validate

Return values

string the validated format

Exceptions

moodle_exception

Since: Moodle 2.3

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

lib/external/classes/util.php

string \| null	$content	The string to be filtered. Should be plain text, expect possibly for multilang tags.
context	$context	The id of the context for the string or the context (affects filters).
boolean	$striplinks	To strip any link in the result text. Moodle 1.8 default changed from false to true! MDL-8713
array	$options	options array/object or courseid

string \| null	$text	The content that may contain ULRs in need of rewriting.
string \| int \| null	$textformat	The text format.
context	$context	This parameter and the next two identify the file area to use.
string \| null	$component
string \| null	$filearea	helps identify the file area.
int \| string \| null	$itemid	helps identify the file area.
array \| stdClass \| null	$options	text formatting options

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ delete_service_descriptions()

◆ format_string()

◆ format_text()

◆ generate_token()

◆ generate_token_for_current_user()

◆ generate_token_name()

◆ get_area_files()

◆ get_service_by_id()

◆ get_service_by_name()

◆ log_token_request()

◆ validate_courses()

◆ validate_format()