eZ components - Url
~~~~~~~~~~~~~~~~~~~

.. contents:: Table of Contents

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

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

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

ezcUrl
  The main class of this component. Contains methods for url parsing, url
  building, get/set parameters, get/set query.

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

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

Notes
=====

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.

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

Get the query part
------------------

Examples of getting the query part of urls:

.. include:: tutorial_get_query.php
    :literal:

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:

.. include:: tutorial_set_query.php
    :literal:

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"

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

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:

.. include:: tutorial_cfg_create.php
    :literal:

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

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

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:

.. include:: tutorial_get_params.php
    :literal:

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:

.. include:: tutorial_set_params.php
    :literal:

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:

.. include:: tutorial_cfg_change.php
    :literal:

The output will be: ::

    string(7) "Beatles"

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

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.

.. include:: tutorial_url_creator.php
    :literal:

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.

.. include:: tutorial_url_creator_params.php
    :literal:

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"

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