mirror of
https://github.com/dannyvankooten/AltoRouter.git
synced 2025-08-06 00:17:29 +02:00
Add usage pages.
This commit is contained in:
Danny van Kooten
52
usage/install.html
Normal file
52
usage/install.html
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Installing AltoRouter
|
||||
layout: default
|
||||
---
|
||||
|
||||
<h1>
|
||||
<small>Using AltoRouter</small>
|
||||
Installation
|
||||
</h1>
|
||||
|
||||
<h2>Install AltoRouter using Composer</h2>
|
||||
<p>To install using Composer, you will have to install Composer first.</p>
|
||||
|
||||
{% highlight bash %}
|
||||
curl -s https://getcomposer.org/installer | php
|
||||
{% endhighlight %}
|
||||
|
||||
<p>Create a <strong>composer.json</strong> file in your project root.</p>
|
||||
|
||||
{% highlight json %}
|
||||
{
|
||||
"require": {
|
||||
"altorouter/altorouter": "1.1.0"
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
<p>Tell Composer to install the required dependencies.</p>
|
||||
|
||||
{% highlight bash %}
|
||||
php composer.phar install
|
||||
{% endhighlight %}
|
||||
|
||||
<p>If you want to use the autoloading provided by Composer, add the following line to your application file.</p>
|
||||
|
||||
{% highlight php startinline %}
|
||||
require 'vendor/autoload.php';
|
||||
{% endhighlight %}
|
||||
|
||||
<p>You are now ready to use the <code>AltoRouter</code> class. <a href="/usage/rewrite-requests.html">Rewrite all requests to your application file</a> and start <a href="/usage/mapping-routes.html">mapping your routes</a>. </p>
|
||||
|
||||
<h2 class="subtitle">Install AltoRouter manually</h2>
|
||||
<p>Just <a href="https://github.com/dannyvankooten/AltoRouter/zipball/master">download the AltoRouter class</a> and require it in your application file.</p>
|
||||
|
||||
{% highlight php startinline %}
|
||||
require 'AltoRouter.php';
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
<a style="float:right;" href="/usage/rewrite-requests.html">Rewrite requests »</a>
|
||||
<br style="clear:both;">
|
||||
</p>
|
||||
131
usage/mapping-routes.html
Normal file
131
usage/mapping-routes.html
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
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">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>
|
||||
|
||||
<h3><code>$method</code> (string)</h3>
|
||||
<p>
|
||||
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>
|
||||
|
||||
<h3><code>$route</code> (string)</h3>
|
||||
<p>
|
||||
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>
|
||||
|
||||
<h3><code>$target</code> (mixed) </h3>
|
||||
<p>As AltoRouter leaves handling routes up to you, this can be anything.</p>
|
||||
<p>
|
||||
<em>Example using a function callback:</em> <br />
|
||||
<code>function() { ... }</code>
|
||||
</p>
|
||||
<p>
|
||||
<em>Example using a controller#action string:</em> <br />
|
||||
<code>UserController#showDetails</code>
|
||||
</p>
|
||||
|
||||
<h3><code>$name</code> (string, optional)</h3>
|
||||
<p>If you want to use reversed routing, specify a name parameter so you can later generate URL's using this route.</p>
|
||||
<p>
|
||||
<em>Example:</em><br />
|
||||
<code>user_details</code></coe>
|
||||
</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">-></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>
|
||||
|
||||
<div class="highlight highlight-php"><pre><span class="o">*</span> <span class="c1">// Match all request URIs</span>
|
||||
<span class="p">[</span><span class="nx">i</span><span class="p">]</span> <span class="c1">// Match an integer</span>
|
||||
<span class="p">[</span><span class="nx">i</span><span class="o">:</span><span class="nx">id</span><span class="p">]</span> <span class="c1">// Match an integer as 'id'</span>
|
||||
<span class="p">[</span><span class="nx">a</span><span class="o">:</span><span class="nx">action</span><span class="p">]</span> <span class="c1">// Match alphanumeric characters as 'action'</span>
|
||||
<span class="p">[</span><span class="nx">h</span><span class="o">:</span><span class="nb">key</span><span class="p">]</span> <span class="c1">// Match hexadecimal characters as 'key'</span>
|
||||
<span class="p">[</span><span class="o">:</span><span class="nx">action</span><span class="p">]</span> <span class="c1">// Match anything up to the next / or end of the URI as 'action'</span>
|
||||
<span class="p">[</span><span class="nx">create</span><span class="o">|</span><span class="nx">edit</span><span class="o">:</span><span class="nx">action</span><span class="p">]</span> <span class="c1">// Match either 'create' or 'edit' as 'action'</span>
|
||||
<span class="p">[</span><span class="o">*</span><span class="p">]</span> <span class="c1">// Catch all (lazy, stops at the next trailing slash)</span>
|
||||
<span class="p">[</span><span class="o">*:</span><span class="nx">trailing</span><span class="p">]</span> <span class="c1">// Catch all as 'trailing' (lazy)</span>
|
||||
<span class="p">[</span><span class="o">**:</span><span class="nx">trailing</span><span class="p">]</span> <span class="c1">// Catch all (possessive - will match the rest of the URI)</span>
|
||||
<span class="o">.</span><span class="p">[</span><span class="o">:</span><span class="nx">format</span><span class="p">]</span><span class="o">?</span> <span class="c1">// Match an optional parameter 'format' - a / or . before the block is also optional</span>
|
||||
</pre></div>
|
||||
|
||||
<p>The character before the colon (the 'match type') is a shortcut for one of the following regular expressions</p>
|
||||
|
||||
<div class="highlight highlight-php"><pre><span class="s1">'i'</span> <span class="o">=></span> <span class="s1">'[0-9]++'</span>
|
||||
<span class="s1">'a'</span> <span class="o">=></span> <span class="s1">'[0-9A-Za-z]++'</span>
|
||||
<span class="s1">'h'</span> <span class="o">=></span> <span class="s1">'[0-9A-Fa-f]++'</span>
|
||||
<span class="s1">'*'</span> <span class="o">=></span> <span class="s1">'.+?'</span>
|
||||
<span class="s1">'**'</span> <span class="o">=></span> <span class="s1">'.++'</span>
|
||||
<span class="s1">''</span> <span class="o">=></span> <span class="s1">'[^/\.]++'</span>
|
||||
</pre></div>
|
||||
|
||||
<p>You can register your own match types using the <code>addMatchTypes()</code> method.</p>
|
||||
|
||||
<div class="highlight highlight-php"><pre><span class="nv">$router</span><span class="o">-></span><span class="na">addMatchTypes</span><span class="p">(</span><span class="k">array</span><span class="p">(</span><span class="s1">'cId'</span> <span class="o">=></span> <span class="s1">'[a-zA-Z]{2}[0-9](?:_[0-9]++)?'</span><span class="p">));</span>
|
||||
</pre></div>
|
||||
|
||||
<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">« Rewriting requests</a>
|
||||
<a style="float:right;" href="/usage/matching-requests.html">Matching requests »</a>
|
||||
<br style="clear:both;">
|
||||
</p>
|
||||
57
usage/matching-requests.html
Normal file
57
usage/matching-requests.html
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Matching requests using AltoRouter
|
||||
layout: default
|
||||
---
|
||||
<h1>
|
||||
<small>Using AltoRouter</small>
|
||||
Matching Requests
|
||||
</h1>
|
||||
|
||||
<p>To match the current request, just call the `match()` method without any parameters.</p>
|
||||
|
||||
{% highlight php startinline %}
|
||||
$match = $router->match();
|
||||
{% endhighlight %}
|
||||
|
||||
<p>If a match was found, the <code>match()</code> method will return an associative array with the following 3 keys.</p>
|
||||
|
||||
<p>
|
||||
<code>target</code> (mixed)<br />
|
||||
The target of the route, given during mapping the route.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<code>params</code> (array)<br />
|
||||
Named parameters found in the request url.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<code>name</code> (string)<br />
|
||||
The name of the route.
|
||||
</p>
|
||||
|
||||
<p><em>Example</em></p>
|
||||
|
||||
{% highlight php startinline %}
|
||||
$router = new AltoRouter();
|
||||
$router->map( 'GET', '/', function() { .. }, 'home' );
|
||||
|
||||
// assuming current request url = '/'
|
||||
$match = $router->match();
|
||||
|
||||
/*
|
||||
array(3) {
|
||||
["target"] => object(Closure)#2 (0) { }
|
||||
["params"] => array(0) { }
|
||||
["name"] => 'home'
|
||||
}
|
||||
*/
|
||||
{% endhighlight %}
|
||||
|
||||
<p>AltoRouter does not process the request for you, you are free to use the method you prefer. Here is a simplified example <a href="/usage/processing-requests.html">how to process requests using closures</a> though.</p>
|
||||
|
||||
<p>
|
||||
<a style="float:left;" href="/usage/mapping-routes.html">« Mapping routes</a>
|
||||
<a style="float:right;" href="/usage/processing-requests.html">Processing requests »</a>
|
||||
<br style="clear:both;">
|
||||
</p>
|
||||
40
usage/processing-requests.html
Normal file
40
usage/processing-requests.html
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Processing requests using AltoRouter
|
||||
layout: default
|
||||
---
|
||||
<h1>
|
||||
<small>Using AltoRouter</small>
|
||||
Processing Requests
|
||||
</h1>
|
||||
|
||||
<p>AltoRouter does not process requests for you so you are free to use the method you prefer. To help you get started, here's a simplified example using closures.</p>
|
||||
|
||||
{% highlight php startinline %}
|
||||
$router = new AltoRouter();
|
||||
|
||||
// map homepage
|
||||
$router->map( 'GET', '/', function() {
|
||||
require __DIR__ . '/views/home.php';
|
||||
});
|
||||
|
||||
// map user details page
|
||||
$router->map( 'GET', '/user/[i:id]/', function( $id ) {
|
||||
require __DIR__ . '/views/user-details.php';
|
||||
});
|
||||
|
||||
// match current request url
|
||||
$match = $router->match();
|
||||
|
||||
// call closure or throw 404 status
|
||||
if( $match && is_callable( $match['target'] ) ) {
|
||||
call_user_func_array( $match['target'], $match['params'] );
|
||||
} else {
|
||||
// no route was matched
|
||||
header( $_SERVER["SERVER_PROTOCOL"] . ' 404 Not Found');
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
<a style="float:left;" href="/usage/matching-requests.html">« Matching requests</a>
|
||||
<br style="clear:both;">
|
||||
</p>
|
||||
43
usage/rewrite-requests.html
Normal file
43
usage/rewrite-requests.html
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: "Rewrite all requests to AltoRouter"
|
||||
layout: default
|
||||
---
|
||||
<h1>
|
||||
<small>Using AltoRouter</small>
|
||||
Rewrite all requests to AltoRouter
|
||||
</h1>
|
||||
|
||||
<p>To use AltoRouter, you will need to rewrite all requests to a single file in which you create an instance of the AltoRouter class.</p>
|
||||
<p>There are various ways to go about this, but here are examples for Apache and Nginx.</p>
|
||||
|
||||
<h4>Apache <code>.htaccess</code></h4>
|
||||
{% highlight apache %}
|
||||
RewriteEngine on
|
||||
RewriteCond %{REQUEST_FILENAME} !-f
|
||||
RewriteRule . index.php [L]
|
||||
{% endhighlight %}
|
||||
|
||||
<h4>Nginx <code>nginx.conf</code></h4>
|
||||
{% highlight nginx %}
|
||||
try_files $uri /index.php;
|
||||
{% endhighlight %}
|
||||
|
||||
<p>All requests are now handled by the same file. In that file, you create an <code>AltoRouter</code> instance.</p>
|
||||
|
||||
{% highlight php startinline %}
|
||||
$router = new AltoRouter();
|
||||
{% endhighlight %}
|
||||
|
||||
<p>Optionally, if your project lives in a sub-folder of your web root you use the <code>setBasePath()</code> method to set a base path.</p>
|
||||
|
||||
{% highlight php startinline %}
|
||||
$router->setBasePath('/alto-app/');
|
||||
{% endhighlight %}
|
||||
|
||||
<p>You are now ready to start <a href="/usage/mapping-routes.html">mapping your routes</a>.</p>
|
||||
|
||||
<p>
|
||||
<a style="float:left;" href="/usage/install.html">« Installing AltoRouter</a>
|
||||
<a style="float:right;" href="/usage/mapping-routes.html">Mapping routes »</a>
|
||||
<br style="clear:both;">
|
||||
</p>
|
||||
Reference in New Issue
Block a user