Url/docs/tutorial.txt

eZ Components - Url
~~~~~~~~~~~~~~~~~~~

.. contents:: Table of Contents

Introduction
============

The Url component provides basic operations to handle urls (including parse,
build, get/set path parameters, get/set query and create formatted urls).

Class overview
==============

ezcUrl
  This is the main class of this component. It contains methods for url
  parsing, url building, get/set parameters and get/set query.

ezcUrlConfiguration
  This class allows the definition of url configurations (including basedir,
  script, ordered parameters, unordered parameters and delimiters for unordered
  parameter names).

ezcUrlCreator
  This class allows you to register a url under an alias. You can then use that
  alias to generate another url suffixed with a value, or to create urls
  formatted using the syntax of the PHP function sprintf().

ezcUrlTools
  This utility class contains useful functions for handling urls, like
  getCurrentUrl() which builds the current url from the $_SERVER array or
  another array source, and parseQueryString() which has the same functionality
  as the PHP function parse_str(), but without converting the dots to
  underscores in query parameter names.

Notes
=====

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.

Working with the query part
===========================

Getting the query part
----------------------

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

.. include:: tutorial/tutorial_get_query.php
    :literal:

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:

.. include:: tutorial/tutorial_set_query.php
    :literal:

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"

Working with url configurations
===============================

Creating and using a custom url configuration
---------------------------------------------

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

.. include:: tutorial/tutorial_cfg_create.php
    :literal:

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

__ introduction_Base.html#lazy-initialization

.. include:: tutorial/tutorial_lazy_initialization.php
	:literal:

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.

Working with parameters
=======================

Getting parameters using a url configuration
--------------------------------------------

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

.. include:: tutorial/tutorial_get_params.php
    :literal:

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:

.. include:: tutorial/tutorial_get_params_aggregate.php
    :literal:

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:

.. include:: tutorial/tutorial_get_params_no_delimiters.php
    :literal:

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:

.. include:: tutorial/tutorial_set_params.php
    :literal:

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:

.. include:: tutorial/tutorial_cfg_change.php
    :literal:

The output would be::

    string(7) "Beatles"

Using the url creator
=====================

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.

.. include:: tutorial/tutorial_url_creator.php
    :literal:

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.

.. include:: tutorial/tutorial_url_creator_params.php
    :literal:

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"

Other url functions
===================

In the class ezcUrlTools there are some useful functions for handling urls.

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::

    <?php
    $_SERVER = array(
        'HTTPS' => '1',
        'SERVER_NAME' => 'www.example.com',
        'SERVER_PORT' => 80,
        'REQUEST_URI' => '/index.php'
        );

    $url = ezcUrlTools::getCurrentUrl();
    ?>

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::

    <?php
    $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'.


..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79