Documentation/libraries/uri.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 12px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin: 0 0 5px 0;
  24                 }
  25
  26                 h2 {
  27                         font-size: 13px;
  28                         font-weight: bold;
  29                         margin: 5px 0 5px 0;
  30                 }
  31
  32                 ol, ul {
  33                         margin: 10px 0 10px 0;
  34                         list-style-position: inside;
  35                 }
  36
  37                 p {
  38                         margin: 5px 0 5px 0;
  39                 }
  40
  41                 .content {
  42                         border: 1px dotted #444;
  43                         margin: 10px;
  44                         padding: 10px;
  45                         text-align: justify;
  46                         width: 700px;
  47                 }
  48
  49                 .example {
  50                         border: 1px solid #ccc;
  51                         background: #eee;
  52                         margin: 10px;
  53                         padding: 10px;
  54                 }
  55         </style>
  56 </head>
  57
  58 <body>
  59         <div class="content">
  60                 <h1>URI Library</h1>
  61
  62                 <p>The URI library provides an interface for retrieving information from URI strings.  If you use URI
  63                 routing you can also retrieve information about the rerouted segments.  <i>Note</i>: the config library is
  64                 automatically loaded by CarbonPHP so there is no need for you to load it.</p>
  65         </div>
  66
  67         <div class="content">
  68                 <h1>$this->uri->segment(index)</h1>
  69
  70                 <p>This allows you to retrieve a specific segment.  Where <b>index</b> is the segment number you wish to
  71                 retrieve.  Segments are numbered from left to right.</p>
  72
  73                 <div class="example">
  74                         www.your-domain.com/index.php/blog/archives/2007/09/
  75                 </div>
  76
  77                 <p>The segment numbers would be the following.</p>
  78
  79                 <ol>
  80                         <li>blog</li>
  81                         <li>archives</li>
  82                         <li>2007</li>
  83                         <li>09</li>
  84                 </ol>
  85
  86                 <p>By default the function will return <b>false</b> if a segment does not exist.  There is an optional second
  87                 parameter that allows you to set your own return value if a segment does not exist.</p>
  88
  89                 <div class="example">
  90                         $post_id = $this->uri->segment(3, 0);
  91                 </div>
  92         </div>
  93
  94         <div class="content">
  95                 <h1>$this->uri->rsegment(index)</h1>
  96
  97                 <p>This method is identical to the above one, except it retrieves the segment from your rerouted URI if you
  98                 are using CarbonPHP's URI routing feature.</p>
  99         </div>
 100
 101         <div class="content">
 102                 <h1>$this->uri->slash_segment(index)</h1>
 103
 104                 <p>This method is almost identical to <b>$this->uri->segment()</b>, except it adds a trailing slash and/or
 105                 leading slash based on the second parameter.</p>
 106
 107                 <div class="example">
 108                         $this->uri->slash_segment(<b>3</b>);<br />
 109                         $this->uri->slash_segment(<b>3</b>, 'leading');<br />
 110                         $this->uri->slash_segment(<b>3</b>, 'both');
 111                 </div>
 112
 113                 <p>The above example would return the following.</p>
 114
 115                 <ul>
 116                         <li>segment/</li>
 117                         <li>/segment</li>
 118                         <li>/segment/</li>
 119                 </ul>
 120         </div>
 121
 122         <div class="content">
 123                 <h1>$this->uri->slash_rsegment(index)</h1>
 124
 125                 <p>This method is identical to the above method except that it lets you add slashes to a segment from your
 126                 rerouted URI if you're using CarbonPHP's URI routing feature.</p>
 127         </div>
 128
 129         <div class="content">
 130                 <h1>$this->uri->get_uri_to_assoc(index)</h1>
 131
 132                 <p>This method lets you turn URI segments into an associative array of keys and values.</p>
 133
 134                 <div class="example">
 135                         index.php/user/search/name/john/country/england/gender/male
 136                 </div>
 137
 138                 <p>Using this method on this URL would turn it into the following array with the following prototype.</p>
 139
 140                 <div class="example">
 141                         [array]<br />
 142                         (<br />
 143                         &nbsp;&nbsp;&nbsp;&nbsp;'name' => 'john',<br />
 144                         &nbsp;&nbsp;&nbsp;&nbsp;'country' => 'england',<br />
 145                         &nbsp;&nbsp;&nbsp;&nbsp;'gender' => 'male'<br />
 146                         )
 147                 </div>
 148
 149                 <p>The first parameter of the method lets you set an offset.  By default the offset is set to 3 since your
 150                 URI will contain a controller and method name in the first and second segments.</p>
 151
 152                 <p>The second parameter lets you set default key names, so that the array returned by the method will always
 153                 contain expected indexes, even if they are missing from the URI.</p>
 154
 155                 <p>If the URI does not contain a value in your default an array index will be set to that name with a value of
 156                 <b>false</b>.  Also if a value is not found for a given array key the value will be set to <b>false</b>.</p>
 157         </div>
 158
 159         <div class="content">
 160                 <h1>$this->uri->get_ruri_to_assoc(index)</h1>
 161
 162                 <p>This method is identical to the above one except that it creates an associative array using the rerouted
 163                 URI if you're using the CarbonPHP URI routing feature.</p>
 164         </div>
 165
 166         <div class="content">
 167                 <h1>$this->uri->assoc_to_uri($array)</h1>
 168
 169                 <p>This method takes an associative array and generates a URI string from it.</p>
 170
 171                 <div class="example">
 172                         $array = array('product' => 'shirts', 'size' => 'medium', 'colour' => 'blue');<br />
 173                         <br />
 174                         $string = $this->uri->assoc_to_uri($array);<br />
 175                         <br />
 176                         // Will generate: product/shirts/size/medium/colour/blue
 177                 </div>
 178         </div>
 179
 180         <div class="content">
 181                 <h1>$this->uri->get_uri_string()</h1>
 182
 183                 <p>This method returns a string with the complete URI.</p>
 184
 185                 <div class="example">
 186                         www.your-domain.com/index.php/blog/post/4
 187                 </div>
 188
 189                 <p>This URI would return the following string.</p>
 190
 191                 <div class="example">
 192                         blog/post/4
 193                 </div>
 194         </div>
 195
 196         <div class="content">
 197                 <h1>$this->uri->get_ruri_string()</h1>
 198
 199                 <p>This method is identical to the above one except that it returns the rerouted URI if you're using the
 200                 URI rerouting feature of CarbonPHP.</p>
 201         </div>
 202
 203         <div class="content">
 204                 <h1>URI Class Methods</h1>
 205
 206                 <h2>public function __construct()</h2>
 207                 <p>This method initialises the class.</p>
 208
 209                 <h2>public function segment($index, $no_result = false)</h2>
 210                 <p>This method returns the value of a URI segment.</p>
 211
 212                 <h2>public function rsegment($index, $no_result = false)</h2>
 213                 <p>This method returns the value of a rerouted URI segment.</p>
 214
 215                 <h2>public function get_uri_to_assoc($index = 3, $default = array())</h2>
 216                 <p>This method creates an associative array from a URI.</p>
 217
 218                 <h2>public function get_ruri_to_assoc($index = 3, $default = array())</h2>
 219                 <p>This method creates an associative array from a rerouted URI.</p>
 220
 221                 <h2>private function c_uri_to_assoc($index = 3, $default, $which = 'segment')</h2>
 222                 <p>This method creates the associative arrays for the URI methods.</p>
 223
 224                 <h2>public function assoc_to_uri($array)</h2>
 225                 <p>This method creates a URI string from an associative array.</p>
 226
 227                 <h2>public function slash_segment($index, $where = 'trailing')</h2>
 228                 <p>This method returns a URI segment with a slash in the specified place.</p>
 229
 230                 <h2>public function slash_rsegment($index, $where = 'trailing')</h2>
 231                 <p>This method returns a rerouted URI segment with a slash in the specified place.</p>
 232
 233                 <h2>private function c_slash_segment($index, $where = 'trailing', $which = 'segment')</h2>
 234                 <p>This method gets the URI segment and slashes the value.</p>
 235
 236                 <h2>public function get_segment_array()</h2>
 237                 <p>This method returns an array of URI segments.</p>
 238
 239                 <h2>public function get_rsegment_array()</h2>
 240                 <p>This method returns an array of rerouted URI segments.</p>
 241
 242                 <h2>public function total_segments()</h2>
 243                 <p>This method returns the total number of URI segments.</p>
 244
 245                 <h2>public function total_rsegments()</h2>
 246                 <p>This method returns the total number of rerouted URI segments.</p>
 247
 248                 <h2>public function get_uri_string()</h2>
 249                 <p>This method returns the URI string.</p>
 250
 251                 <h2>public function get_ruri_string()</h2>
 252                 <p>This method returns the rerouted URI string.</p>
 253         </div>
 254 </body>
 255
 256 </html>