URL Helper
**********

The URL Helper file contains functions that assist in working with
URLs.

* Loading this Helper

* Available Functions


Loading this Helper
===================

This helper is loaded using the following code:

   $this->load->helper('url');


Available Functions
===================

The following functions are available:

site_url([$uri = ''[, $protocol = NULL]])

   Parameters:
      * **$uri** ("string") – URI string

      * **$protocol** ("string") – Protocol, e.g. ‘http’ or ‘https’

   Returns:
      Site URL

   Return type:
      "string"

   Returns your site URL, as specified in your config file. The
   index.php file (or whatever you have set as your site
   **index_page** in your config file) will be added to the URL, as
   will any URI segments you pass to the function, plus the
   **url_suffix** as set in your config file.

   You are encouraged to use this function any time you need to
   generate a local URL so that your pages become more portable in the
   event your URL changes.

   Segments can be optionally passed to the function as a string or an
   array. Here is a string example:

      echo site_url('news/local/123');

   The above example would return something like:
   *http://example.com/index.php/news/local/123*

   Here is an example of segments passed as an array:

      $segments = array('news', 'local', '123');
      echo site_url($segments);

   This function is an alias for "CI_Config::site_url()". For more
   info, please see the Config Library documentation.

base_url($uri = '', $protocol = NULL)

   Parameters:
      * **$uri** ("string") – URI string

      * **$protocol** ("string") – Protocol, e.g. ‘http’ or ‘https’

   Returns:
      Base URL

   Return type:
      "string"

   Returns your site base URL, as specified in your config file.
   Example:

      echo base_url();

   This function returns the same thing as "site_url()", without the
   *index_page* or *url_suffix* being appended.

   Also like "site_url()", you can supply segments as a string or an
   array. Here is a string example:

      echo base_url("blog/post/123");

   The above example would return something like:
   *http://example.com/blog/post/123*

   This is useful because unlike "site_url()", you can supply a string
   to a file, such as an image or stylesheet. For example:

      echo base_url("images/icons/edit.png");

   This would give you something like:
   *http://example.com/images/icons/edit.png*

   This function is an alias for "CI_Config::base_url()". For more
   info, please see the Config Library documentation.

current_url()

   Returns:
      The current URL

   Return type:
      "string"

   Returns the full URL (including segments) of the page being
   currently viewed.

   Note:

     Calling this function is the same as doing this: | |
     site_url(uri_string());

uri_string()

   Returns:
      An URI string

   Return type:
      "string"

   Returns the URI segments of any page that contains this function.
   For example, if your URL was this:

      http://some-site.com/blog/comments/123

   The function would return:

      blog/comments/123

   This function is an alias for "CI_Config::uri_string()". For more
   info, please see the Config Library documentation.

index_page()

   Returns:
      ‘index_page’ value

   Return type:
      "mixed"

   Returns your site **index_page**, as specified in your config file.
   Example:

      echo index_page();

anchor($uri = '', $title = '', $attributes = '')

   Parameters:
      * **$uri** ("string") – URI string

      * **$title** ("string") – Anchor title

      * **$attributes** ("mixed") – HTML attributes

   Returns:
      HTML hyperlink (anchor tag)

   Return type:
      "string"

   Creates a standard HTML anchor link based on your local site URL.

   The first parameter can contain any segments you wish appended to
   the URL. As with the "site_url()" function above, segments can be a
   string or an array.

   Note:

     If you are building links that are internal to your application
     do not include the base URL (http://…). This will be added
     automatically from the information specified in your config file.
     Include only the URI segments you wish appended to the URL.

   The second segment is the text you would like the link to say. If
   you leave it blank, the URL will be used.

   The third parameter can contain a list of attributes you would like
   added to the link. The attributes can be a simple string or an
   associative array.

   Here are some examples:

      echo anchor('news/local/123', 'My News', 'title="News title"');
      // Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a>

      echo anchor('news/local/123', 'My News', array('title' => 'The best news!'));
      // Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a>

      echo anchor('', 'Click here');
      // Prints: <a href="http://example.com">Click Here</a>

anchor_popup($uri = '', $title = '', $attributes = FALSE)

   Parameters:
      * **$uri** ("string") – URI string

      * **$title** ("string") – Anchor title

      * **$attributes** ("mixed") – HTML attributes

   Returns:
      Pop-up hyperlink

   Return type:
      "string"

   Nearly identical to the "anchor()" function except that it opens
   the URL in a new window. You can specify JavaScript window
   attributes in the third parameter to control how the window is
   opened. If the third parameter is not set it will simply open a new
   window with your own browser settings.

   Here is an example with attributes:

      $atts = array(
              'width'       => 800,
              'height'      => 600,
              'scrollbars'  => 'yes',
              'status'      => 'yes',
              'resizable'   => 'yes',
              'screenx'     => 0,
              'screeny'     => 0,
              'window_name' => '_blank'
      );

      echo anchor_popup('news/local/123', 'Click Me!', $atts);

   Note:

     The above attributes are the function defaults so you only need
     to set the ones that are different from what you need. If you
     want the function to use all of its defaults simply pass an empty
     array in the third parameter: | | echo
     anchor_popup(‘news/local/123’, ‘Click Me!’, array());

   Note:

     The **window_name** is not really an attribute, but an argument
     to the JavaScript *window.open()
     <http://www.w3schools.com/jsref/met_win_open.asp>* method, which
     accepts either a window name or a window target.

   Note:

     Any other attribute than the listed above will be parsed as an
     HTML attribute to the anchor tag.

mailto($email, $title = '', $attributes = '')

   Parameters:
      * **$email** ("string") – E-mail address

      * **$title** ("string") – Anchor title

      * **$attributes** ("mixed") – HTML attributes

   Returns:
      A “mail to” hyperlink

   Return type:
      "string"

   Creates a standard HTML e-mail link. Usage example:

      echo mailto('me@my-site.com', 'Click Here to Contact Me');

   As with the "anchor()" tab above, you can set attributes using the
   third parameter:

      $attributes = array('title' => 'Mail me');
      echo mailto('me@my-site.com', 'Contact Me', $attributes);

safe_mailto($email, $title = '', $attributes = '')

   Parameters:
      * **$email** ("string") – E-mail address

      * **$title** ("string") – Anchor title

      * **$attributes** ("mixed") – HTML attributes

   Returns:
      A spam-safe “mail to” hyperlink

   Return type:
      "string"

   Identical to the "mailto()" function except it writes an obfuscated
   version of the *mailto* tag using ordinal numbers written with
   JavaScript to help prevent the e-mail address from being harvested
   by spam bots.

auto_link($str, $type = 'both', $popup = FALSE)

   Parameters:
      * **$str** ("string") – Input string

      * **$type** ("string") – Link type (‘email’, ‘url’ or ‘both’)

      * **$popup** ("bool") – Whether to create popup links

   Returns:
      Linkified string

   Return type:
      "string"

   Automatically turns URLs and e-mail addresses contained in a string
   into links. Example:

      $string = auto_link($string);

   The second parameter determines whether URLs and e-mails are
   converted or just one or the other. Default behavior is both if the
   parameter is not specified. E-mail links are encoded as
   "safe_mailto()" as shown above.

   Converts only URLs:

      $string = auto_link($string, 'url');

   Converts only e-mail addresses:

      $string = auto_link($string, 'email');

   The third parameter determines whether links are shown in a new
   window. The value can be TRUE or FALSE (boolean):

      $string = auto_link($string, 'both', TRUE);

url_title($str, $separator = '-', $lowercase = FALSE)

   Parameters:
      * **$str** ("string") – Input string

      * **$separator** ("string") – Word separator

      * **$lowercase** ("bool") – Whether to transform the output
        string to lower-case

   Returns:
      URL-formatted string

   Return type:
      "string"

   Takes a string as input and creates a human-friendly URL string.
   This is useful if, for example, you have a blog in which you’d like
   to use the title of your entries in the URL. Example:

      $title = "What's wrong with CSS?";
      $url_title = url_title($title);
      // Produces: Whats-wrong-with-CSS

   The second parameter determines the word delimiter. By default
   dashes are used. Preferred options are: **-** (dash) or **_**
   (underscore)

   Example:

      $title = "What's wrong with CSS?";
      $url_title = url_title($title, 'underscore');
      // Produces: Whats_wrong_with_CSS

   Note:

     Old usage of ‘dash’ and ‘underscore’ as the second parameter is
     DEPRECATED.

   The third parameter determines whether or not lowercase characters
   are forced. By default they are not. Options are boolean
   TRUE/FALSE.

   Example:

      $title = "What's wrong with CSS?";
      $url_title = url_title($title, 'underscore', TRUE);
      // Produces: whats_wrong_with_css

prep_url($str = '')

   Parameters:
      * **$str** ("string") – URL string

   Returns:
      Protocol-prefixed URL string

   Return type:
      "string"

   This function will add http:// in the event that a protocol prefix
   is missing from a URL.

   Pass the URL string to the function like this:

      $url = prep_url('example.com');

redirect($uri = '', $method = 'auto', $code = NULL)

   Parameters:
      * **$uri** ("string") – URI string

      * **$method** ("string") – Redirect method (‘auto’, ‘location’
        or ‘refresh’)

      * **$code** ("string") – HTTP Response code (usually 302 or 303)

   Return type:
      "void"

   Does a “header redirect” to the URI specified. If you specify the
   full site URL that link will be built, but for local links simply
   providing the URI segments to the controller you want to direct to
   will create the link. The function will build the URL based on your
   config file values.

   The optional second parameter allows you to force a particular
   redirection method. The available methods are **auto**,
   **location** and **refresh**, with location being faster but less
   reliable on IIS servers. The default is **auto**, which will
   attempt to intelligently choose the method based on the server
   environment.

   The optional third parameter allows you to send a specific HTTP
   Response Code - this could be used for example to create 301
   redirects for search engine purposes. The default Response Code is
   302. The third parameter is *only* available with **location**
   redirects, and not *refresh*. Examples:

      if ($logged_in == FALSE)
      {
              redirect('/login/form/');
      }

      // with 301 redirect
      redirect('/article/13', 'location', 301);

   Note:

     In order for this function to work it must be used before
     anything is outputted to the browser since it utilizes server
     headers.

   Note:

     For very fine grained control over headers, you should use the
     Output Library "set_header()" method.

   Note:

     To IIS users: if you hide the *Server* HTTP header, the *auto*
     method won’t detect IIS, in that case it is advised you
     explicitly use the **refresh** method.

   Note:

     When the **location** method is used, an HTTP status code of 303
     will *automatically* be selected when the page is currently
     accessed via POST and HTTP/1.1 is used.

   Important:

     This function will terminate script execution.
