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

### Url::ezcUrlConfiguration

### Class ezcUrlConfiguration

ezcUrlConfiguration makes it possible to use a custom URL form in your application.

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" )
29. // to remove parameters from the URL configuration $urlCfg
30. $urlCfg-> removeOrderedParameter ('subcategory');
31. $urlCfg-> removeUnorderedParameter ('game');
33. // to remove parameters from the URL configuration stored in the URL
34. $url->configuration-> removeOrderedParameter ('subcategory');
35. $url->configuration-> removeUnorderedParameter ('game');

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" ) )

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

Version: | //autogen//

### Constants

`AGGREGATE_ARGUMENTS = 4`

Flag for specifying aggregation for unordered parameter values if the parameter name appears more than once in the URL.

For example, if the URL is 'http://www.example.com/(param1)/x/(param1)/y/z', then all values will be considered for the parameter param1. So $url->getParam( 'param1' ) will return array( array( "x" ), array( "y", "z" ) ), if $url is an ezcUrl object created from the above URL.

`MULTIPLE_ARGUMENTS = 2` | Flag for specifying multiple arguments for unordered parameters.
`SINGLE_ARGUMENT = 1` | Flag for specifying single arguments for unordered parameters.

### Properties

string | read/write | `$basedir` The part of the URL after the first slash. It can be null. Example: $basedir = shop in http://www.example.com/shop
array(string=>int) | read/write | `$orderedParameters` The ordered parameters of the URL. Example: $orderedParameters = array( 'section' => 0, 'module' => 1, 'view' => 2, 'content' => 3 ); url = http://www.example.com/doc/components/view/trunk The numbers in the array represent the indices for each parameter.
string | read/write | `$script` The default php script, which comes after the basedir. Can be null if the web server configuration is set to hide it. Example: $script = index.php in http://www.example.com/shop/index.php
array(string) | read/write | `$unorderedDelimiters` The delimiters for the unordered parameters names. Example: $unorderedDelimiters = array( '(', ')' ) for url = http://www.example.com/doc/(file)/classtrees_Base.html
array(string=>int) | read/write | `$unorderedParameters` The unordered parameters of the URL. Example: $unorderedParameters = array( 'file' => SINGLE_ARGUMENT ); url = http://www.example.com/doc/(file)/classtrees_Base.html The keys of the array represent the parameter names, and the values in the array represent the types of the parameters.

### Method Summary

public static ezcUrlConfiguration | `getInstance( )` Returns the instance of the class.
public ezcUrlConfiguration | `__construct( )` Constructs a new ezcUrlConfiguration object.
public void | `addOrderedParameter( $name )` Adds an ordered parameter to the URL configuration.
public void | `addUnorderedParameter( $name , [ $type = null] )` Adds an unordered parameter to the URL configuration.
public void | `removeOrderedParameter( $name )` Removes an ordered parameter from the URL configuration.
public void | `removeUnorderedParameter( $name )` Removes an unordered parameter from the URL configuration.

### Methods

#### getInstance

static ezcUrlConfiguration getInstance( )

Returns the instance of the class.

#### __construct

ezcUrlConfiguration __construct( )

Constructs a new ezcUrlConfiguration object.

The properties of the object get default values, which can be changed by setting the properties directly, like:

1. $urlCfg=new ezcUrlConfiguration ();
2. $urlCfg->basedir='mydir';
3. $urlCfg->script='index.php';

#### addOrderedParameter

void addOrderedParameter( string $name )

Adds an ordered parameter to the URL configuration.

Ordered parameters must be added before unordered parameters, and they must appear in the parsed URL in the same number and order as they are defined in the configuration.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | The name of the ordered parameter to add to the configuration

#### addUnorderedParameter

void addUnorderedParameter( string $name , [int $type = null] )

Adds an unordered parameter to the URL configuration.

The possible values for the $type parameter are:

- ezcUrlConfiguration::SINGLE_ARGUMENT (default): the getParam() method in ezcUrl will return a string containing the value of the parameter $name
- ezcUrlConfiguration::MULTIPLE_ARGUMENTS: the getParam() method will return an array containing the last encountered values of the parameter $name
- ezcUrlConfiguration::AGGREGATE_ARGUMENTS: the getParam() method will return an array with all encountered values for the parameter $name

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',$urlCfg);
6. $param1=$url->getParam('param1');// will return "x"
8. // multiple parameter values
9. $urlCfg-> addUnorderedParameter ('param1', ezcUrlConfiguration ::MULTIPLE_ARGUMENTS);
10. $url=new ezcUrl ('http://www.example.com/(param1)/x/y',$urlCfg);
11. $param1=$url->getParam('param1');// will return array( "x", "y" )
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 parameters must be added before unordered parameters, and they must appear in the parsed URL in the same number and order as they are defined in the configuration.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | The name of the unordered parameter to add to the configuration
`$type` | int | The type of the unordered parameter

#### removeOrderedParameter

void removeOrderedParameter( string $name )

Removes an ordered parameter from the URL configuration.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | The name of the ordered parameter to remove from the configuration

#### removeUnorderedParameter

void removeUnorderedParameter( string $name )

Removes an unordered parameter from the URL configuration.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | The name of the unordered parameter to remove from the configuration

Documentation generated by phpDocumentor 1.4.3