Class for creating and manipulating urls. More...

Public Member Functions
	__construct ($url, array $params=null, $anchor=null)
	Create new instance of moodle_url.

	__toString ()
	Shortcut for printing of encoded URL.

	compare (moodle_url $url, $matchtype=URL_MATCH_EXACT)
	Compares this moodle_url with another.

	export_params_for_template ()
	Get the url params as an array of key => value pairs.

	get_encoded_anchor ()
	Encode the anchor according to RFC 3986.

	get_host ()
	Returns the 'host' portion of a URL.

	get_param ($name)
	Returns a given parameter value from the URL.

	get_path ($includeslashargument=true)
	Returns the 'path' portion of a URL.

	get_port ()
	Returns the 'port' portion of a URL.

	get_query_string ($escaped=true, array $overrideparams=null)
	Get the params as as a query string.

	get_scheme ()
	Returns the 'scheme' portion of a URL.

	is_local_url ()
	Checks if URL is relative to $CFG->wwwroot.

	out ($escaped=true, array $overrideparams=null)
	Output url.

	out_as_local_url ($escaped=true, array $overrideparams=null)
	Returns URL as relative path from $CFG->wwwroot.

	out_omit_querystring ($includeanchor=false)
	Returns url without parameters, everything before '?'.

	param ($paramname, $newvalue='')
	Add a param to the params for this url.

	params (array $params=null)
	Add an array of params to the params for this url.

	raw_out ($escaped=true, array $overrideparams=null)
	Output url without any rewrites.

	remove_all_params ($params=null)
	Remove all url parameters.

	remove_params ($params=null)
	Remove all params if no arguments passed.

	set_anchor ($anchor)
	Sets the anchor for the URI (the bit after the hash)

	set_scheme ($scheme)
	Sets the scheme for the URI (the bit before ://)

	set_slashargument ($path, $parameter='file', $supported=null)
	Sets the url slashargument value.

Static Public Member Functions
static	make_draftfile_url ($draftid, $pathname, $filename, $forcedownload=false)
	Factory method for creation of url pointing to draft file of current user.

static	make_file_url ($urlbase, $path, $forcedownload=false)
	General moodle file url.

static	make_legacyfile_url ($courseid, $filepath, $forcedownload=false)
	Factory method for creating of links to legacy course files.

static	make_pluginfile_url ($contextid, $component, $area, $itemid, $pathname, $filename, $forcedownload=false, $includetoken=false)
	Factory method for creation of url pointing to plugin file.

static	make_webservice_pluginfile_url ($contextid, $component, $area, $itemid, $pathname, $filename, $forcedownload=false)
	Factory method for creation of url pointing to plugin file.

Protected Member Functions
	merge_overrideparams (array $overrideparams=null)
	Merges parameters and validates them.

Protected Attributes
string	$anchor = null
	Anchor, may be also empty, null means none.

string	$host = ''
	Hostname.

array	$params = array()
	Url parameters as associative array.

string	$pass = ''
	Password for http auth.

string	$path = ''
	Script path.

int	$port = ''
	Port number, empty means default 80 or 443 in case of http.

string	$scheme = ''
	Scheme, ex.: http, https.

string	$slashargument = ''
	Optional slash argument value.

string	$user = ''
	Username for http auth.

Detailed Description

Class for creating and manipulating urls.

It can be used in moodle pages where config.php has been included without any further includes.

It is useful for manipulating urls with long lists of params. One situation where it will be useful is a page which links to itself to perform various actions and / or to process form data. A moodle_url object : can be created for a page to refer to itself with all the proper get params being passed from page call to page call and methods can be used to output a url including all the params, optionally adding and overriding params and can also be used to

output the url without any get params
and output the params as hidden fields to be output within a form

Copyright: 2007 jamiesensei

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

Constructor & Destructor Documentation

◆ __construct()

moodle_url::__construct	(		$url,
		array	$params = null,
			$anchor = null )

Create new instance of moodle_url.

Parameters

moodle_url \| string	$url	- moodle_url means make a copy of another moodle_url and change parameters, string means full url or shortened form (ex.: '/course/view.php'). It is strongly encouraged to not include query string because it may result in double encoded values. Use the $params instead. For admin URLs, just use /admin/script.php, this class takes care of the $CFG->admin issue.
array	$params	these params override current params or add new
string	$anchor	The anchor to use as part of the URL if there is one.

Exceptions

moodle_exception

Member Function Documentation

◆ __toString()

moodle_url::__toString ( )

Shortcut for printing of encoded URL.

Return values

string

◆ compare()

moodle_url::compare	(	moodle_url	$url,
			$matchtype = URL_MATCH_EXACT )

Compares this moodle_url with another.

See documentation of constants for an explanation of the comparison flags.

Parameters

moodle_url	$url	The moodle_url object to compare
int	$matchtype	The type of comparison (URL_MATCH_BASE, URL_MATCH_PARAMS, URL_MATCH_EXACT)

Return values

bool

◆ export_params_for_template()

moodle_url::export_params_for_template ( )

Get the url params as an array of key => value pairs.

This helps in handling cases where url params contain arrays.

Return values

array params array for templates.

◆ get_encoded_anchor()

moodle_url::get_encoded_anchor ( )

Encode the anchor according to RFC 3986.

Return values

string The encoded anchor

◆ get_host()

moodle_url::get_host ( )

Returns the 'host' portion of a URL.

For example, if the URL is http://www.example.org:447/my/file/is/here.txt?really=1 then this will return 'www.example.org'.

Return values

string Host of the URL.

◆ get_param()

moodle_url::get_param ( $name )

Returns a given parameter value from the URL.

Parameters

string $name Name of parameter

Return values

string Value of parameter or null if not set

◆ get_path()

moodle_url::get_path ( $includeslashargument = true )

Returns the 'path' portion of a URL.

For example, if the URL is http://www.example.org:447/my/file/is/here.txt?really=1 then this will return '/my/file/is/here.txt'.

By default the path includes slash-arguments (for example, '/myfile.php/extra/arguments') so it is what you would expect from a URL path. If you don't want this behaviour, you can opt to exclude the slash arguments. (Be careful: if the $CFG variable slasharguments is disabled, these URLs will have a different format and you may need to look at the 'file' parameter too.)

Parameters

bool $includeslashargument If true, includes slash arguments

Return values

string Path of URL

◆ get_port()

moodle_url::get_port ( )

Returns the 'port' portion of a URL.

For example, if the URL is http://www.example.org:447/my/file/is/here.txt?really=1 then this will return '447'.

Return values

string Port of the URL.

◆ get_query_string()

moodle_url::get_query_string	(		$escaped = true,
		array	$overrideparams = null )

Get the params as as a query string.

This method should not be used outside of this method.

Parameters

bool	$escaped	Use & as params separator instead of plain &
array	$overrideparams	params to add to the output params, these override existing ones with the same name.

Return values

string query string that can be added to a url.

◆ get_scheme()

moodle_url::get_scheme ( )

Returns the 'scheme' portion of a URL.

For example, if the URL is http://www.example.org:447/my/file/is/here.txt?really=1 then this will return 'http' (without the colon).

Return values

string Scheme of the URL.

◆ is_local_url()

moodle_url::is_local_url ( )

Checks if URL is relative to $CFG->wwwroot.

Return values

bool	True if URL is relative to $CFG->wwwroot; otherwise, false.

◆ make_draftfile_url()

static moodle_url::make_draftfile_url	(	$draftid,
		$pathname,
		$filename,
		$forcedownload = false )

static

Factory method for creation of url pointing to draft file of current user.

Parameters

int	$draftid	draft item id
string	$pathname
string	$filename
bool	$forcedownload

Return values

moodle_url

◆ make_file_url()

static moodle_url::make_file_url	(	$urlbase,
		$path,
		$forcedownload = false )

static

General moodle file url.

Parameters

string	$urlbase	the script serving the file
string	$path
bool	$forcedownload

Return values

moodle_url

◆ make_legacyfile_url()

static moodle_url::make_legacyfile_url	(	$courseid,
		$filepath,
		$forcedownload = false )

static

Factory method for creating of links to legacy course files.

Parameters

int	$courseid
string	$filepath
bool	$forcedownload

Return values

moodle_url

◆ make_pluginfile_url()

static moodle_url::make_pluginfile_url	(	$contextid,
		$component,
		$area,
		$itemid,
		$pathname,
		$filename,
		$forcedownload = false,
		$includetoken = false )

static

Factory method for creation of url pointing to plugin file.

Please note this method can be used only from the plugins to create urls of own files, it must not be used outside of plugins!

Parameters

int	$contextid
string	$component
string	$area
int	$itemid
string	$pathname
string	$filename
bool	$forcedownload
mixed	$includetoken	Whether to use a user token when displaying this group image. True indicates to generate a token for current user, and integer value indicates to generate a token for the user whose id is the value indicated. If the group picture is included in an e-mail or some other location where the audience is a specific user who will not be logged in when viewing, then we use a token to authenticate the user.

Return values

moodle_url

◆ make_webservice_pluginfile_url()

static moodle_url::make_webservice_pluginfile_url	(	$contextid,
		$component,
		$area,
		$itemid,
		$pathname,
		$filename,
		$forcedownload = false )

static

Factory method for creation of url pointing to plugin file.

This method is the same that make_pluginfile_url but pointing to the webservice pluginfile.php script. It should be used only in external functions.

Since: 2.8

Parameters

int	$contextid
string	$component
string	$area
int	$itemid
string	$pathname
string	$filename
bool	$forcedownload

Return values

moodle_url

◆ merge_overrideparams()

moodle_url::merge_overrideparams ( array $overrideparams = null )

protected

Merges parameters and validates them.

Parameters

array $overrideparams

Return values

array merged parameters

Exceptions

coding_exception

◆ out()

moodle_url::out	(		$escaped = true,
		array	$overrideparams = null )

Output url.

If you use the returned URL in HTML code, you want the escaped ampersands. If you use the returned URL in HTTP headers, you want $escaped=false.

Parameters

bool	$escaped	Use & as params separator instead of plain &
array	$overrideparams	params to add to the output url, these override existing ones with the same name.

Return values

string Resulting URL

◆ out_as_local_url()

moodle_url::out_as_local_url	(		$escaped = true,
		array	$overrideparams = null )

Returns URL as relative path from $CFG->wwwroot.

Can be used for passing around urls with the wwwroot stripped

Parameters

boolean	$escaped	Use & as params separator instead of plain &
array	$overrideparams	params to add to the output url, these override existing ones with the same name.

Return values

string Resulting URL

Exceptions

coding_exception if called on a non-local url

◆ out_omit_querystring()

moodle_url::out_omit_querystring ( $includeanchor = false )

Returns url without parameters, everything before '?'.

Parameters

bool $includeanchor if self::anchor is defined, should it be returned?

Return values

string

◆ param()

moodle_url::param	(		$paramname,
			$newvalue = '' )

Add a param to the params for this url.

The added param overrides existing one if they have the same name.

Parameters

string	$paramname	name
string	$newvalue	Param value. If new value specified current value is overriden or parameter is added

Return values

mixed string parameter value, null if parameter does not exist

◆ params()

moodle_url::params ( array $params = null )

Add an array of params to the params for this url.

The added params override existing ones if they have the same name.

Parameters

array $params Defaults to null. If null then returns all params.

Return values

array Array of Params for url.

Exceptions

coding_exception

◆ raw_out()

moodle_url::raw_out	(		$escaped = true,
		array	$overrideparams = null )

Output url without any rewrites.

This is identical in signature and use to out() but doesn't call the rewrite handler.

Parameters

bool	$escaped	Use & as params separator instead of plain &
array	$overrideparams	params to add to the output url, these override existing ones with the same name.

Return values

string Resulting URL

◆ remove_all_params()

moodle_url::remove_all_params ( $params = null )

Remove all url parameters.

Todo: remove the unused param.

Parameters

array $params Unused param

Return values

void

◆ remove_params()

moodle_url::remove_params ( $params = null )

Remove all params if no arguments passed.

Remove selected params if arguments are passed.

Can be called as either remove_params('param1', 'param2') or remove_params(array('param1', 'param2')).

Parameters

string[] | string $params,... either an array of param names, or 1..n string params to remove as args.

Return values

array url parameters

◆ set_anchor()

moodle_url::set_anchor ( $anchor )

Sets the anchor for the URI (the bit after the hash)

Parameters

string $anchor null means remove previous

◆ set_scheme()

moodle_url::set_scheme ( $scheme )

Sets the scheme for the URI (the bit before ://)

Parameters

string $scheme

◆ set_slashargument()

moodle_url::set_slashargument	(	$path,
		$parameter = 'file',
		$supported = null )

Sets the url slashargument value.

Parameters

string	$path	usually file path
string	$parameter	name of page parameter if slasharguments not supported
bool	$supported	usually null, then it depends on $CFG->slasharguments, use true or false for other servers

Return values

void

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

lib/weblib.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ __toString()

◆ compare()

◆ export_params_for_template()

◆ get_encoded_anchor()

◆ get_host()

◆ get_param()

◆ get_path()

◆ get_port()

◆ get_query_string()

◆ get_scheme()

◆ is_local_url()

◆ make_draftfile_url()

◆ make_file_url()

◆ make_legacyfile_url()

◆ make_pluginfile_url()

◆ make_webservice_pluginfile_url()

◆ merge_overrideparams()

◆ out()

◆ out_as_local_url()

◆ out_omit_querystring()

◆ param()

◆ params()

◆ raw_out()

◆ remove_all_params()

◆ remove_params()

◆ set_anchor()

◆ set_scheme()

◆ set_slashargument()