Apache Zeta Components - high quality PHP components

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';
  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"
  27.  $game = $url->getParam( 'game' ); // will be array( "Larry", "7" )
  28.  
  29.  // to remove parameters from the URL configuration $urlCfg
  30.  $urlCfg->removeOrderedParameter( 'subcategory' );
  31.  $urlCfg->removeUnorderedParameter( 'game' );
  32.  
  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();
  2.  
  3.  $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
  4.  $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
  5.  
  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:

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', $urlCfg );
  6.  $param1 = $url->getParam( 'param1' ); // will return "x"
  7.  
  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" )
  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 );
  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
Copyright © 2010 The Apache Software Foundation