Url: ezcUrl
[ ]
[ ]
[ ]
[ ]
[ ]
Class: ezcUrl
|
ezcUrl stores an URL both absolute and relative and contains methods to retrieve the various parts of the URL and to manipulate them. [
source]
Example of use:
1. // create an ezcUrlConfiguration object
2. $urlCfg = new ezcUrlConfiguration();
3. // set the basedir and script values
4. $urlCfg->basedir = 'mydir';
5. $urlCfg->script = 'index.php';
6.
7. // define delimiters for unordered parameter names
8. $urlCfg->unorderedDelimiters = array( '(', ')' );
9.
10. // define ordered parameters
11. $urlCfg->addOrderedParameter( 'section' );
12. $urlCfg->addOrderedParameter( 'group' );
13. $urlCfg->addOrderedParameter( 'category' );
14. $urlCfg->addOrderedParameter( 'subcategory' );
15.
16. // define unordered parameters
17. $urlCfg->addUnorderedParameter( 'game', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
18.
19. // create a new ezcUrl object from a string URL and use the above $urlCfg
20. $url = new ezcUrl( 'http://www.example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7', $urlCfg );
21.
22. // to get the parameter values from the URL use $url->getParam():
23. $section = $url->getParam( 'section' ); // will be "groups"
24. $group = $url->getParam( 'group' ); // will be "Games"
25. $category = $url->getParam( 'category' ); // will be "Adventure"
26. $subcategory = $url->getParam( 'subcategory' ); // will be "Adult"
26. $game = $url->getParam( 'game' ); // will be array( "Larry", "7" )
Example of aggregating values for unordered parameters:
1. $urlCfg = new ezcUrlConfiguration();
2.
3. $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
4. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
5.
5. $param1 = $url->getParam( 'param1' ); // will be array( array( "x" ), array( "y", "z" ) )
Unordered parameters can also be fetched as a flat array (useful if the URL doesn't have delimiters for the unordered parameter names). Example:
1. $urlCfg = new ezcUrlConfiguration();
2. $urlCfg->basedir = '/mydir/shop';
3. $urlCfg->script = 'index.php';
4. $urlCfg->addOrderedParameter( 'module' );
5.
6. $url = new ezcUrl( 'http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl', $urlCfg );
7.
7. $params = $url->getParams(); // will be array( 'Software', 'PHP', 'Version', '5.2', 'Extension', 'XDebug', 'Extension', 'openssl' )
Properties
|
array(string) |
read/write
|
$basedir
Base directory (the part before the script name) or null. |
|
ezcUrlConfiguration |
read/write
|
$configuration
The URL configuration defined for this URL, or null. |
|
string |
read/write
|
$fragment
Anchor or null. |
|
string |
read/write
|
$host
Hostname or null |
|
array(string) |
read/write
|
$params
Complete ordered parameters as array. |
|
string |
read/write
|
$pass
Password or null. |
|
array(string) |
read/write
|
$path
Complete path as an array. |
|
string |
read/write
|
$port
Port or null. |
|
array(string=>mixed) |
read/write
|
$query
Complete query string as an associative array. |
|
string |
read/write
|
$scheme
Protocol or null. |
|
array(string) |
read/write
|
$script
Script name (eg. 'index.php') or null. |
|
array(string=>mixed) |
read/write
|
$uparams
Complete unordered parameters as associative array. |
|
string |
read/write
|
$user
User or null. |
Method Summary
|
public ezcUrl |
__construct(
[$url = null], [$configuration = null] )
Constructs a new ezcUrl object from the string $url. |
|
public void |
applyConfiguration(
$configuration )
Applies the URL configuration $configuration to the current url. |
|
public string |
buildUrl(
[$includeScriptName = false] )
Returns this URL as a string. |
|
public mixed |
getParam(
$name )
Returns the value of the specified parameter from the URL based on the active URL configuration. |
|
public array(string) |
getParams(
)
Returns the unordered parameters from the URL as a flat array. |
|
public array(string=>mixed) |
getQuery(
)
Returns the query elements as an associative array. |
|
public bool |
isRelative(
)
Returns true if this URL is relative and false if the URL is absolute. |
|
public array(string=>mixed) |
parseOrderedParameters(
$config, $index )
Returns ordered parameters from the $path array. |
|
public array(string=>mixed) |
parseUnorderedParameters(
$config, $index )
Returns unordered parameters from the $path array. |
|
public void |
setParam(
$name, $value )
Sets the specified parameter in the URL based on the URL configuration. |
|
public void |
setQuery(
$query )
Set the query elements using the associative array provided. |
|
public string |
__toString(
)
Returns this URL as a string by calling buildUrl(). |
Methods
__construct
Constructs a new ezcUrl object from the string $url.
If the $configuration parameter is provided, then it will apply the configuration to the URL by calling
applyConfiguration().
Parameters
| Name |
Type |
Description |
$url |
string |
A string URL from which to construct the URL object |
$configuration |
ezcUrlConfiguration |
An optional URL configuration used when parsing and building the URL |
applyConfiguration
Applies the URL configuration $configuration to the current url.
It fills the arrays $basedir, $script, $params and $uparams with values from $path.
It also sets the property configuration to the value of $configuration.
Parameters
buildUrl
string buildUrl(
[bool
$includeScriptName = false] )
Returns this URL as a string.
The query part of the URL is build with http_build_query() which encodes the query in a similar way to urlencode().
If $includeScriptName is true, then the script name (eg. 'index.php') will be included in the result. By default the script name is hidden (to ensure backwards compatibility).
Parameters
| Name |
Type |
Description |
$includeScriptName |
bool |
|
getParam
mixed getParam(
string
$name )
Returns the value of the specified parameter from the URL based on the active URL configuration.
Unordered parameter examples:
1. $urlCfg = new ezcUrlConfiguration();
2.
3. // single parameter value
4. $urlCfg->addUnorderedParameter( 'param1' ); // type is SINGLE_ARGUMENT by default
5. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
6. $param1 = $url->getParam( 'param1' ); // will return "y"
7.
8. // multiple parameter values
9. $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
10. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
11. $param1 = $url->getParam( 'param1' ); // will return array( "y", "z" )
12.
13. // multiple parameter values with aggregation
14. $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
15. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
15. $param1 = $url->getParam( 'param1' ); // will return array( array( "x" ), array( "y", "z" ) )
Ordered parameter examples:
1. $urlCfg = new ezcUrlConfiguration();
2.
3. $urlCfg->addOrderedParameter( 'param1' );
4. $urlCfg->addOrderedParameter( 'param2' );
5. $url = new ezcUrl( 'http://www.example.com/x/y', $urlCfg );
6. $param1 = $url->getParam( 'param1' ); // will return "x"
6. $param2 = $url->getParam( 'param2' ); // will return "y"
Parameters
| Name |
Type |
Description |
$name |
string |
The name of the parameter for which to return the value |
Throws
| Class | Description |
|---|
ezcUrlNoConfigurationException |
if an URL configuration is not defined |
ezcUrlInvalidParameterException |
if the specified parameter is not defined in the URL configuration |
getParams
array(string) getParams(
)
Returns the unordered parameters from the URL as a flat array.
It takes into account the basedir, script and ordered parameters.
It can be used for URLs which don't have delimiters for the unordered parameters.
Example:
1. $urlCfg = new ezcUrlConfiguration();
2. $urlCfg->basedir = '/mydir/shop';
3. $urlCfg->script = 'index.php';
4. $urlCfg->addOrderedParameter( 'module' );
5.
6. $url = new ezcUrl( 'http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl', $urlCfg );
7.
7. $params = $url->getParams(); // will be array( 'Software', 'PHP', 'Version', '5.2', 'Extension', 'XDebug', 'Extension', 'openssl' )
getQuery
array(string=>mixed) getQuery(
)
Returns the query elements as an associative array.
Example: for 'http://www.example.com/mydir/shop?content=view&products=10' returns array( 'content' => 'view', 'products' => '10' )
isRelative
bool isRelative(
)
Returns true if this URL is relative and false if the URL is absolute.
parseOrderedParameters
array(string=>mixed) parseOrderedParameters(
array(string)
$config, int
$index )
Returns ordered parameters from the $path array.
Parameters
| Name |
Type |
Description |
$config |
array(string) |
An array of ordered parameters names, from the URL configuration used in parsing |
$index |
int |
The index in the URL path part from where to start the matching of $config |
parseUnorderedParameters
array(string=>mixed) parseUnorderedParameters(
array(string)
$config, int
$index )
Returns unordered parameters from the $path array.
The format of the returned array is:
1. array( param_name1 => array( 0 => array( value1, value2, ... ),
2. 1 => array( value1, value2, ... ) ),
3. param_name2 = array( 0 => array( value1, value2, ... ),
4. 1 => array( value1, value2, ... ) ), ... )
where 0, 1, etc are numbers meaning the nth encounter of each param_name in the url.
For example, if the URL is 'http://www.example.com/(param1)/a/(param2)/x/(param2)/y/z' then the result of this function will be:
1. array( 'param1' => array( 0 => array( 'a' ) ),
2. 'param2' => array( 0 => array( 'x' ),
3. 1 => array( 'y', 'z' ) ) );
For the URL 'http://www.example.com/(param1)/x/(param1)/y/z', these methods can be employed to get the values of param1:
1. $urlCfg = new ezcUrlConfiguration();
2.
3. // single parameter value
4. $urlCfg->addUnorderedParameter( 'param1' ); // type is SINGLE_ARGUMENT by default
5. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
6. $param1 = $url->getParam( 'param1' ); // will return "y"
7.
8. // multiple parameter values
9. $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
10. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
11. $param1 = $url->getParam( 'param1' ); // will return array( "y", "z" )
12.
13. // multiple parameter values with aggregation
14. $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
15. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
15. $param1 = $url->getParam( 'param1' ); // will return array( array( "x" ), array( "y", "z" ) )
Note: in the examples above, if the URL does not contain the string 'param1', then all the unordered parameters from and including param1 will be null, so $url->getParam( 'param1' ) will return null (see issue
#12825).
Parameters
| Name |
Type |
Description |
$config |
array(string) |
An array of unordered parameters names, from the URL configuration used in parsing |
$index |
int |
The index in the URL path part from where to start the matching of $config |
setParam
void setParam(
string
$name, string|array(string=>mixed)
$value )
Sets the specified parameter in the URL based on the URL configuration.
For ordered parameters, the value cannot be an array, otherwise an ezcBaseValueException will be thrown.
For unordered parameters, the value can be one of:
- string
- array(string)
- array(array(string))
Any of these values can be assigned to an unordered parameter, whatever the parameter type (SINGLE_ARGUMENT, MULTIPLE_ARGUMENTS, AGGREGATE_ARGUMENTS).
If there are ordered and unordered parameters with the same name, only the ordered parameter value will be set.
Examples:
1. $urlCfg = new ezcUrlConfiguration();
2. $urlCfg->addUnorderedParameter( 'param1' );
3.
4. $url = new ezcUrl( 'http://www.example.com' );
5.
6. $url->setParam( 'param1', 'x' );
7. echo $url->buildUrl(); // will output http://www.example.com/(param1)/x
8.
8.
9. $url->setParam( 'param1', array( 'x', 'y' ) );
10. echo $url->buildUrl(); // will output http://www.example.com/(param1)/x/y
11.
11.
12. $url->setParam( 'param1', array( array( 'x' ), array( 'y', 'z' ) ) );
12. echo $url->buildUrl(); // will output http://www.example.com/(param1)/x/(param1)/y/z
Parameters
| Name |
Type |
Description |
$name |
string |
The name of the parameter to set |
$value |
string|array(string=>mixed) |
The new value of the parameter |
Throws
| Class | Description |
|---|
ezcBaseValueException |
if trying to assign an array value to an ordered parameter |
ezcUrlNoConfigurationException |
if an URL configuration is not defined |
ezcUrlInvalidParameterException |
if the specified parameter is not defined in the URL configuration |
setQuery
void setQuery(
array(string=>mixed)
$query )
Set the query elements using the associative array provided.
Example: for 'http://www.example.com/mydir/shop' and $query = array( 'content' => 'view', 'products' => '10' ) then 'http://www.example.com/mydir/shop?content=view&products=10'
Parameters
| Name |
Type |
Description |
$query |
array(string=>mixed) |
The new value of the query part |
__toString
string __toString(
)
Returns this URL as a string by calling buildUrl().
Last updated: Tue, 02 Dec 2008
