<commit_before><?php
/* @var $this \Phavour\Runnable\View */
?>
<div class="container" id="top">
    <div class="page-header">
        <h1>
            <small><a href="/docs">Docs</a> &raquo; </small>Routes
        </h1>
    </div>

    <p class="lead">
        The routes file controls where requests should be sent.
    </p>

    <p>
        As covered in the <a href="<?php echo $this->urlFor('docs.quickStart'); ?>#application-routes">Quick Start</a>, there are two main ways to write routes, both of which utilise a <code>routes.php</code> file.
    </p>

    <hr>
    <h2 id="routes-php-file">Introduction to the <code>routes.php</code> File</h2>

    <p>
        The concept behind the <code>routes.php</code> file is that it should return an array upon an include.<br />
        For instance, take this following basic example of a route. For this example we'll use the routes.php file located inside the <code>/src/DefaultPackage/res</code> folder.
    </p>

    <pre>// File: /src/DefaultPackage/res/routes.php
&lt;?php
return array(
    'Default.index.index' =&gt; array(
        'method' =&gt; 'GET|POST|PUT|DELETE',
        'path' =&gt; '/',
        'runnable' =&gt; 'Index::index',
    )
);</pre>

    <h3>Naming the route</h3>

    <p>
        The route file above only contains one route. The name of which is the array key (in this case "Default.index.index"). Naming the routes inside packages should always begin with the package name (without the word "Package"). For example:<br />
        <code>My.foo</code> should relate to a route in the 'MyPackage' package.<br />
        <code>Test.foo.bar</code> should relate to a route in the 'TestPackage' package.
    </p>

    <h3>Required keys for a route</h3>

    <p>
        In actual fact, there isn't that much information required for a route. The only thing the application REALLY needs to know is:
    </p>

    <ul>
        <li>Request path - array key of 'path'</li>
        <li>Runnable and method - array key of 'runnable'</li>
    </ul>

    <p>
        We'll cover the 'path' key <a href="#path-and-params">later in this page</a>
    </p>

    <p>
        The structure of the 'runnable' key inside a <strong>package specific route.php</strong> file should be:<br />
    </p>
    <pre>ClassName::methodName</pre>

    <div class="alert alert-info">
        There are some optional keys, which we'll cover in the next section.
    </div>

    <h3>Optional keys for a route</h3>

    <p>
        Routes are flexible, and adapt to your application needs. There are a few optional keys that you can give to your routes to make them a bit more specific.
    </p>

    <ul>
        <li>'method' - a string of HTTP request methods to use for this route, (ex: "GET" or "GET|POST|PUT")</li>
        <li>'params' - an array of static parameters to use for the route. These will be injected into your runnable method.</li>
        <li>'package' - a string of the package name to utilise for this route (full name, so 'MyPackage' or 'DefaultPackage'</li>
        <li>'allow' - an array, containing a key of 'from' with a value of IP addresses seperated by a pipe |, and/or a key of 'roles' with a list of user roles to allow</li>
    </ul>

    <p>
        If not specified, the 'method' key will default back to only GET.
    </p>

    <hr>
    <h2 id="full-route-example">A full route example</h2>

    <pre>// EXAMPLE
&lt;?php
return array(
    'My.custom.route' =&gt; array(
        'method' =&gt; 'GET|POST|PUT|DELETE', // take requests for GET POST PUT and DELETE
        'path' =&gt; '/my/path', // requests for /my/path only.
        'package' =&gt; 'MyPackage', // assign this route to 'MyPackage'
        'runnable' =&gt; 'Foo::bar', // run the method called 'bar' in the class called 'Foo'
        'params' =&gt; array( // inject this array of parameters to the method
            'foo' =&gt; 'bar'
        ),
        'allow' =&gt; array(
            'from' =&gt; '127.0.0.1|8.8.8.8', // only allow access from 127.0.0.1 and 8.8.8.8
            'roles' =&gt; 'user|admin' // only allow access from user or admin roles
        )
    )
);</pre>

    <hr>
    <h2 id="path-and-params">Path and Parameters</h2>

    <p>
        Creating dynamic routes is quite easy. You can simply include <code>{myParamName}</code> in the 'path'<br />
        Take this for example:
    </p>

    <pre>'path' =&gt; '/view/{user}</pre>

    <p>
        That path above would route all requests matching '/view/xxxxx' to this specific route, and provide a parameter called 'user' that you can call upon to retrieve the parameter value.
    </p>

    <hr>
    <h2 id="overriding-routes">Overriding a Route</h2>

    <p>
        Not all packages fit your needs. Thankfully, we've built in the ability to override routes to suit your needs.<br />
        At the top level, an application can also have a <code>routes.php</code> file. This file needs to be located in: <code>/res/routes.php</code>
    </p>

    <p>
        To override a route, you need simply to have a route in your <code>/res/routes.php</code> file which has the same name as the package specific route.<br />
        Utilising the example at the top of this page, we've overriden this by providing a new package, class, method combination
    </p>

    <pre>// File: /res/routes.php
&lt;?php
return array(
    'Default.index.index' =&gt; array(
        'method' =&gt; 'GET|POST|PUT|DELETE',
        'path' =&gt; '/',
        'package' =&gt; 'MyPackage',
        'runnable' =&gt; 'Foo::bar',
    )
);</pre>

    <p>
        Now that we've overriden the route for 'Default.index.index', from now on, all requests that match this route will be directed to:<br />
    </p>

    <ul>
        <li>Package: <code>MyPackage</code></li>
        <li>Class: <code>Foo</code></li>
        <li>Method: <code>bar</code></li>
    </ul>

    <div class="alert alert-warning">
        <p>
            <strong>Gotcha!</strong><br />
            If you provide a cache to the application, you'll need to either flush or disable it to see your route.
        </p>
    </div>

    <h2 id="establishing-a-url">Generate a URL</h2>

    <p>
        Whether it's in your Runnable, or in a view, at some point you'll want to create a URL based on a route name.<br />
        To do this, you can call:
    </p>

    <pre>echo $this-&gt;urlFor(
    $routeName, // The name of the route (ex: 'Default.index.index')
    array $params // A key value array of parameters to give the route (to populate a URL perhaps).
);</pre>

    <p>
        This method <code>urlFor</code> is in the <code>\Phavour\Application</code> and <code>\Phavour\Runnable\View</code> classes, enabling you to use it anywhere you need to.
    </p>

</div><commit_msg>Left menu on routes page<commit_after><?php
/* @var $this \Phavour\Runnable\View */
?>
<div class="container" id="top">
    <div class="page-header">
        <h1>
            <small><a href="/docs">Docs</a> &raquo; </small>Routes
        </h1>
    </div>

    <p class="lead">
        The routes file controls where requests should be sent.
    </p>

    <div class="row">
        <div class="col-md-3">
            <div class="list-group">
                <a href="#routes-php-file" class="list-group-item">Introduction to routes.php</a>
                <a href="#naming-the-route" class="list-group-item">&nbsp;&nbsp;&nbsp;&nbsp;Naming the route</a>
                <a href="#required-keys" class="list-group-item">&nbsp;&nbsp;&nbsp;&nbsp;Required keys</a>
                <a href="#optional-keys" class="list-group-item">&nbsp;&nbsp;&nbsp;&nbsp;Optional keys</a>
                <a href="#full-route-example" class="list-group-item">Full route example</a>
                <a href="#path-and-params" class="list-group-item">Path &amp; parameters</a>
                <a href="#overriding-routes" class="list-group-item">Overriding routes</a>
                <a href="#establishing-a-url" class="list-group-item">Generating URLs</a>
            </div>
        </div>
        <div class="col-md-9">
            <p>
                As covered in the <a href="<?php echo $this->urlFor('docs.quickStart'); ?>#application-routes">Quick Start</a>, there are two main ways to write routes, both of which utilise a <code>routes.php</code> file.
            </p>

            <hr>
            <h2 id="routes-php-file">Introduction to the <code>routes.php</code> File</h2>

            <p>
                The concept behind the <code>routes.php</code> file is that it should return an array upon an include.<br />
                For instance, take this following basic example of a route. For this example we'll use the routes.php file located inside the <code>/src/DefaultPackage/res</code> folder.
            </p>

            <pre>// File: /src/DefaultPackage/res/routes.php
&lt;?php
return array(
    'Default.index.index' =&gt; array(
        'method' =&gt; 'GET|POST|PUT|DELETE',
        'path' =&gt; '/',
        'runnable' =&gt; 'Index::index',
    )
);</pre>

            <h3 id="naming-the-route">Naming the route</h3>

            <p>
                The route file above only contains one route. The name of which is the array key (in this case "Default.index.index"). Naming the routes inside packages should always begin with the package name (without the word "Package"). For example:<br />
                <code>My.foo</code> should relate to a route in the 'MyPackage' package.<br />
                <code>Test.foo.bar</code> should relate to a route in the 'TestPackage' package.
            </p>

            <h3 id="required-keys">Required keys for a route</h3>

            <p>
                In actual fact, there isn't that much information required for a route. The only thing the application REALLY needs to know is:
            </p>

            <ul>
                <li>Request path - array key of 'path'</li>
                <li>Runnable and method - array key of 'runnable'</li>
            </ul>

            <p>
                We'll cover the 'path' key <a href="#path-and-params">later in this page</a>
            </p>

            <p>
                The structure of the 'runnable' key inside a <strong>package specific route.php</strong> file should be:<br />
            </p>
            <pre>ClassName::methodName</pre>

            <div class="alert alert-info">
                There are some optional keys, which we'll cover in the next section.
            </div>

            <h3 id="optional-keys">Optional keys for a route</h3>

            <p>
                Routes are flexible, and adapt to your application needs. There are a few optional keys that you can give to your routes to make them a bit more specific.
            </p>

            <ul>
                <li>'method' - a string of HTTP request methods to use for this route, (ex: "GET" or "GET|POST|PUT")</li>
                <li>'params' - an array of static parameters to use for the route. These will be injected into your runnable method.</li>
                <li>'package' - a string of the package name to utilise for this route (full name, so 'MyPackage' or 'DefaultPackage'</li>
                <li>'allow' - an array, containing a key of 'from' with a value of IP addresses seperated by a pipe |, and/or a key of 'roles' with a list of user roles to allow</li>
            </ul>

            <p>
                If not specified, the 'method' key will default back to only GET.
            </p>

            <hr>
            <h2 id="full-route-example">A full route example</h2>

            <pre>// EXAMPLE
&lt;?php
return array(
    'My.custom.route' =&gt; array(
        'method' =&gt; 'GET|POST|PUT|DELETE', // take requests for GET POST PUT and DELETE
        'path' =&gt; '/my/path', // requests for /my/path only.
        'package' =&gt; 'MyPackage', // assign this route to 'MyPackage'
        'runnable' =&gt; 'Foo::bar', // run the method called 'bar' in the class called 'Foo'
        'params' =&gt; array( // inject this array of parameters to the method
            'foo' =&gt; 'bar'
        ),
        'allow' =&gt; array(
            'from' =&gt; '127.0.0.1|8.8.8.8', // only allow access from 127.0.0.1 and 8.8.8.8
            'roles' =&gt; 'user|admin' // only allow access from user or admin roles
        )
    )
);</pre>

            <hr>
            <h2 id="path-and-params">Path and Parameters</h2>

            <p>
                Creating dynamic routes is quite easy. You can simply include <code>{myParamName}</code> in the 'path'<br />
                Take this for example:
            </p>

            <pre>'path' =&gt; '/view/{user}</pre>

            <p>
                That path above would route all requests matching '/view/xxxxx' to this specific route, and provide a parameter called 'user' that you can call upon to retrieve the parameter value.
            </p>

            <hr>
            <h2 id="overriding-routes">Overriding a Route</h2>

            <p>
                Not all packages fit your needs. Thankfully, we've built in the ability to override routes to suit your needs.<br />
                At the top level, an application can also have a <code>routes.php</code> file. This file needs to be located in: <code>/res/routes.php</code>
            </p>

            <p>
                To override a route, you need simply to have a route in your <code>/res/routes.php</code> file which has the same name as the package specific route.<br />
                Utilising the example at the top of this page, we've overriden this by providing a new package, class, method combination
            </p>

            <pre>// File: /res/routes.php
&lt;?php
return array(
    'Default.index.index' =&gt; array(
        'method' =&gt; 'GET|POST|PUT|DELETE',
        'path' =&gt; '/',
        'package' =&gt; 'MyPackage',
        'runnable' =&gt; 'Foo::bar',
    )
);</pre>

            <p>
                Now that we've overriden the route for 'Default.index.index', from now on, all requests that match this route will be directed to:<br />
            </p>

            <ul>
                <li>Package: <code>MyPackage</code></li>
                <li>Class: <code>Foo</code></li>
                <li>Method: <code>bar</code></li>
            </ul>

            <div class="alert alert-warning">
                <p>
                    <strong>Gotcha!</strong><br />
                    If you provide a cache to the application, you'll need to either flush or disable it to see your route.
                </p>
            </div>

            <h2 id="establishing-a-url">Generate a URL</h2>

            <p>
                Whether it's in your Runnable, or in a view, at some point you'll want to create a URL based on a route name.<br />
                To do this, you can call:
            </p>

            <pre>echo $this-&gt;urlFor(
    $routeName, // The name of the route (ex: 'Default.index.index')
    array $params // A key value array of parameters to give the route (to populate a URL perhaps).
);</pre>

            <p>
                This method <code>urlFor</code> is in the <code>\Phavour\Application</code> and <code>\Phavour\Runnable\View</code> classes, enabling you to use it anywhere you need to.
            </p>
        </div>
    </div>

</div>
{'fraction_non_alphanumeric': 0.13426774954152476, 'fraction_numerical': 0.005108724128897039, 'mean_word_length': 2.169815237699813, 'pattern_counts': {'":': 0, '<': 339, '<?xml version=': 0, '>': 341, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5406025', 'n_tokens_mistral': 4728, 'n_tokens_neox': 4513, 'n_words': 1688}