Working with path, params and query parts

Do not work with the path, params and query properties directly, because this will not work in PHP 5.2.0 (that is, do not set/get $url->query[0], because a notice will be thrown: "Notice: Indirect modification of overloaded property ezcUrl::$query has no effect"). Instead, use the following methods.

Using url configurations

By using the ezcUrlConfiguration class, you can specify a custom configuration that can be used to parse urls. The properties you can set in objects of this class are the default base directory, default script name (eg. index.php) (which will be hidden when building the url by default, but can be displayed by calling buildUrl( true )), delimiters for unordered parameter names and names for accepted parameters.

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

Working with a variable number of ordered parameters is explained in the Changing a url configuration dynamically section.

Getting the query part

Here is an example of getting the query part of urls:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create a new Url object from a string url
5. $url = new ezcUrl( 'http://www.example.com/mydir/index.php/content/view/article/42/mode/print?user[name]=Bob+Smith&user[age]=47&user[sex]=M' );
7. // get the query parts
8. var_dump( $url->getQuery() );
10. ?>

The output would be:

array(1) {
  ["user"]=>
  array(3) {
    ["name"]=>
    string(9) "Bob Smith"
    ["age"]=>
    string(2) "47"
    ["sex"]=>
    string(1) "M"
  }
}

Setting the query part

Here is an example of setting the query part of urls:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create a new Url object from a string url
5. $url = new ezcUrl( 'http://www.example.com/mydir/index.php/content/view/article/42/mode/print?user[name]=Bob+Smith&user[age]=47&user[sex]=M' );
7. // create an array which will be used to set the query part
8. $query = array( 'user' => array( 'name' => 'Bob Smith',
9. 'age' => '47',
10. 'sex' => 'M',
11. 'dob' => '5/12/1956'),
12. );
14. // set the query part of the Url object
15. $url->setQuery( $query );
16. var_dump( rawurldecode( $url ) );
18. // add a query parameter to the query part
19. $url->setQuery( array_merge( $url->getQuery(), array( 'sort' => 'desc' ) ) );
20. var_dump( rawurldecode( $url ) );
22. // remove a query parameter from the query part
23. $url->setQuery( array_diff_key( $url->getQuery(), array( 'sort' => null ) ) );
24. var_dump( rawurldecode( $url ) );
26. ?>

The output would be as follows (wrapped for clarity):

string(139) "http://www.example.com/mydir/index.php/content/view/article/
42/mode/print?user[name]=Bob+Smith&user[age]=47&user[sex]=M&user[dob]=
5/12/1956"

string(149) "http://www.example.com/mydir/index.php/content/view/article/
42/mode/print?user[name]=Bob+Smith&user[age]=47&user[sex]=M&user[dob]=
5/12/1956&sort=desc"

string(139) "http://www.example.com/mydir/index.php/content/view/article/
42/mode/print?user[name]=Bob+Smith&user[age]=47&user[sex]=M&user[dob]=
5/12/1956"

Creating and using a custom url configuration

The following example creates a custom url configuration and uses it when creating a new url object:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create an ezcUrlConfiguration object
5. $urlCfg = new ezcUrlConfiguration();
7. // set the basedir and script values
8. $urlCfg->basedir = 'mydir';
9. $urlCfg->script = 'index.php';
11. // define delimiters for unordered parameter names
12. $urlCfg->unorderedDelimiters = array( '(', ')' );
14. // define ordered parameters
15. $urlCfg->addOrderedParameter( 'section' );
16. $urlCfg->addOrderedParameter( 'group' );
17. $urlCfg->addOrderedParameter( 'category' );
18. $urlCfg->addOrderedParameter( 'subcategory' );
20. // define unordered parameters
21. $urlCfg->addUnorderedParameter( 'game' );
23. // visualize the $urlCfg object
24. var_dump( $urlCfg );
26. // create a new ezcUrl object from a string url and use the above $urlCfg
27. $url = new ezcUrl( 'http://www.example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7', $urlCfg );
29. ?>

The output would be:

object(ezcUrlConfiguration)#1 (1) {
  ["properties:private"]=>
  array(5) {
    ["basedir"]=>
    string(5) "mydir"
    ["script"]=>
    string(9) "index.php"
    ["unorderedDelimiters"]=>
    array(2) {
      [0]=>
      string(1) "("
      [1]=>
      string(1) ")"
    }
    ["orderedParameters"]=>
    array(4) {
      ["section"]=>
      int(0)
      ["group"]=>
      int(1)
      ["category"]=>
      int(2)
      ["subcategory"]=>
      int(3)
    }
    ["unorderedParameters"]=>
    array(1) {
      ["game"]=>
      int(0)
    }
  }
}

Lazy initialization

