php-altorouter/usage/mapping-routes.html

---
title: "Mapping routes using AltoRouter"
layout: default
---
<h1>
    <small>Using AltoRouter</small>
    Mapping Routes
</h1>

<p>By now, you should have <a href="{{ '/usage/rewrite-requests.html' | relative_url }}">rewritten al requests to be handled by a single file in which you created an AltoRouter instance.</a></p>
<p>To map your routes, use the <code>map()</code> method. The following example maps all <code>GET /</code> requests.</p>

{% highlight php startinline %}
    $router->map( 'GET', '/', 'render_home', 'home' );
{% endhighlight %}

<p>The <code>map()</code> method accepts the following parameters.</p>

<p>
    <code>$method</code> (string)<br />
    This is a pipe-delimited string of the accepted HTTP requests methods.<br /><br />
    <em>Example: </em><code>GET|POST|PATCH|PUT|DELETE</code>
</p>

<p>
    <code>$route</code> (string)<br />
    This is the route pattern to match against. This can be a plain string, one of the predefined regex filters or a custom regex. Custom regexes must start with <code>@</code>.
    <br /><br />
    <em>Examples: </em>
</p>

<table>
    <tr>
        <th>Route</th>
        <th>Example Match</th>
        <th>Variables</th>
    </tr>
    <tr>
        <td><code>/contact/</code></td>
        <td><code>/contact/</code></td>
        <td></td>
    </tr>
    <tr>
        <td><code>/users/[i:id]/</code></td>
        <td><code>/users/12/</code></td>
        <td><code>$id: 12</code></td>
    </tr>
    <tr>
        <td><code>/[a:c]/[a:a]?/[i:id]?</code></td>
        <td><code>/controller/action/21</code></td>
        <td><code>$c: "controller", $a: "action", $id: 21</code></td>
    </tr>
</table>

<p>
    <code>$target</code> (mixed)<br />
    As AltoRouter leaves handling routes up to you, this can be anything.<br /><br />
    <em>Example using a function callback:</em> <br />
    <code>function() { ... }</code>
    <br /><br />
    <em>Example using a controller#action string:</em> <br />
    <code>UserController#showDetails</code>
</p>


<p>
    <code>$name</code> (string, optional)<br />
    If you want to use reversed routing, specify a name parameter so you can later generate URL's using this route.<br /><br />
    <em>Example:</em><br />
    <code>user_details</code>
 </p>

<h3>Example Mapping</h3>
{% highlight php startinline%}
// map homepage using callable
$router->map( 'GET', '/', function() {
    require __DIR__ . '/views/home.php';
});

// map users details page using controller#action string
$router->map( 'GET', '/users/[i:id]/', 'UserController#showDetails' );

// map contact form handler using function name string
$router->map( 'POST', '/contact/', 'handleContactForm' );
{% endhighlight %}

<p>For quickly adding multiple routes, you can use the <code>addRoutes</code> method. This method accepts an array or any kind of traversable.</p>

<div class="highlight highlight-php"><pre><span class="nv">$router</span><span class="o">-&gt;</span><span class="na">addRoutes</span><span class="p">(</span><span class="k">array</span><span class="p">(</span>
  <span class="k">array</span><span class="p">(</span><span class="s1">'PATCH'</span><span class="p">,</span><span class="s1">'/users/[i:id]'</span><span class="p">,</span> <span class="s1">'users#update'</span><span class="p">,</span> <span class="s1">'update_user'</span><span class="p">),</span>
  <span class="k">array</span><span class="p">(</span><span class="s1">'DELETE'</span><span class="p">,</span><span class="s1">'/users/[i:id]'</span><span class="p">,</span> <span class="s1">'users#delete'</span><span class="p">,</span> <span class="s1">'delete_user'</span><span class="p">)</span>
<span class="p">));</span>
</pre></div>

<h2>Match Types</h2>
<p>You can use the following limits on your named parameters. AltoRouter will create the correct regexes for you.</p>

{% highlight php startinline %}
*                    // Match all request URIs
[i]                  // Match an integer
[i:id]               // Match an integer as 'id'
[a:action]           // Match alphanumeric characters as 'action'
[h:key]              // Match hexadecimal characters as 'key'
[:action]            // Match anything up to the next / or end of the URI as 'action'
[create|edit:action] // Match either 'create' or 'edit' as 'action'
[*]                  // Catch all (lazy, stops at the next trailing slash)
[*:trailing]         // Catch all as 'trailing' (lazy)
[**:trailing]        // Catch all (possessive - will match the rest of the URI)
.[:format]?          // Match an optional parameter 'format' - a / or . before the block is also optional
{% endhighlight %}

<p>The character before the colon (the 'match type') is a shortcut for one of the following regular expressions</p>

{% highlight php startinline %}
'i'  => '[0-9]++'
'a'  => '[0-9A-Za-z]++'
'h'  => '[0-9A-Fa-f]++'
'*'  => '.+?'
'**' => '.++'
''   => '[^/\.]++'
{% endhighlight %}

<p>You can register your own match types using the <code>addMatchTypes()</code> method.</p>

{% highlight php startinline %}
$router->addMatchTypes(array('cId' => '[a-zA-Z]{2}[0-9](?:_[0-9]++)?'));
{% endhighlight %}

<p>Once your routes are all mapped you can start matching requests and continue processing the request.</p>

<p>
    <a style="float:left;" href="{{ '/usage/rewrite-requests.html' | relative_url }}">&laquo; Rewriting requests</a>
    <a style="float:right;" href="{{ '/usage/matching-requests.html' | relative_url }}">Matching requests &raquo;</a>
    <br style="clear:both;">
</p>