FrostMVC PHP Framework

Documentation | Version 1.0.3

FrostMVC / app / routes.php

routes.php

The routes.php file contains the map of all controllers of your web application. It is where you indicate how the user will interact with your controllers.

How routing works?

The term routing refers to how the web application will select (or map) a certain URL based on its value (or path), and then execute its mapped controller for that URL. For example, you need to define which controller to be used as landing page (or homepage), or which controller will be used for /blog path.

In FrostMVC, routing works by registering your controller file to a function in routes.php file. The function name will serve as the path in the URL.

Basically, FrostMVC uses the following URL format:

 https://<domain.tld>/[routeFunc]/[controllerFunc]/[param-1]/[param-2]/.../[param-N]

Take note that in FrostMVC URL format:

The first value of the path (the value right after the domain) will always refer to a function name in routes.php file.
The second value of the path will always refer to a controller function
The third value (and onwards) will refer to the values that will be passed to the parameters of the controller function.

To learn more about how the URL paths will be routed to the controller, take a look at the next topics below.

Routing your Controller

Routing your controller is as simple as creating a function in app/routes.php file, and loading your controller using View::route() function. Take a look at the following example to see how FrostMVC process the URL to call a certain controller using a route function.

 https://www.mysite.com/blog

First, FrostMVC will look for a function in routes.php file with the same name as the path from the URL.
Once a match is found, FrostMVC will then load the file of the controller class routed to the function through the View::route() method.
Lastly, FrostMVC will execute the index() function of the said controller.

Note that index() function is a special function that will be executed by the controller if the URL only contains the route function name.

Routing your Controller's function

The second path from the URL determines what function in your controller will be executed. Take a look at the following example to see how the framework pick the controller's function based on the URL's path.

 https://www.mysite.com/blog/latest

First, the framework will look for a function in routes.php file with the same name as the first path from the URL.
Once a match is found, the framework will then load the file of the controller class routed to the function through the View::route() method.
Lastly, the framework will execute the function of the controller based on the second path of the URL (which is internally processed by the framework using the $pages parameter).

For this example, since the URL only provided the value for first path (route function blog) and second path (controller function latest), the framework will look for the function latest that has no parameter.

Routing your Controller's function with parameters

Invoking a function with parameter is not much different than invoking a function without parameter. The only difference is that the values of the parameters will be acquired respective with the URL's third path onwards.
Take a look at the following example:

 https://www.mysite.com/blog/view/1145/frostmvc-routing-tutorial

First, the framework will look for a function in routes.php file with the same name as the first path from the URL.
Once a match is found, the framework will then load the file of the controller class routed to the function through the View::route() method.
Then, the framework will pass the third and fourth path to the first and second parameters of the controller's function.
Lastly, the framework will execute the function of the controller based on the second path of the URL (which is internally processed by the framework using the $pages parameter).

For this example, the third path will become the value of the parameter $articleid (which is now holding the string value '1145' and the fourth path will become the value of the parameter $slug (which is now holding 'frostmvc-routing-tutorial' string value.

Routing your Controller's function with optional parameters

Generally in PHP, you can declare a default value for your parameter if you want it to be optional.

class BlogController extends Controller{
    public function index(){
        print '<h1>Hello World!</h1>';
    }

    public function latest(){
        print '<h1>Welcome to Latest Blogs!</h1>';
    }

    public function view($articleid, $slug = false){
        vardump([$articleid, $slug]);
    }
}

In the code above, the parameter $slug is optional. This will make the following URL valid for the function.

 https://www.mysite.com/blog/view/1145/frostmvc-routing-tutorial

 https://www.mysite.com/blog/view/1145

However the following URL is not valid

 https://www.mysite.com/blog/view

This is because the parameter $articleid is not an optional parameter.

Routing your Homepage

In order to specify which controller is the default controller for landing page (or homepage), there is a special function in routes.php file that can be used for it.
The index() function in routes.php file can be used to specify the controller for your homepage.

function index(){
    View::route('HomepageController');
}

Unlike other routing, the parameter $pages is no longer required in index() function.
In your routed controller, for this example the HomepageController, you can only specify index() function to get the which view file will be loaded as homepage.

class HomepageController extends Controller{
    public function index(){
        View::get('home');
    }
}

Documentation

app/
- controllers/
- models/
- views/
- routes.php
- settings.php
assets/
- css/
- img/
- js/
- index.php
core/
libraries/
- helpers/
  - generalHelper.php
- vendor/
- composer.json
- composer.lock
- TwigExtensions.php
.htaccess
index.php
php.ini
README.md
robots.txt