## Class TUrlMapping

Description

TUrlMapping Class

The TUrlMapping module allows PRADO to construct and recognize URLs based on specific patterns.

TUrlMapping consists of a list of URL patterns which are used to match against the currently requested URL. The first matching pattern will then be used to decompose the URL into request parameters (accessible through

    $this->Request['paramname']

).

The patterns can also be used to construct customized URLs. In this case, the parameters in an applied pattern will be replaced with the corresponding GET variable values.

Since it is derived from TUrlManager, it should be configured globally in the application configuration like the following,

      <module id="request" class="THttpRequest" UrlManager="friendly-url" />
      <module id="friendly-url" class="System.Web.TUrlMapping" EnableCustomUrl="true">
        <url ServiceParameter="Posts.ViewPost" pattern="post/{id}/" parameters.id="\d+" />
        <url ServiceParameter="Posts.ListPost" pattern="archive/{time}/" parameters.time="\d{6}" />
        <url ServiceParameter="Posts.ListPost" pattern="category/{cat}/" parameters.cat="\d+" />
      </module>

In the above, each <tt>&lt;url&gt;</tt> element specifies a URL pattern represented as a TUrlMappingPattern internally. You may create your own pattern classes by extending TUrlMappingPattern and specifying the <tt>&lt;class&gt;</tt> attribute in the element.

The patterns can be also be specified in an external file using the ConfigFile property.

The URL mapping are evaluated in order, only the first mapping that matches the URL will be used. Cascaded mapping can be achieved by placing the URL mappings in particular order. For example, placing the most specific mappings first.

Only the PATH_INFO part of the URL is used to match the available patterns. The matching is strict in the sense that the whole pattern must match the whole PATH_INFO of the URL.

From PRADO v3.1.1, TUrlMapping also provides support for constructing URLs according to the specified pattern. You may enable this functionality by setting EnableCustomUrl to true. When you call THttpRequest::constructUrl() (or via TPageService::constructUrl()), TUrlMapping will examine the available URL mapping patterns using their TUrlMappingPattern::getServiceParameter and TUrlMappingPattern::getPattern properties. A pattern is applied if its TUrlMappingPattern::getServiceParameter matches the service parameter passed to constructUrl() and every parameter in the getPattern is found in the GET variables.

- since: 3.0.5
- version: $Id: TUrlMapping.php 2604 2009-01-21 08:49:21Z haertl.mike $
- author: Wei Zhuo <weizhuo[at]gmail[dot]com>

Located in /Web/TUrlMapping.php (line 70)

    TComponent
       |
       --TApplicationComponent
          |
          --TModule
             |
             --TUrlManager
                |
                --TUrlMapping

Class Constant Summary
CONFIG_FILE_EXT = '.xml'
Variable Summary
array $_constructRules
TUrlMappingPattern[] $_patterns
Method Summary
string constructUrl (string $serviceID, string $serviceParam, array $getItems, boolean $encodeAmpersand, boolean $encodeGetItems)
string getConfigFile ()
string getDefaultMappingClass ()
boolean getEnableCustomUrl ()
TUrlMappingPattern getMatchingPattern ()
string getUrlPrefix ()
void init (TXmlElement $xml)
void loadConfigFile ()
void loadUrlMappings (TXmlElement $xml)
array parseUrl ()
void setConfigFile (string $value)
void setDefaultMappingClass (string $value)
void setEnableCustomUrl (boolean $value)
void setUrlPrefix (string $value)
Variables
array $_constructRules = array() (line 95)

- var: rules for constructing URLs
- access: protected

TUrlMappingPattern[] $_patterns = array() (line 79)

- var: list of patterns.
- access: protected

Methods
constructUrl (line 296)

Constructs a URL that can be recognized by PRADO.

This method provides the actual implementation used by THttpRequest::constructUrl. Override this method if you want to provide your own way of URL formatting. If you do so, you may also need to override parseUrl so that the URL can be properly parsed.

The URL is constructed as the following format: /entryscript.php?serviceID=serviceParameter&get1=value1&... If THttpRequest::setUrlFormat is 'Path', the following format is used instead: /entryscript.php/serviceID/serviceParameter/get1,value1/get2,value2...

- return: URL
- access: public
- since: 3.1.1
- see: TUrlMapping::parseUrl()

