From 2143fc9d208c82a43cf9ea39f13c724e99f66d16 Mon Sep 17 00:00:00 2001
From: xue <>
Date: Sat, 11 Aug 2007 14:30:07 +0000
Subject: further enhanced TUrlMapping.
---
UPGRADE | 2 +
.../protected/pages/Configurations/UrlMapping.page | 77 ++++----
framework/Exceptions/messages.txt | 6 +-
framework/Web/TUrlMapping.php | 216 ++++++++++-----------
4 files changed, 150 insertions(+), 151 deletions(-)
diff --git a/UPGRADE b/UPGRADE
index 6c8e72c9..77b136e8 100644
--- a/UPGRADE
+++ b/UPGRADE
@@ -13,6 +13,8 @@ Upgrading from v3.1.0
---------------------
- IFeedContentProvider adds a new method getContentType(). This affects any
class implementing this interface.
+- TUrlMapping now only uses the PATH_INFO part of URL for matching, and the matching
+ is for the whole PATH_INFO.
Upgrading from v3.1b
--------------------
diff --git a/demos/quickstart/protected/pages/Configurations/UrlMapping.page b/demos/quickstart/protected/pages/Configurations/UrlMapping.page
index 4e06dd09..3197dde3 100644
--- a/demos/quickstart/protected/pages/Configurations/UrlMapping.page
+++ b/demos/quickstart/protected/pages/Configurations/UrlMapping.page
@@ -4,36 +4,29 @@
Using the TUrlMapping module different URLs can be -mapped into any existing Prado pages or services. This allows -the application to use nice looking and friendly URLs. +
+The TUrlMapping module allows PRADO to construct and recognize friendly URLs +based on specific patterns.
-The TUrlMapping module allows aributary URL path to be mapped to a -particular service and page class. This module must be configured -before a service is initialized, thus this module should be configured -globally in the application configuration -file and before any services. +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 via +$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.
-
To use TUrlMapping, one must set the UrlManager property of the THttpRequest module as the TUrlMapping module ID. See following for an example,
-The ServiceParameter and ServiceID (the default ID is 'page') set the service parameter and service ID, respectively, of the Request module. The service parameter for the TPageService service is the Page class name, e.g., for an URL "index.php?page=Home", "page" is the service ID and the service parameter is "Home". Other services may use the service parameter and ID differently. See Services for further details. +The ServiceParameter and ServiceID (the default ID is 'page') +set the service parameter and service ID, respectively, of the Request module. The service parameter for the TPageService service is the Page class name, e.g., for an URL "index.php?page=Home", "page" is the service ID and the service parameter is "Home". Other services may use the service parameter and ID differently. See Services for further details.
+
TUrlMapping enables recognition of customized URL formats based on a list prespecified of URL patterns. Each pattern is specified in a <url> tag.
@@ -63,7 +65,7 @@ values are regular expression patterns that
determine the mapping criteria. The Pattern property takes
a regular expression with parameter names enclosed between a left brace '{'
and a right brace '}'. The pattens for each parameter can be set
-using Parametersattribute collection.
+using Parameters attribute collection.
For example,
In the above example, the pattern contains 3 parameters named "year",
@@ -93,13 +92,13 @@ property you need to escape the slash in regular expressions.
Following from the above pattern example,
-an URL "http://example.com/index.php/articles/2006/07/21" will be matched
-and valid. However, "http://example.com/index.php/articles/2006/07/hello" is not
- valid since the "day" parameter pattern is not satisfied.
- In the default TUrlMappingPattern class, the pattern is matched against the
-path property of the URL only. For example, only the
-"/index.php/articles/2006/07/21" portion of the URL is considered.
-
The mapped request URL is equivalent to index.php?page=ArticleView&year=2006&month=07&day=21. @@ -107,14 +106,22 @@ The request parameter values are available through the standard Request object. For example, $this->Request['year'].
-The URL mapping are evaluated in order they are place and only the first mapping that matches +
The URL mapping are evaluated in order they are placed and only the first pattern 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.
-Since version 3.0.6, TUrlMapping starts to support constructing customized URL formats. This is achieved by allowing users to extend TUrlMapping class and override the constructUrl method. In the applications, users can still use THttpRequest.constructUrl() or TPageService.constructUrl() to generate PRADO-recognizable URLS. The actual URL construction work is ultimately delegated to the TUrlMapping.constructUrl(), provided it is implemented. +Since version 3.1.1, TUrlMapping starts to support constructing customized URLs based on the provided patterns. To enable this feature, set TUrlMapping.EnableCustomUrl to true. When THttpRequest.constrcutUrl() is invoked, the actual URL construction work will be delegated to a matching TUrlMappingPattern instance. It replaces the parameters in the pattern with the corresponding GET variables passed to constructUrl(). +
+ ++A matching pattern is one whose ServiceID and ServiceParameter properties are the same as those passed to constructUrl() and whose named parameters are found in the GET variables. For example, constructUrl('Posts.ListPost',array('cat'=>2)) will use the third pattern in the above example. +
+ +
+By default, TUrlMapping will construct URLs prefixed with the currently requesting PHP script path, such as /path/to/index.php/article/3. Users may change this behavior by explicitly specifying the URL prefix through its UrlPrefix property. For example, if the Web server configuration treats index.php as the default script, we can set UrlPrefix as /path/to and the constructed URL will look like /path/to/article/3.
$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 {@link TUrlManager}, it should be configured globally
+ * in the application configuration like the following,
*
*
- *
- *
- *
- *
+ *
+ *
+ *
+ *
*
*
*
- * See {@link TUrlMappingPattern} for details regarding the mapping patterns.
- * Similar to other modules, the <url /> configuration class
- * can be customised using the class property.
+ * In the above, each <url> element specifies a URL pattern represented
+ * as a {@link TUrlMappingPattern} internally. You may create your own pattern classes
+ * by extending {@link TUrlMappingPattern} and specifying the <class> attribute
+ * in the element.
+ *
+ * The patterns can be also be specified in an external file using the {@link setConfigFile 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.
*
- * The mapping can be loaded from an external file by specifying a configuration
- * file using the {@link setConfigFile ConfigFile} property.
- *
- * Since TUrlMapping is a URL manager extending from {@link TUrlManager},
- * you may override {@link TUrlManager::constructUrl} to support your pattern-based
- * URL scheme.
+ * 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 to construct URLs according to
- * the specified the pattern. You may enable this functionality by setting {@link setEnableCustomUrl EnableCustomUrl} to true.
+ * From PRADO v3.1.1, TUrlMapping also provides support for constructing URLs according to
+ * the specified pattern. You may enable this functionality by setting {@link setEnableCustomUrl EnableCustomUrl} to true.
* When you call THttpRequest::constructUrl() (or via TPageService::constructUrl()),
- * TUrlMapping will examine the available URL mapping patterns using their {@link getServiceParameter ServiceParameter}
- * and {@link getPattern Pattern} properties. A pattern is applied if its
- * {@link getServiceParameter ServiceParameter} matches the service parameter passed
+ * TUrlMapping will examine the available URL mapping patterns using their {@link TUrlMappingPattern::getServiceParameter ServiceParameter}
+ * and {@link TUrlMappingPattern::getPattern Pattern} properties. A pattern is applied if its
+ * {@link TUrlMappingPattern::getServiceParameter ServiceParameter} matches the service parameter passed
* to constructUrl() and every parameter in the {@link getPattern Pattern} is found
* in the GET variables.
*
@@ -99,7 +108,7 @@ class TUrlMapping extends TUrlManager
{
parent::init($xml);
if($this->getRequest()->getRequestResolved())
- throw new TConfigurationException('urlpath_dispatch_module_must_be_global');
+ throw new TConfigurationException('urlmapping_global_required');
if($this->_configFile!==null)
$this->loadConfigFile();
$this->loadUrlMappings($xml);
@@ -121,8 +130,7 @@ class TUrlMapping extends TUrlManager
$this->loadUrlMappings($dom);
}
else
- throw new TConfigurationException(
- 'urlpath_dispatch_configfile_invalid',$this->_configFile);
+ throw new TConfigurationException('urlmapping_configfile_inexistent',$this->_configFile);
}
/**
@@ -130,6 +138,7 @@ class TUrlMapping extends TUrlManager
* If true, constructUrl() will make use of the URL mapping rules to
* construct valid URLs.
* @return boolean whether to enable custom constructUrl. Defaults to false.
+ * @since 3.1.1
*/
public function getEnableCustomUrl()
{
@@ -141,6 +150,7 @@ class TUrlMapping extends TUrlManager
* If true, constructUrl() will make use of the URL mapping rules to
* construct valid URLs.
* @param boolean whether to enable custom constructUrl.
+ * @since 3.1.1
*/
public function setEnableCustomUrl($value)
{
@@ -149,6 +159,7 @@ class TUrlMapping extends TUrlManager
/**
* @return string 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)
+ * @since 3.1.1
*/
public function getUrlPrefix()
{
@@ -158,6 +169,7 @@ class TUrlMapping extends TUrlManager
/**
* @param string the part that will be prefixed to the constructed URLs. This is used by constructUrl() when EnableCustomUrl is set true.
* @see getUrlPrefix
+ * @since 3.1.1
*/
public function setUrlPrefix($value)
{
@@ -180,7 +192,7 @@ class TUrlMapping extends TUrlManager
public function setConfigFile($value)
{
if(($this->_configFile=Prado::getPathOfNamespace($value,self::CONFIG_FILE_EXT))===null)
- throw new TConfigurationException('urlpath_configfile_invalid',$value);
+ throw new TConfigurationException('urlmapping_configfile_invalid',$value);
}
/**
@@ -216,12 +228,12 @@ class TUrlMapping extends TUrlManager
$properties=$url->getAttributes();
if(($class=$properties->remove('class'))===null)
$class=$this->getDefaultMappingClass();
- $pattern = Prado::createComponent($class,$this);
+ $pattern=Prado::createComponent($class,$this);
if(!($pattern instanceof TUrlMappingPattern))
throw new TConfigurationException('urlmapping_urlmappingpattern_required');
foreach($properties as $name=>$value)
$pattern->setSubproperty($name,$value);
- $this->_patterns[] = $pattern;
+ $this->_patterns[]=$pattern;
$pattern->init($url);
$key=$pattern->getServiceID().':'.$pattern->getServiceParameter();
@@ -239,17 +251,19 @@ class TUrlMapping extends TUrlManager
*/
public function parseUrl()
{
- $url = $this->getRequest()->getUrl();
+ $request=$this->getRequest();
foreach($this->_patterns as $pattern)
{
- $matches = $pattern->getPatternMatches($url);
- if(count($matches) > 0)
+ $matches=$pattern->getPatternMatches($request);
+ if(count($matches)>0)
{
$this->_matched=$pattern;
$params=array();
foreach($matches as $key=>$value)
+ {
if(is_string($key))
$params[$key]=$value;
+ }
$params[$pattern->getServiceID()]=$pattern->getServiceParameter();
return $params;
}
@@ -280,17 +294,18 @@ class TUrlMapping extends TUrlManager
*/
public function constructUrl($serviceID,$serviceParam,$getItems,$encodeAmpersand,$encodeGetItems)
{
- if(!$this->_customUrl)
- return parent::constructUrl($serviceID,$serviceParam,$getItems,$encodeAmpersand,$encodeGetItems);
- if(!(is_array($getItems) || ($getItems instanceof Traversable)))
- $getItems=array();
- $key=$serviceID.':'.$serviceParam;
- if(isset($this->_constructRules[$key]))
+ if($this->_customUrl)
{
- foreach($this->_constructRules[$key] as $rule)
+ if(!(is_array($getItems) || ($getItems instanceof Traversable)))
+ $getItems=array();
+ $key=$serviceID.':'.$serviceParam;
+ if(isset($this->_constructRules[$key]))
{
- if($rule->supportCustomUrl($getItems))
- return $rule->constructUrl($getItems,$encodeAmpersand,$encodeGetItems);
+ foreach($this->_constructRules[$key] as $rule)
+ {
+ if($rule->supportCustomUrl($getItems))
+ return $rule->constructUrl($getItems,$encodeAmpersand,$encodeGetItems);
+ }
}
}
return parent::constructUrl($serviceID,$serviceParam,$getItems,$encodeAmpersand,$encodeGetItems);
@@ -306,13 +321,16 @@ class TUrlMapping extends TUrlManager
}
/**
- * URL Mapping Pattern Class
+ * TUrlMappingPattern class.
*
- * Describes an URL mapping pattern, if a given URL matches the pattern, the
- * TUrlMapping class will alter the THttpRequest parameters. The
- * url matching is done using patterns and regular expressions.
+ * 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.
*
- * The {@link setPattern Pattern} property takes an string expression with
+ * To specify the pattern, set the {@link setPattern Pattern} property.
+ * {@link setPattern 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 {@link getParameters Parameters}
* attribute collection. For example
@@ -326,34 +344,27 @@ class TUrlMapping extends TUrlManager
* "\d{4}" (4 digits), "\d{2}" (2 digits) and "\d+" (1 or more digits).
* Essentially, the Parameters attribute name and values are used
* as substrings in replacing the placeholders in the Pattern string
- * to form a complete regular expression string. A full regular expression
- * may be expressed using the RegularExpression attribute or
- * as the body content of the <module> tag. The above pattern is equivalent
- * to the following regular expression pattern.
+ * to form a complete regular expression string.
+ *
+ * For more complicated patterns, one may specify the pattern using a regular expression
+ * by {@link setRegularExpression RegularExpression}. For example, the above pattern
+ * is equivalent to the following regular expression-based pattern:
*
- * /articles\/(?P\d{4})\/(?P\d{2})\/(?P\d+)/u
+ * /^articles\/(?P\d{4})\/(?P\d{2})\/(?P\d+)$/u
*
* The above regular expression used the "named group" feature available in PHP.
* Notice that you need to escape the slash in regular expressions.
*
- * In the TUrlMappingPattern class, the pattern is matched against the
- * path property of the url only.
- *
* Thus, only an url that matches the pattern will be valid. For example,
- * an url "http://example.com/articles/2006/07/21" will matches and is valid.
- * However, "http://example.com/articles/2006/07/hello" is not
- * valid since the "day" parameter pattern is not satisfied.
+ * a URL http://example.com/index.php/articles/2006/07/21 will match the above pattern,
+ * while http://example.com/index.php/articles/2006/07/hello will not
+ * since the "day" parameter pattern is not satisfied.
*
- * The parameter values are available through the standard Request
- * object. For example, $this->Request['year'].
+ * The parameter values are available through the THttpRequest instance (e.g.
+ * $this->Request['year']).
*
* The {@link setServiceParameter ServiceParameter} and {@link setServiceID ServiceID}
* (the default ID is 'page') set the service parameter and service id respectively.
- * The service parameter for the TPageService is the Page class name, other service
- * may use the service parameter differently.
- *
- * For more complicated mappings, the body of the <url>
- * can be used to specify the mapping pattern.
*
* @author Wei Zhuo