Class TUrlMappingPattern

Description

TUrlMappingPattern class.

TUrlMappingPattern represents a pattern used to parse and construct URLs. If the currently requested URL matches the pattern, it will alter the THttpRequest parameters. If a constructUrl() call matches the pattern parameters, the pattern will generate a valid URL. In both case, only the PATH_INFO part of a URL is parsed/constructed using the pattern.

To specify the pattern, set the Pattern property. Pattern takes a string expression with parameter names enclosed between a left brace '{' and a right brace '}'. The patterns for each parameter can be set using Parameters attribute collection. For example

  1.  <url ... pattern="articles/{year}/{month}/{day}"
  2.           parameters.year="\d{4}" parameters.month="\d{2}" parameters.day="\d+" />

In the above example, the pattern contains 3 parameters named "year", "month" and "day". The pattern for these parameters are, respectively, "\d{4}" (4 digits), "\d{2}" (2 digits) and "\d+" (1 or more digits). Essentially, the <tt>Parameters</tt> attribute name and values are used as substrings in replacing the placeholders in the <tt>Pattern</tt> string to form a complete regular expression string.

For more complicated patterns, one may specify the pattern using a regular expression by RegularExpression. For example, the above pattern is equivalent to the following regular expression-based pattern:

  1.  #^articles/(?P<year>\d{4})/(?P<month>\d{2})\/(?P<day>\d+)$#u
The above regular expression used the "named group" feature available in PHP. If you intended to use the <tt>RegularExpression</tt> property or regular expressions in CDATA sections, notice that you need to escape the slash, if you are using the slash as regular expressions delimiter.

Thus, only an url that matches the pattern will be valid. For example, a URL <tt>http://example.com/index.php/articles/2006/07/21</tt> will match the above pattern, while <tt>http://example.com/index.php/articles/2006/07/hello</tt> will not since the "day" parameter pattern is not satisfied.

The parameter values are available through the <tt>THttpRequest</tt> instance (e.g. <tt>$this->Request['year']</tt>).

The ServiceParameter and ServiceID (the default ID is 'page') set the service parameter and service id respectively.

Since 3.1.4 you can also use simplyfied wildcard patterns to match multiple ServiceParameters with a single rule. The pattern must contain the placeholder {*} for the ServiceParameter. For example

<url ServiceParameter="adminpages.*" pattern="admin/{*}" />

This rule will match an URL like <tt>http://example.com/index.php/admin/edituser</tt> and resolve it to the page Application.pages.admin.edituser. The wildcard matching is non-recursive. That means you have to add a rule for every subdirectory you want to access pages in:

<url ServiceParameter="adminpages.users.*" pattern="useradmin/{*}" />

It is still possible to define an explicit rule for a page in the wildcard path. This rule has to preceed the wildcard rule.

You can also use parameters with wildcard patterns. The parameters are then available with every matching page:

<url ServiceParameter="adminpages.*" pattern="admin/{*}/{id}" parameters.id="\d+" />

To enable automatic parameter encoding in a path format fro wildcard patterns you can set {@setUrlFormat UrlFormat} to 'Path':

<url ServiceParameter="adminpages.*" pattern="admin/{*}" UrlFormat="Path" />

This will create and parse URLs of the form <tt>.../index.php/admin/listuser/param1/value1/param2/value2</tt>.

Use {@setUrlParamSeparator} to define another separator character between parameter name and value. Parameter/value pairs are always separated by a '/'.

<url ServiceParameter="adminpages.*" pattern="admin/{*}" UrlFormat="Path" UrlParamSeparator="-" />

<tt>.../index.php/admin/listuser/param1-value1/param2-value2</tt>.

  • author: Wei Zhuo <weizhuo[at]gmail[dot]com>
  • version: $Id: TUrlMapping.php 3051 2011-10-17 07:36:47Z GODZilla0480@gmail.com $
  • since: 3.0.5

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

TComponent
   |
   --TUrlMappingPattern
Method Summary
TUrlMappingPattern __construct (TUrlManager $manager)
string applySecureConnectionPrefix (string $url)
string constructUrl (array $getItems, boolean $encodeAmpersand, boolean $encodeGetItems)
boolean getCaseSensitive ()
boolean getEnableCustomUrl ()
string getPattern ()
array getPatternMatches (THttpRequest $request)
string getServiceID ()
void init (TXmlElement $config)
void setCaseSensitive (boolean $value)
void setEnableCustomUrl (boolean $value)
void setPattern (string $value)
void setRegularExpression (string $value)
void setServiceID (string $value)
void setServiceParameter (string $value)
void setUrlFormat (THttpRequestUrlFormat $value, since 1)
void setUrlParamSeparator (string $value)
boolean supportCustomUrl (array $getItems)
Methods
Constructor __construct (line 518)

Constructor.

  • access: public
TUrlMappingPattern __construct (TUrlManager $manager)
applySecureConnectionPrefix (line 894)

Apply behavior of SecureConnection property by conditionaly prefixing URL with THttpRequest::getBaseUrl()

  • since: 3.2
  • access: protected
string applySecureConnectionPrefix (string $url)
  • string $url