Lazy initialization is a mechanism to load and configure a component, only when it is really used in your application. This mechanism saves time for parsing the classes and configuration, when the component is not used at all during one request. You can find a description how you can use it for your own components and how it works in the ezcBase tutorial. The keyword for the url component is ezcUrlConfiguration.

1. <?php
2. require_once 'tutorial_autoload.php';
4. class customLazyUrlConfiguration implements ezcBaseConfigurationInitializer
5. {
6. public static function configureObject( $urlCfg )
7. {
8. // set the basedir and script values
9. $urlCfg->basedir = 'mydir';
10. $urlCfg->script = 'index.php';
12. // define delimiters for unordered parameter names
13. $urlCfg->unorderedDelimiters = array( '(', ')' );
15. // define ordered parameters
16. $urlCfg->addOrderedParameter( 'section' );
17. $urlCfg->addOrderedParameter( 'group' );
18. $urlCfg->addOrderedParameter( 'category' );
19. $urlCfg->addOrderedParameter( 'subcategory' );
21. // define unordered parameters
22. $urlCfg->addUnorderedParameter( 'game' );
23. }
24. }
26. ezcBaseInit::setCallback(
27. 'ezcUrlConfiguration',
28. 'customLazyUrlConfiguration'
29. );
31. // Classes loaded and configured on first request
32. $url = new ezcUrl(
33. 'http://www.example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7',
34. ezcUrlConfiguration::getInstance()
35. );
36. ?>

This examples configures the URL component exactly like the example before. The main difference is, that we roll out the configuration to an own class, and define a callback using ezcBaseInit::setCallback to this class, which will be called with a url configuration instance as the first parameter on the first call on ezcUrlConfiguration::getInstance().

ezcBaseInit::setCallback accepts as a first parameter a component specific key, which lets the component later request the right configuration callback. The second parameter is the name of the class to perform the static callback on. This class must implement the ezcBaseConfigurationInitializer class. Each component's lazy initialization calls the static method configureObject() on the referenced class.

When the URL is really parsed in your application, like shown in line 35 of the example, a new ezcUrlConfiguration is instatiated an automatically configured by the configureObject() method.

Getting parameters using a url configuration

