## Apache Zeta Components Manual :: Docs For Class ezcUrl

### 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.

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:

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';
7. // define delimiters for unordered parameter names
8. $urlCfg->unorderedDelimiters=array('(',')');
10. // define ordered parameters
11. $urlCfg->addOrderedParameter('section');
12. $urlCfg->addOrderedParameter('group');
13. $urlCfg->addOrderedParameter('category');
14. $urlCfg->addOrderedParameter('subcategory');
16. // define unordered parameters
17. $urlCfg->addUnorderedParameter('game', ezcUrlConfiguration ::MULTIPLE_ARGUMENTS);
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);
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"
27. $game=$url-> getParam ('game');// will be array( "Larry", "7" )

Example of aggregating values for unordered parameters:

1. $urlCfg=new ezcUrlConfiguration ();
3. $urlCfg->addUnorderedParameter('param1', ezcUrlConfiguration ::AGGREGATE_ARGUMENTS);
4. $url=new ezcUrl ('http://www.example.com/(param1)/x/(param1)/y/z',$urlCfg);
6. $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');
6. $url=new ezcUrl ('http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl',$urlCfg);
8. $params=$url-> getParams ();// will be array( 'Software', 'PHP', 'Version', '5.2', 'Extension', 'XDebug', 'Extension', 'openssl' )

Source for this file: /Url/src/url.php

Version: | //autogen//

### 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

ezcUrl __construct( [string $url = null] , [ezcUrlConfiguration $configuration = null] )

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

void applyConfiguration( ezcUrlConfiguration $configuration )

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:

Name | Type | Description
--- | --- | ---
`$configuration` | ezcUrlConfiguration | An URL configuration used in parsing

#### 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.

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:

1. $urlCfg=new ezcUrlConfiguration ();
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"
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" )
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);
16. $param1=$url-> getParam ('param1');// will return array( array( "x" ), array( "y", "z" ) )

Ordered parameter examples:

1. $urlCfg=new ezcUrlConfiguration ();
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"
7. $param2=$url-> getParam ('param2');// will return "y"

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | The name of the parameter for which to return the value

##### Exceptions:

Type | Description
--- | ---
`ezcUrlInvalidParameterException` | if the specified parameter is not defined in the URL configuration
`ezcUrlNoConfigurationException` | if an URL configuration is not defined

#### 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');
6. $url=new ezcUrl ('http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl',$urlCfg);
8. $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 ();
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"
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" )
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);
16. $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');
4. $url=new ezcUrl ('http://www.example.com');
6. $url-> setParam ('param1','x');
7. echo$url-> buildUrl ();// will output http://www.example.com/(param1)/x
9. $url-> setParam ('param1',array('x','y') );
10. echo$url-> buildUrl ();// will output http://www.example.com/(param1)/x/y
12. $url-> setParam ('param1',array(array('x'),array('y','z') ) );
13. 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

##### Exceptions:

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

#### 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().

Documentation generated by phpDocumentor 1.4.3