Do not work with the path, params and query properties directly, because this
will not work in PHP5.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.
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.
Here is an example 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 would be:
array(1) {
["user"]=>
array(3) {
["name"]=>
string(9) "Bob Smith"
["age"]=>
string(2) "47"
["sex"]=>
string(1) "M"
}
}
Here is an example 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 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"
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';
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 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 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';
3.
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';
11.
12. // define delimiters for unordered parameter names
13. $urlCfg->unorderedDelimiters = array( '(', ')' );
14.
15. // define ordered parameters
16. $urlCfg->addOrderedParameter( 'section' );
17. $urlCfg->addOrderedParameter( 'group' );
18. $urlCfg->addOrderedParameter( 'category' );
19. $urlCfg->addOrderedParameter( 'subcategory' );
20.
21. // define unordered parameters
22. $urlCfg->addUnorderedParameter( 'game' );
23. }
24. }
25.
26. ezcBaseInit::setCallback(
27. 'ezcUrlConfiguration',
28. 'customLazyUrlConfiguration'
29. );
30.
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.
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';
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. // 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"
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';
3.
4. // create an ezcUrlConfiguration object
5. $urlCfg = new ezcUrlConfiguration();
6.
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"
11.
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" )
16.
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" ) )
21.
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"
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';
3.
4. // create an ezcUrlConfiguration object
5. $urlCfg = new ezcUrlConfiguration();
6.
7. $urlCfg->basedir = '/mydir/shop';
8. $urlCfg->script = 'index.php';
9. $urlCfg->addOrderedParameter( 'module' );
10.
11. $url = new ezcUrl( 'http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl', $urlCfg );
12.
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" )
);
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';
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. $urlCfg->addUnorderedParameter( 'patches', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
23.
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() );
27.
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() );
32.
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"
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';
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 would be:
string(7) "Beatles"
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';
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 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"
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';
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 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"
In the class ezcUrlTools there are some useful functions for handling urls.
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:
$_SERVER = array(
'HTTPS' => '1',
'HTTP_HOST' => 'www.example.com',
'SERVER_PORT' => 80,
'REQUEST_URI' => '/index.php'
);
$url = ezcUrlTools::getCurrentUrl();
Then $url will be:
http://www.example.com/index.php
This function has the same functionality as the PHP function parse_str(), but
without converting the dots to underscores in query parameter names.
Example:
$params = ezcUrlTools::parseQueryString(
'openid.nonce=123456&foo[]=bar&foo[]=baz' );
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'.
