Actions

API15

JURI

From Joomla! Documentation

Revision as of 16:19, 22 March 2010 by Doxiki (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

[Edit Descripton] JURI provides a number of methods and properties for handling Uniform Resource Identifiers (URIs). It also provides a means of obtaining the URI of the current request regardless of the web server on which Joomla is running.

The formal structure of a URI is defined in RFC3986 and the following is an example taken from that document:

     foo://example.com:8042/over/there?name=ferret#nose
     \_/   \______________/\_________/ \_________/ \__/
      |           |            |            |        |
   scheme     authority       path        query   fragment

The scheme and path components are required, though the path may be empty (no characters). When authority is present, the path must either be empty or begin with a slash ("/") character. When authority is not present, the path cannot begin with two slash characters ("//").

The scheme usually specifies the internet protocol that is to be used to access the resource. For example, 'http' indicates that the HyperText Transfer Protocol is to be used.

The authority field can be sub-divided into user information, host and port number parts. The user information part allows a URI to contain authentication information, usually in the form 'username:password', although this format is deprecated as "The passing of authentication information in clear text has proven to be a security risk in almost every case where it has been used." However, as URIs containing authentication information are still available on the internet, the JURI class will continue to support the generation and parsing of user authentication information.

The query part may contain multiple items, separated by '&' characters.

The JURI class effectively provides a wrapper around the PHP parse_url function.

Contents

Defined in

libraries/joomla/environment/uri.php

Methods

Method name Description
__construct Constructor. You can pass a URI string to the constructor to initialize a specific URI.
current Returns the URL for the request, minus the query
parse Parse a given URI and populate the class fields
toString Returns full uri string
setVar Adds a query variable and value, replacing the value if it already exists and returning the old value.
getVar Returns a query variable by name
delVar Removes an item from the query string variables if it exists
setQuery Sets the query to a supplied string in format: foo=bar&x=y
getQuery Returns flat query string
buildQuery Build a query from a array (reverse of the PHP parse_str())
getScheme Get URI scheme (protocol) ie. http, https, ftp, etc...
setScheme Set URI scheme (protocol) ie. http, https, ftp, etc...
getUser Get URI username returns the username, or null if no username was specified
setUser Set URI username
getPass Get URI password returns the password, or null if no password was specified
setPass Set URI password
getHost Get URI host returns the hostname/ip, or null if no hostname/ip was specified
setHost Set URI host
getPort Get URI port returns the port number, or null if no port was specified
setPort Set URI port
getPath Gets the URI path string
setPath Set the URI path string
getFragment Get the URI archor string everything after the "#"
setFragment Set the URI anchor string everything after the "#"
isSSL Checks whether the current URI is using HTTPS
isInternal Checks if the supplied URL is internal
getInstance Returns a reference to a global JURI object, only creating it if it doesn't already exist.
base Returns the base URI for the request.
root Returns the root URI for the request.

Importing

jimport( 'joomla.environment.uri' );

[Edit See Also] SeeAlso:JURI

Examples

<CodeExamplesForm />

Example of Get and Set Methods

Get and set methods are provided for all the component parts of a URI. The following names of the component parts are used:

     http://fredbloggs:itsasecret@www.example.com:8080/path/to/Joomla/index.php?task=view&id=32#anchorthis
     \__/   \________/ \________/ \_____________/ \__/\_______________________/ \_____________/ \________/
      |          |         |              |        |              |                    |            |
   scheme      user       pass          host      port          path                 query       fragment

The example column in the following table illustrates the result of each of the get methods on the URI above.

Get method Set method Description Example
getFragment setFragment Fragment (everything after the '#'). This is often referred to as an anchor. anchorthis
getHost setHost Hostname or IP address. For example, 'www.joomla.org' or '192.168.2.45'. www.example.com
getPass setPass Password part of the authority. itsasecret
getPath setPath Path string. Note that the path always includes the leading "/" character. /path/to/Joomla/index.php
getPort setPort Port number. Specific schemes (protocols) have their own defaults (for example, 'http' is port 80, 'ftp' is port 21). 8080
getQuery setQuery Query in string format. For example, "foo=bar&x=y". See also buildQuery. task=view&id=32
getScheme setScheme Scheme (protocol). For example, 'http', 'https', 'ftp'. http
getUser setUser Username part of the authority. fredbloggs
getVar setVar An individual query item value from within the query part. See also delVar. 32


Chris Davenport 13:17, 17 April 2011 (CDT) Edit comment