Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
moodle_url Class Reference

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 from_uri (UriInterface $uri)
 Create a new moodle_url instance from a UriInterface.
 
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
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$paramsthese params override current params or add new
string$anchorThe 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$urlThe moodle_url object to compare
int$matchtypeThe 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
arrayparams array for templates.

◆ from_uri()

static moodle_url::from_uri ( UriInterface $uri)
static

Create a new moodle_url instance from a UriInterface.

Parameters
UriInterface$uri
Return values
self

◆ get_encoded_anchor()

moodle_url::get_encoded_anchor ( )

Encode the anchor according to RFC 3986.

Return values
stringThe 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
stringHost of the URL.

◆ get_param()

moodle_url::get_param ( $name)

Returns a given parameter value from the URL.

Parameters
string$nameName of parameter
Return values
stringValue 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$includeslashargumentIf true, includes slash arguments
Return values
stringPath 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
stringPort 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$escapedUse & as params separator instead of plain &
array$overrideparamsparams to add to the output params, these override existing ones with the same name.
Return values
stringquery 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
stringScheme of the URL.

◆ is_local_url()

moodle_url::is_local_url ( )

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

Return values
boolTrue 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$draftiddraft 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$urlbasethe 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$includetokenWhether 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
arraymerged 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$escapedUse & as params separator instead of plain &
array$overrideparamsparams to add to the output url, these override existing ones with the same name.
Return values
stringResulting 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$escapedUse & as params separator instead of plain &
array$overrideparamsparams to add to the output url, these override existing ones with the same name.
Return values
stringResulting URL
Exceptions
coding_exceptionif called on a non-local url

◆ out_omit_querystring()

moodle_url::out_omit_querystring ( $includeanchor = false)

Returns url without parameters, everything before '?'.

Parameters
bool$includeanchorif 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$paramnamename
string$newvalueParam value. If new value specified current value is overriden or parameter is added
Return values
mixedstring 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$paramsDefaults to null. If null then returns all params.
Return values
arrayArray 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$escapedUse & as params separator instead of plain &
array$overrideparamsparams to add to the output url, these override existing ones with the same name.
Return values
stringResulting URL

◆ remove_all_params()

moodle_url::remove_all_params ( $params = null)

Remove all url parameters.

Todo
remove the unused param.
Parameters
array$paramsUnused 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
arrayurl parameters

◆ set_anchor()

moodle_url::set_anchor ( $anchor)

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

Parameters
string$anchornull 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$pathusually file path
string$parametername of page parameter if slasharguments not supported
bool$supportedusually 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: