ezcUrl stores an URL both absolute and relative and contains methods to retrieve the various parts of the URL and to manipulate them.
A URL is assumed to be of this form: scheme://host/basedir/script/ordered_parameters/unordered_parameters
Example: http://example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7
Where: scheme = "http" host = "example.com" basedir = "mydir" script = "index.php" ordered parameters = "groups", "Games", "Adventure", "Adult" unordered parameters = array( "Larry", "7" )
When creating a configuration with ordered parameters, those parameters are required to be present in the parsed URL, in the same number as the configuration states. Having a different number of ordered parameters in the parsed URL will lead to wrong values assigned to the unordered parameters (if any follow the ordered parameters).
See the tutorial for a way to change configurations dynamically based on the ordered parameters.
Example of use:
Example of aggregating values for unordered parameters:
Unordered parameters can also be fetched as a flat array (useful if the URL doesn't have delimiters for the unordered parameter names). Example:
Source for this file: /Url/src/url.php
Version: | //autogen// |
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. |
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(). |
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().
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 |
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.
Name | Type | Description |
---|---|---|
$configuration |
ezcUrlConfiguration | An URL configuration used in parsing |
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).
Name | Type | Description |
---|---|---|
$includeScriptName |
bool |
Returns the value of the specified parameter from the URL based on the active URL configuration.
Ordered parameters must appear before unordered parameters in the parsed URL, in the same number and order as they are defined in the configuration.
Unordered parameter examples:
Ordered parameter examples:
Name | Type | Description |
---|---|---|
$name |
string | The name of the parameter for which to return the value |
Type | Description |
---|---|
ezcUrlInvalidParameterException |
if the specified parameter is not defined in the URL configuration |
ezcUrlNoConfigurationException |
if an URL configuration is not defined |
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:
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' )
Returns true if this URL is relative and false if the URL is absolute.
Returns ordered parameters from the $path array.
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 |
Returns unordered parameters from the $path array.
The format of the returned array is:
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:
For the URL 'http://www.example.com/(param1)/x/(param1)/y/z', these methods can be employed to get the values of param1:
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).
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 |
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:
If there are ordered and unordered parameters with the same name, only the ordered parameter value will be set.
Examples:
Name | Type | Description |
---|---|---|
$name |
string | The name of the parameter to set |
$value |
string|array(string=>mixed) | The new value of the parameter |
Type | 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 |
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'
Name | Type | Description |
---|---|---|
$query |
array(string=>mixed) | The new value of the query part |
Returns this URL as a string by calling buildUrl().