^Status|Draft|
^Todo|Proof read|

====== URL Helper ======

Provides methods for working with URL(s).

===== Methods =====

==== current() ====

''url::current()'' returns the current URI string. This method accepts one optional parameter. If you set it to TRUE the query string will be included in the return value.

<code php>
// site_domain = 'localhost/kohana/'
// site_protocol = 'http'
// index_page = 'index.php'
// url_suffix = '.html'

// Current URL: http://localhost/kohana/index.php/welcome/home.html?query=string

echo url::current();
</code>

Returns

  welcome/home

While

<code php>
echo url::current(TRUE);
</code>

Returns

  welcome/home?query=string

==== base() ====
''url::base()'' returns the base URL defined by the ''site_protocol'' and ''site_domain'' in ''config.php''. If your site_domain doesn't have a hostname in it, you will get a relative URL.

<code php>
// site_domain = 'localhost/kohana/'
// site_protocol = 'http'

echo url::base();
</code>

Generates 

  http://localhost/kohana/

''url::base()'' accepts two **optional** parameters. Set the first parameter to ''TRUE'' if you want to append the ''index_page'' defined in ''config.php'' to the base URL. Via the second parameter you can overwrite the default ''site_protocol'' from ''config.php''.

<code php>
// site_domain = 'localhost/kohana/'
// site_protocol = 'http'
// index_page = 'index.php'

echo url::base(TRUE, 'https');
</code>

Generates 

  https://localhost/kohana/index.php

==== site() ====

''url::site()'' returns a URL based on the ''site_protocol'', ''site_domain'', ''index_page'', ''url_suffix'' defined in ''config.php''. If your site_domain doesn't have a hostname in it, you will get a relative URL.

<code php>
// site_domain = 'localhost/kohana/'
// site_protocol = 'http'
// index_page = 'index.php'
// url_suffix = '.html'

echo url::site();
</code>

Generates

  http://localhost/kohana/index.php/.html

''url::site()'' accepts two **optional** parameters. You can pass URL segments via the first one. The second one allows you to overwrite the default ''site_protocol'' from ''config.php''.

<code php>
// site_domain = 'localhost/kohana/'
// site_protocol = 'http'
// index_page = ''
// url_suffix = '.html'

echo url::site('admin/login', 'https');
</code>

Generates

  https://localhost/kohana/admin/login.html

==== file() ====

''url::file()'' returns the URL to a file. Absolute filenames and relative filenames are allowed.

  * [string] filename
  * [bool] include the index.php

<code php>
echo url::file('download.zip');
</code>

Produces
<code>
http://domain.tld/download.zip 
</code>

==== title() ====

''url::title()'' returns a properly formatted title, for use in a URI. The first parameter, the input title string, is **mandatory**. The optional second parameter is used to set the separator character. By default this is a dash. You can only change this to an underscore.

<code php>
$input_title = ' __Ecléçtic__ title\'s  entered by cràzed users- ?>  ';

echo url::title($input_title, '_');
</code>

Generates: 
	
  eclectic_titles_entered_by_crazed_users

What happens to the input title? All non-alphanumeric characters, except for dashes or underscores (depending on the second parameter), will be deleted. However, non-ascii characters will first be [[core:utf8#transliterate_to_ascii|transliterated]] (for example: ''à'' becomes ''a'') in order to keep the URL title as readable as possible. Finally, the URL title is converted to lowercase.

==== redirect() ====

''url::redirect()'' generates an HTTP Server Header (302) and runs the **system.redirect** event, which will redirect the browser to a specified URL, by default ''site_domain'' defined in ''config.php''. 

''url::redirect()'' will always call the php ''exit'' function to prevent further script execution.

<code php>
url::redirect('http://www.whitehouse.gov');
</code>

Will redirect the browser to the White House website.

The optional second parameter can be used to set the redirect method. The default is 302.

<code php>
// site_domain = 'localhost/kohana/'
// site_protocol = 'http'

url::redirect('aboutus', 301);
</code>

Will redirect with a 301 header to ''http://localhost/kohana/aboutus''.

If you wish to send a Multiple Choice (300) redirect, provide an array of URIs to the redirect method:
<code php>
url::redirect(array('aboutus','http://www.kohana.php/'), 300);
</code>
The first URI in the array is considered the preferred URI and will be placed in the Location header.  All of the URIs will then be output in a HTML unordered list.  Generally the browser will follow the location header and this list will never be seen.  However, there is no standard defined behavior for what a user agent should do upon receiving a 300 and the list could be used to present the user with the choices you have given.