string constructUrl (string $serviceID, string $serviceParam, array $getItems, boolean $encodeAmpersand, boolean $encodeGetItems)

- string $serviceID: service ID
- string $serviceParam: service parameter
- array $getItems: GET parameters, null if not provided
- boolean $encodeAmpersand: whether to encode the ampersand in URL
- boolean $encodeGetItems: whether to encode the GET parameters (their names and values)

Redefinition of:

TUrlManager::constructUrl()
  Constructs a URL that can be recognized by PRADO.

getConfigFile (line 182)

- return: external configuration file. Defaults to null.
- access: public

string getConfigFile ()
getDefaultMappingClass (line 202)

- return: the default class of URL mapping patterns. Defaults to TUrlMappingPattern.
- access: public
- since: 3.1.1

string getDefaultMappingClass ()
getEnableCustomUrl (line 143)

Returns a value indicating whether to enable custom constructUrl.

If true, constructUrl() will make use of the URL mapping rules to construct valid URLs.

- return: whether to enable custom constructUrl. Defaults to false.
- access: public
- since: 3.1.1

boolean getEnableCustomUrl ()
getMatchingPattern (line 331)

- return: the matched pattern, null if not found.
- access: public

TUrlMappingPattern getMatchingPattern ()
getUrlPrefix (line 164)

- return: the part that will be prefixed to the constructed URLs. Defaults to the requested script path (e.g. /path/to/index.php for a URL http://hostname/path/to/index.php)
- access: public
- since: 3.1.1

string getUrlPrefix ()
init (line 107)

Initializes this module.

This method is required by the IModule interface.

- access: public
- throws: TConfigurationException if module is configured in the global scope.

void init (TXmlElement $xml)

- TXmlElement $xml: configuration for this module, can be null

Redefinition of:

TModule::init()
  Initializes the module.

loadConfigFile (line 124)

Initialize the module from configuration file.

- access: protected
- throws: TConfigurationException if ConfigFile is invalid.

void loadConfigFile ()
loadUrlMappings (line 224)

Load and configure each url mapping pattern.

- access: protected
- throws: TConfigurationException if specific pattern class is invalid

void loadUrlMappings (TXmlElement $xml)

- TXmlElement $xml: configuration node

parseUrl (line 252)

Parses the request URL and returns an array of input parameters.

This method overrides the parent implementation. The input parameters do not include GET and POST variables. This method uses the request URL path to find the first matching pattern. If found the matched pattern parameters are used to return as the input parameters.

- return: list of input parameters
- access: public

array parseUrl ()

Redefinition of:

TUrlManager::parseUrl()
  Parses the request URL and returns an array of input parameters.

setConfigFile (line 192)

- access: public
- throws: TInvalidDataValueException if the file is invalid.

void setConfigFile (string $value)

- string $value: external configuration file in namespace format. The file must be suffixed with '.xml'.

setDefaultMappingClass (line 214)

Sets the default class of URL mapping patterns.

When a URL matching pattern does not specify "class" attribute, it will default to the class specified by this property. You may use either a class name or a namespace format of class (if the class needs to be included first.)

- access: public
- since: 3.1.1

void setDefaultMappingClass (string $value)

- string $value: the default class of URL mapping patterns.

setEnableCustomUrl (line 155)

Sets a value indicating whether to enable custom constructUrl.

If true, constructUrl() will make use of the URL mapping rules to construct valid URLs.

- access: public
- since: 3.1.1

void setEnableCustomUrl (boolean $value)

- boolean $value: whether to enable custom constructUrl.

setUrlPrefix (line 174)

- access: public
- since: 3.1.1
- see: TUrlMapping::getUrlPrefix()

void setUrlPrefix (string $value)

- string $value: the part that will be prefixed to the constructed URLs. This is used by constructUrl() when EnableCustomUrl is set true.

#### Inherited Methods

Inherited From TUrlManager

> TUrlManager::constructUrl()
> TUrlManager::parseUrl()

Inherited From TModule

> TModule::getID()
> TModule::init()
> TModule::setID()

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants
CONFIG_FILE_EXT = '.xml' (line 75)

File extension of external configuration file

Documentation generated on Mon, 22 Feb 2010 12:18:57 +0000 by phpDocumentor 1.3.0RC4