The following example uses the custom url configuration from before to get the parameters from the provided url:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create an ezcUrlConfiguration object
5. $urlCfg = new ezcUrlConfiguration();
7. // set the basedir and script values
8. $urlCfg->basedir = 'mydir';
9. $urlCfg->script = 'index.php';
11. // define delimiters for unordered parameter names
12. $urlCfg->unorderedDelimiters = array( '(', ')' );
14. // define ordered parameters
15. $urlCfg->addOrderedParameter( 'section' );
16. $urlCfg->addOrderedParameter( 'group' );
17. $urlCfg->addOrderedParameter( 'category' );
18. $urlCfg->addOrderedParameter( 'subcategory' );
20. // define unordered parameters
21. $urlCfg->addUnorderedParameter( 'game', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
23. // create a new ezcUrl object from a string url and use the above $urlCfg
24. $url = new ezcUrl( 'http://www.example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7', $urlCfg );
26. // get the parameter values from the url
27. var_dump( $url->getParam( 'section' ) );
28. var_dump( $url->getParam( 'group' ) );
29. var_dump( $url->getParam( 'category' ) );
30. var_dump( $url->getParam( 'subcategory' ) );
31. var_dump( $url->getParam( 'game' ) );
33. // output the url (index.php will not be there)
34. var_dump( $url->buildUrl() );
36. // output the url (with index.php included)
37. var_dump( $url->buildUrl( true ) );
38. ?>

The output would be as follows (wrapped for clarity):

string(6) "groups"
string(5) "Games"
string(9) "Adventure"
string(5) "Adult"
array(2) {
  [0]=>
  string(5) "Larry"
  [1]=>
  string(1) "7"
}
string(72) "http://www.example.com/mydir/groups/Games/Adventure/Adult/
(game)/Larry/7"
string(82) "http://www.example.com/mydir/index.php/groups/Games/Adventure/
Adult/(game)/Larry/7"

Getting parameters by aggregating values for unordered parameters

If the URL contains multiple appearances of an unordered parameter (for example 'http://www.example.com/(param1)/x/(param1)/y/z'), then by default only the last encountered values are returned when calling getParam().

To return all the values (to aggregate values) as an array of arrays (for example, array( array( 'x' ), array( 'y', 'z' ) ) for the above URL), use ezcUrlConfiguration::AGGREGATE_ARGUMENTS as the second parameter when calling addUnorderedParameter(), like in this example:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create an ezcUrlConfiguration object
5. $urlCfg = new ezcUrlConfiguration();
7. // single parameter value
8. $urlCfg->addUnorderedParameter( 'param1' );
9. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
10. var_dump( $url->getParam( 'param1' ) ); // will output "y"
12. // multiple parameter values
13. $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
14. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
15. var_dump( $url->getParam( 'param1' ) ); // will output array( "y", "z" )
17. // multiple parameter values with aggregation
18. $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
19. $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
20. var_dump( $url->getParam( 'param1' ) ); // will output array( array( "x" ), array( "y", "z" ) )
22. // output the url (it will be similar to the input url)
23. var_dump( $url->buildUrl() );
24. ?>

The output will be:

string(1) "y"
array(2) {
  [0]=>
  string(1) "y"
  [1]=>
  string(1) "z"
}
array(2) {
  [0]=>
  array(1) {
    [0]=>
    string(1) "x"
  }
  [1]=>
  array(2) {
    [0]=>
    string(1) "y"
    [1]=>
    string(1) "z"
  }
}
string(46) "http://www.example.com/(param1)/x/(param1)/y/z"

Getting unordered parameters without name delimiters

If the URL doesn't contain delimiters for unordered parameter names, then you can use the getParams() method to return the values after the basedir, script and ordered parameters as a flat array. This array can be parsed later by your application to make it an associative array.

Example:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create an ezcUrlConfiguration object
5. $urlCfg = new ezcUrlConfiguration();
7. $urlCfg->basedir = '/mydir/shop';
8. $urlCfg->script = 'index.php';
9. $urlCfg->addOrderedParameter( 'module' );
11. $url = new ezcUrl( 'http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl', $urlCfg );
13. // get the unordered parameters as a flat array
14. var_dump( $url->getParams() ); // will output array( 'Software', 'PHP', 'Version', '5.2', 'Extension', 'XDebug', 'Extension', 'openssl' )
15. ?>

The output will be:

array(8) {
  [0]=>
  string(8) "Software"
  [1]=>
  string(3) "PHP"
  [2]=>
  string(7) "Version"
  [3]=>
  string(3) "5.2"
  [4]=>
  string(9) "Extension"
  [5]=>
  string(6) "XDebug"
  [6]=>
  string(9) "Extension"
  [7]=>
  string(7) "openssl"
}

This array can then be translated by your application to this form (if needed):

array( "Software" => array( "PHP" ),
    "Version" => array( "5.2" ),
    "Extension" => array( "XDebug", "openssl" )
);

Setting parameters using a url configuration

The following example uses the custom url configuration from before to set the parameters into the provided url:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create an ezcUrlConfiguration object
5. $urlCfg = new ezcUrlConfiguration();
7. // set the basedir and script values
8. $urlCfg->basedir = 'mydir';
9. $urlCfg->script = 'index.php';
11. // define delimiters for unordered parameter names
12. $urlCfg->unorderedDelimiters = array( '(', ')' );
14. // define ordered parameters
15. $urlCfg->addOrderedParameter( 'section' );
16. $urlCfg->addOrderedParameter( 'group' );
17. $urlCfg->addOrderedParameter( 'category' );
18. $urlCfg->addOrderedParameter( 'subcategory' );
20. // define unordered parameters
21. $urlCfg->addUnorderedParameter( 'game', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
22. $urlCfg->addUnorderedParameter( 'patches', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
24. // create a new ezcUrl object from a string url and use the above $urlCfg
25. $url = new ezcUrl( 'http://www.example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7', $urlCfg );
26. var_dump( $url->buildUrl() );
28. // set the parameter values in the url
29. $url->setParam( 'subcategory', 'Kids' );
30. $url->setParam( 'game', array( 'Monkey_Island', '3' ) );
31. var_dump( $url->buildUrl() );
33. $url->setParam( 'patches', array( array( 'beta1' ), array( 'rc1', 'rc2' ) ) );
34. var_dump( $url->buildUrl() );
35. ?>

The output would be as follows (wrapped for clarity):

string(72) "http://www.example.com/mydir/groups/Games/Adventure/Adult/
(game)/Larry/7"

string(79) "http://www.example.com/mydir/groups/Games/Adventure/Kids/
(game)/Monkey_Island/3"

string(113) "http://www.example.com/mydir/groups/Games/Adventure/Kids/
(game)/Monkey_Island/3/(patches)/beta1/(patches)/rc1/rc2"

Changing a url configuration dynamically

The following example uses the custom url configuration from before to set the parameters into the provided url:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // create a default url configuration
5. $urlCfgDefault = new ezcUrlConfiguration();
6. $urlCfgDefault->addOrderedParameter( 'section' );
8. // create a configuration for artists
9. $urlCfgArtist = new ezcUrlConfiguration();
10. $urlCfgArtist->addOrderedParameter( 'section' );
11. $urlCfgArtist->addOrderedParameter( 'artist_name' );
13. // create a configuration for albums
14. $urlCfgAlbum = new ezcUrlConfiguration();
15. $urlCfgAlbum->addOrderedParameter( 'section' );
16. $urlCfgAlbum->addOrderedParameter( 'artist_name' );
17. $urlCfgAlbum->addOrderedParameter( 'album_name' );
19. // create a configuration for music genres
20. $urlCfgGenre = new ezcUrlConfiguration();
21. $urlCfgGenre->addOrderedParameter( 'section' );
22. $urlCfgGenre->addOrderedParameter( 'genre_name' );
24. $url = new ezcUrl( 'http://mymusicsite.com/showartist/Beatles', $urlCfgDefault );
26. switch ( $url->getParam( 'section' ) )
27. {
28. case 'showartist':
29. $url->applyConfiguration( $urlCfgArtist );
30. $artist = $url->getParam( 'artist_name' );
31. // do stuff with $artist
32. var_dump( $artist );
33. break;
34. case 'showalbum':
35. $url->applyConfiguration( $urlCfgAlbum );
36. $artist = $url->getParam( 'artist_name' );
37. $album = $url->getParam( 'album_name' );
38. // do stuff with $artist and $album
39. var_dump( $artist );
40. var_dump( $album );
41. break;
42. case 'showgenre':
43. $url->applyConfiguration( $urlCfgGenre );
44. $genre = $url->getParam( 'genre_name' );
45. // do stuff with $genre
46. var_dump( $genre );
47. break;
48. }
50. ?>

The output would be:

string(7) "Beatles"

Appending a suffix to a url

With the url creator, you can register a url under an alias, then use that alias when you want to prepend the url to a file name.

1. <?php
2. require_once 'tutorial_autoload.php';
4. // register an url under the alias 'map'
5. ezcUrlCreator::registerUrl( 'map', '/images/geo?xsize=450&ysize=450&zoom=4' );
7. // display the the url prepended to map_norway.gif
8. var_dump( ezcUrlCreator::prependUrl( 'map', 'map_norway.gif' ) );
10. // display the the url prepended to map_sweden.gif
11. var_dump( ezcUrlCreator::prependUrl( 'map', 'map_sweden.gif' ) );
13. // display the stored url under the alias 'map'
14. var_dump( ezcUrlCreator::getUrl( 'map' ) );
16. ?>

The output would be:

string(53) "/images/geo/map_norway.gif?xsize=450&ysize=450&zoom=4"

string(53) "/images/geo/map_sweden.gif?xsize=450&ysize=450&zoom=4"

string(38) "/images/geo?xsize=450&ysize=450&zoom=4"

Using formatting for a url

With the url creator, you can register a url under an alias, then use that alias when you want to apply formatting to a url.

1. <?php
2. require_once 'tutorial_autoload.php';
4. // register an url under the alias 'map'
5. ezcUrlCreator::registerUrl( 'map', '/images/geo/%s?xsize=%d&ysize=%d&zoom=%d' );
7. // display the stored url under the alias 'map' formatted with parameters
8. var_dump( ezcUrlCreator::getUrl( 'map', 'map_norway.gif', 450, 450, 4 ) );
10. // display the stored url under the alias 'map' formatted with other parameters
11. var_dump( ezcUrlCreator::getUrl( 'map', 'map_sweden.gif', 450, 450, 4 ) );
12. ?>

The output would be:

string(53) "/images/geo/map_norway.gif?xsize=450&ysize=450&zoom=4"

string(53) "/images/geo/map_sweden.gif?xsize=450&ysize=450&zoom=4"

getCurrentUrl

This function builds the current url from the $_SERVER array or another array source. The $_SERVER array is used by default, but another array source can be specified as a parameter when calling the function.

For example, if the $_SERVER array has these fields:

1. <?php
2. $_SERVER = array(
3. 'HTTPS' => '1',
4. 'SERVER_NAME' => 'www.example.com',
5. 'SERVER_PORT' => 80,
6. 'REQUEST_URI' => '/index.php'
7. );
9. $url = ezcUrlTools::getCurrentUrl();
10. ?>

Then $url will be:

https://www.example.com/index.php

parseQueryString

This function has the same functionality as the PHP function parse_str(), but without converting the dots to underscores in query parameter names.

Example:

1. <?php
2. $params = ezcUrlTools::parseQueryString(
3. 'openid.nonce=123456&foo[]=bar&foo[]=baz' );
4. ?>

Then $params will be:

array(2) {
  ["openid.nonce"]=>
  string(6) "123456"
  ["foo"]=>
  array(2) {
    [0]=>
    string(3) "bar"
    [1]=>
    string(3) "baz"
  }
}

By calling parse_str() on the same string, instead of 'openid.nonce' as a key in $params there would have been 'openid_nonce'.