constructUrl (line 828)

Constructs a URL using this pattern.

  • return: the constructed URL
  • since: 3.1.1
  • access: public
string constructUrl (array $getItems, boolean $encodeAmpersand, boolean $encodeGetItems)
  • array $getItems: list of GET variables
  • boolean $encodeAmpersand: whether the ampersand should be encoded in the constructed URL
  • boolean $encodeGetItems: whether the GET variables should be encoded in the constructed URL
getCaseSensitive (line 597)
  • return: whether the Pattern should be treated as case sensititve. Defaults to true.
  • access: public
boolean getCaseSensitive ()
getEnableCustomUrl (line 719)

Returns a value indicating whether to use this pattern to construct URL.

  • return: whether to enable custom constructUrl. Defaults to true.
  • since: 3.1.1
  • access: public
boolean getEnableCustomUrl ()
getIsWildCardPattern (line 737)
  • return: whether this pattern is a wildcard pattern
  • since: 3.1.4
  • access: public
boolean getIsWildCardPattern ()
getManager (line 528)
  • return: the URL manager instance
  • access: public
TUrlManager getManager ()
getParameterizedPattern (line 551)

Substitute the parameter key value pairs as named groupings in the regular expression matching pattern.

  • return: regular expression pattern with parameter subsitution
  • access: protected
string getParameterizedPattern ()
getParameters (line 661)
  • return: parameter key value pairs.
  • access: public
TAttributeCollection getParameters ()
getPattern (line 645)
  • return: url pattern to match. Defaults to ''.
  • access: public
string getPattern ()
getPatternMatches (line 680)

Uses URL pattern (or full regular expression if available) to match the given url path.

  • return: matched parameters, empty if no matches.
  • access: public
array getPatternMatches (THttpRequest $request)
getRegularExpression (line 581)
  • return: full regular expression mapping pattern
  • access: public
string getRegularExpression ()
getSecureConnection (line 789)
  • return: the SecureConnection behavior. Defaults to Automatic
  • since: 3.2
  • access: public
TUrlMappingPatternSecureConnection getSecureConnection ()
getServiceID (line 637)
  • return: service id.
  • access: public
string getServiceID ()
getServiceParameter (line 621)
  • return: service parameter, such as page class name.
  • access: public
string getServiceParameter ()
getUrlFormat (line 744)
  • return: the format of URLs. Defaults to THttpRequestUrlFormat::Get.
  • access: public
THttpRequestUrlFormat getUrlFormat ()
getUrlParamSeparator (line 768)
  • return: separator used to separate GET variable name and value when URL format is Path. Defaults to slash '/'.
  • access: public
string getUrlParamSeparator ()
init (line 538)

Initializes the pattern.

  • throws: TConfigurationException if service parameter is not specified
  • access: public
void init (TXmlElement $config)
setCaseSensitive (line 605)
  • access: public
void setCaseSensitive (boolean $value)
  • boolean $value: whether the Pattern should be treated as case sensititve.
setEnableCustomUrl (line 728)

Sets a value indicating whether to enable custom constructUrl using this pattern

  • access: public
void setEnableCustomUrl (boolean $value)
  • boolean $value: whether to enable custom constructUrl.
setParameters (line 669)
  • access: public
void setParameters (TAttributeCollection $value)
setPattern (line 653)
  • access: public
void setPattern (string $value)
  • string $value: url pattern to match.
setRegularExpression (line 589)
  • access: public
void setRegularExpression (string $value)
  • string $value: full regular expression mapping pattern.
setSecureConnection (line 798)
  • since: 3.2
  • access: public
void setSecureConnection (TUrlMappingPatternSecureConnection $value)
setServiceID (line 629)
  • access: public
void setServiceID (string $value)
  • string $value: service id to handle.
setServiceParameter (line 613)
  • access: public
void setServiceParameter (string $value)
  • string $value: service parameter, such as page class name.
setUrlFormat (line 760)

Sets the format of URLs constructed and interpreted by this pattern.

A Get URL format is like index.php?name1=value1&name2=value2 while a Path URL format is like index.php/name1/value1/name2/value. The separating character between name and value can be configured with setUrlParamSeparator and defaults to '/'. Changing the UrlFormat will affect constructUrl and how GET variables are parsed.

  • access: public
void setUrlFormat (THttpRequestUrlFormat $value, since 1)
setUrlParamSeparator (line 777)
  • throws: TInvalidDataValueException if the separator is not a single character
  • access: public
void setUrlParamSeparator (string $value)
  • string $value: separator used to separate GET variable name and value when URL format is Path.
supportCustomUrl (line 808)
  • return: whether this pattern IS the one for constructing the URL with the specified GET items.
  • since: 3.1.1
  • access: public
boolean supportCustomUrl (array $getItems)
  • array $getItems: list of GET items to be put in the constructed URL

Inherited Methods

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::__call()
TComponent::__get()
TComponent::__set()
TComponent::__sleep()
TComponent::__wakeup()

Documentation generated on Mon, 25 Jun 2012 14:39:33 +0200 by phpDocumentor 1.4.3