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>$this->uri->total_segments()</h1>
 205
 206                 <p>Returns the total number of URI segments.</p>
 207         </div>
 208
 209         <div class="content">
 210                 <h1>$this->uri->total_rsegments()</h1>
 211
 212                 <p>Returns the total number of URI segments in a re-routed URI.</p>
 213         </div>
 214
 215         <div class="content">
 216                 <h1>$this->uri->get_segment_array()</h1>
 217
 218                 <p>Returns an array of URI segments.</p>
 219         </div>
 220
 221                 <div class="content">
 222                 <h1>$this->uri->get_rsegment_array()</h1>
 223
 224                 <p>Returns an array of re-routed URI segments.</p>
 225         </div>
 226 </body>
 227
 228 </html>