Apache Zeta Components - high quality PHP components

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

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

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.  
  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();
  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 );
  16.  $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"
  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' );
  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.  
  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();
  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 );
  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' );
  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.  
  9.  $url->setParam( 'param1', array( 'x', 'y' ) );
  10.  echo $url->buildUrl(); // will output http://www.example.com/(param1)/x/y
  11.  
  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
Copyright © 2010 The Apache Software Foundation