Working with path, params and query parts

Do not work with the path, params and query properties directly, because in PHP5.2.0 it will not work (ie. 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 which can be used to parse urls. The properties you can set in objects of this class are the default base directory, default script name (which will be hidden when building the url), delimiters for unordered parameter names, and names for accepted parameters.

Get the query part

Examples of getting the query part of urls:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  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' );
  6. 
  7. // get the query parts
  8. var_dump( $url->getQuery() );
  9. 
 10. ?>

The output will be:

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

Set the query part

Examples of setting the query part of urls:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  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' );
  6. 
  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.               );
 13. 
 14. // set the query part of the Url object
 15. $url->setQuery( $query );
 16. var_dump( rawurldecode( $url ) );
 17. 
 18. // add a query parameter to the query part
 19. $url->setQuery( array_merge( $url->getQuery(), array( 'sort' => 'desc' ) ) );
 20. var_dump( rawurldecode( $url ) );
 21. 
 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 ) );
 25. 
 26. ?>

The output will be (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"

Create and use a custom url configuration

The following example will create a custom url configuration and use it when creating a new url object:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // create an ezcUrlConfiguration object
  5. $urlCfg = new ezcUrlConfiguration();
  6. 
  7. // set the basedir and script values
  8. $urlCfg->basedir = 'mydir';
  9. $urlCfg->script = 'index.php';
 10. 
 11. // define delimiters for unordered parameter names
 12. $urlCfg->unorderedDelimiters = array( '(', ')' );
 13. 
 14. // define ordered parameters
 15. $urlCfg->addOrderedParameter( 'section' );
 16. $urlCfg->addOrderedParameter( 'group' );
 17. $urlCfg->addOrderedParameter( 'category' );
 18. $urlCfg->addOrderedParameter( 'subcategory' );
 19. 
 20. // define unordered parameters
 21. $urlCfg->addUnorderedParameter( 'game' );
 22. 
 23. // visualize the $urlCfg object
 24. var_dump( $urlCfg );
 25. 
 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 );
 28. 
 29. ?>

The output will 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)
    }
  }
}

Get parameters using an url configuration

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

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // create an ezcUrlConfiguration object
  5. $urlCfg = new ezcUrlConfiguration();
  6. 
  7. // set the basedir and script values
  8. $urlCfg->basedir = 'mydir';
  9. $urlCfg->script = 'index.php';
 10. 
 11. // define delimiters for unordered parameter names
 12. $urlCfg->unorderedDelimiters = array( '(', ')' );
 13. 
 14. // define ordered parameters
 15. $urlCfg->addOrderedParameter( 'section' );
 16. $urlCfg->addOrderedParameter( 'group' );
 17. $urlCfg->addOrderedParameter( 'category' );
 18. $urlCfg->addOrderedParameter( 'subcategory' );
 19. 
 20. // define unordered parameters
 21. $urlCfg->addUnorderedParameter( 'game', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
 22. 
 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 );
 25. 
 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' ) );
 32. 
 33. // output the url (index.php will not be there)
 34. var_dump( $url->buildUrl() );
 35. 
 36. ?>

The output will be (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"

Set parameters using an url configuration

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

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // create an ezcUrlConfiguration object
  5. $urlCfg = new ezcUrlConfiguration();
  6. 
  7. // set the basedir and script values
  8. $urlCfg->basedir = 'mydir';
  9. $urlCfg->script = 'index.php';
 10. 
 11. // define delimiters for unordered parameter names
 12. $urlCfg->unorderedDelimiters = array( '(', ')' );
 13. 
 14. // define ordered parameters
 15. $urlCfg->addOrderedParameter( 'section' );
 16. $urlCfg->addOrderedParameter( 'group' );
 17. $urlCfg->addOrderedParameter( 'category' );
 18. $urlCfg->addOrderedParameter( 'subcategory' );
 19. 
 20. // define unordered parameters
 21. $urlCfg->addUnorderedParameter( 'game', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
 22. 
 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 );
 25. var_dump( $url->buildUrl() );
 26. 
 27. // set the parameter values in the url
 28. $url->setParam( 'subcategory', 'Kids' );
 29. $url->setParam( 'game', array( 'Monkey_Island', '3' ) );
 30. var_dump( $url->buildUrl() );
 31. 
 32. ?>

The output will be (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"

Change an url configuration dynamically

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

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // create a default url configuration
  5. $urlCfgDefault = new ezcUrlConfiguration();
  6. $urlCfgDefault->addOrderedParameter( 'section' );
  7. 
  8. // create a configuration for artists
  9. $urlCfgArtist = new ezcUrlConfiguration();
 10. $urlCfgArtist->addOrderedParameter( 'section' );
 11. $urlCfgArtist->addOrderedParameter( 'artist_name' );
 12. 
 13. // create a configuration for albums
 14. $urlCfgAlbum = new ezcUrlConfiguration();
 15. $urlCfgAlbum->addOrderedParameter( 'section' );
 16. $urlCfgAlbum->addOrderedParameter( 'artist_name' );
 17. $urlCfgAlbum->addOrderedParameter( 'album_name' );
 18. 
 19. // create a configuration for music genres
 20. $urlCfgGenre = new ezcUrlConfiguration();
 21. $urlCfgGenre->addOrderedParameter( 'section' );
 22. $urlCfgGenre->addOrderedParameter( 'genre_name' );
 23. 
 24. $url = new ezcUrl( 'http://mymusicsite.com/showartist/Beatles', $urlCfgDefault );
 25. 
 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. }
 49. 
 50. ?>

The output will be:

string(7) "Beatles"

Append a suffix to an url

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

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

The output will 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"

Use formatting for an url

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

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. // register an url under the alias 'map'
  5. ezcUrlCreator::registerUrl( 'map', '/images/geo/%s?xsize=%d&ysize=%d&zoom=%d' );
  6. 
  7. // display the stored url under the alias 'map' formatted with parameters
  8. var_dump( ezcUrlCreator::getUrl( 'map', 'map_norway.gif', 450, 450, 4 ) );
  9. 
 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 will 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"