Brief Tour


Controllers
Views
Templating
Models

Controllers

Controllers form the entry point into your application. It is from here that you can call your model classes, libraries and load the view files, among other things...

<?php namespace Controllers;

/**
 *This class loads the application homepage
 *@author Geoffrey Bans <geoffreybans@gmail.com>
 *@copyright 2015 - 2020 Geoffrey Bans
 *@category Controllers
 *@package Controllers\Home
 *@link https://github.com/gliver-mvc/gliver
 *@license http://opensource.org/licenses/MIT MIT License
 *@version 1.0.1
 */

use Helpers\View\View;

class HomeController extends BaseController  {

    /**
     *This method loads the preface page.
     *@param null
     *@return void
     */
    public function getIndex()
    {
        //get the ending date today
        View::render('home/index');

    } 

}  

Controllers reside in the application/controllers/ directory - and are always autoloaded as need be, so all you need is define the code to be executed and the excecution would proceed seamlessly. When defining your controllers, you wanna ensure you stick to this pattern:

  • The file that contains your controller class must reside within the application/controllers directory or subdirectory
  • One file can only contain one controller class.
  • Controller class files must have a .php file extension. The name of the controller class must be the same as the name of the file: HomeController class should be in HomeController.php.
  • Controller class and file names must have the 'Controller' suffix as HomeController.
  • When accessing controllers from a url, you only specify the controller name without the 'Controller' suffix as http://localhost/gliver/home
  • All controllers classes must extend the BaseController class.
  • You want to ensure you namespace your controllers, so that they will be autoloaded as expected. If your controller class resides in the application/controllers directory then use namespace Controllers; else if your controller resides within a subdirectory like 'Admin' as application/controllers/Admin use namespace Controllers\Admin; - this follows psr-4 namespace pattern.
  • You cannot create static methods or properties in your controllers.

Use PHPDoc commenting style to add metadata to your class - as part of your documentation. This would help you and other developers looking at your code understand the purpose of your controller classes, methods and expected behavior of the controllers.

In order to use a class inside of your controller class, use the use statement with the full namespace of the class as use Helpers\View\View; to load the view helper class then access it as View::render('home/users');

When defining your methods in your controllers, you can choose to let all your methods be unique or you can use the same method name to excecute different methods based on the request method used. There are two request methods that would be detected by Gliver framework : GET and POST methods.

With this feature comes a cool ability of Gliver to load a controller method based on your request method. This means that you can use the same method name in different request methods. For example:

Say you have a controller class named LoginController and would like to use the same method name for loading a login form and at the same time processing user login information - you will do this as below.

Create two methods named getLogin() and postLogin(). You will access both methods with the same url as http://localhost/gliver/login/login. Accessing this url in your address bar will load the user login form as the request method would be GET and the getLogin method would be excecuted. Once the user fills up the form, you specify in your action attribute the same url for form submission as this <form action="http://localhost/gliver/login/login" method="post" >. When the user then submits the form, Gliver would detect this as a POST request and therefore submit your form to the postLogin method of the LoginController. So, there you go! Using the same method name to excecute different methods depening on the request method.

Views

The view class enables you to invoke a response to the url request. This can in the form of loading view files to provide a graphical interface to enable your users to interact with your application or set header for sending pdf, json, xml responses among others...

You call the view class from the controller by first requiring it using the statement use Helpers\View\View; after which you access the View class and methods directly without creating an instance. For instance, this is how you will load a view file View::render('home/users', $data); More methods available in the View class are described in the Helpers section

All view files are located in the application/views directory.

If you put your view files in a subdirectory under the views directory, you access them by separating the directories with a forward slash. Say you have put your index.glade.php view file in your home subdirectory under the views folder - in order to load this view from the view class, you specify View::render('home/index').

Most of the time when you are loading your views, you may need to pass variables along so that their values are injected into the views. This is completely in built in Gliver. All you need to do is pass the variables in an array and then access them using the array key.

Say we would like to dynamically get the site title from the controller and use it in our view file in this manner <title><?php echo $title; ?></title>. Create a $data array and store the value of the title as a key in the array as $data['title'] = "Gliver - Official Site";, then pass this as a second parameter to the View::render() method as View::render('home/index', $data);

Templating

Out of the box, Gliver has an in built templating engine called glade. This engine is rather simple and has been kept light-weight for the purpose of faster view file parsing - so there are no complicated methods, only the most commonly repeated actions in view files have been abstracted.

All view files should have a .glade.php extension in order to be parsed by the View loader class. When specifying the view file though, you do not need to add the file extension as this is enabled by default. Say you have a file named index.glade.php in your root views directory. In order to load this view file from the View class you will use this syntax View::render('index'); and this would definitely load the view file at application/views/index.glade.php.

Glade basically has the following template methods that you can use in your view files

Echo

In regular PHP in order to echo a string to the browser, you'd open and close PHP tags then use the echo statement in between the tags. You have more than 5 variables to echo in your view files and you are already wishing there was an alternative. Look at this <?php echo $username; ?>, ugly? Huh? Let's make it elegant -> {{$username}}. That's all you need to do to print out the value of a variable to the browser in glade template files. <p>{{$username}}</p>

@include

Subdeviding your view files into parts saves you time when you need to make updates. Say you have 100 view files that have the same content in the header and footer. You might want to ensure that you separate the header and footer and put them in a place where all the other view files refrence them. So if you need to make a change to the footer content, you just update one file - the footer, and all the other view files would be up-to date, as opposed to if you would have had to iterate through all the 100 views files updating header and footer content.

Glade enables you to include sub-views into your view file using the @include() statement, passing the name of the file to include as the first parameter.

Say you have a header.glade.php and footer file in your home directory and would like to pull it into your home/users page.

@include('home/header')
<div class="container"> <div class="row"> <div class="col-lg-12"> </div> </div> </div> @include('home/footer')

@if...@endif

@if(isset($email) AND ! empty($email))
  <p>Your email address is {{$email}}</p>
@endif

@if...@else...@endif

@if(count($users) > 0)
  <p>Registered users({{count($users)}})</p>
@else
  <p>There are no registered users yet!</p>
@endif

@if...@elseif...@else...@endif

@if($score > 80) 
  <p>Grade : A  Remarks : Excellent</p>
@elseif($score > 60)
  <p>Grade : B  Remarks : Good </p>
@else
  <p>Grade : C  Remarks : Fair</p>
@endif

@while...@endwhile

@while($number <= 10)
  <p>Number is {{$number}}</p>
  ....do something to terminate loop
@endwhile

@for...@endfor

@for($itr = 1; $itr < 10; $itr++)
  <p>This is paragraph number {{$itr}} </p>
@endfor

@foreach...@endforeach

@foreach($users as $user)
  <p>Name {{$user['first_name']}} : Email : {{$user['email_address']}}</p>
@endforeach

Models

Models classes will help you handle database operations or API connection operations.

All model classes reside in the application/models directory and must extend the Model class. This ensures acccess to the already built in functionality of the model class.

<?php namespace Models;

/**
 *This models handles all user management datatabase operations
 *@author Geoffrey Bans <geoffreybans@gmail.com>
 *@copyright 2015 - 2020 Geoffrey Bans
 *@category Models
 *@package Models\UsersModel
 *@link https://github.com/gliver-mvc/gliver
 *@license http://opensource.org/licenses/MIT MIT License
 *@version 1.0.1
 */

class UsersModel extends Model  {

  /**
  *@var  string The name of the table associated with this model
  */
  protected static $table = 'users'; 

  /**
   *This method gets the records of all users from the database
   *
   *@param null
   *@return array The users data in an array format
   */
  public static function all()
  {
    //excecute query to return all users
    $users = static::Query()->from(self::$table)->all();

    //return the rows found
    return $users;

  }

}

All methods of the Model class must be declared static in order to be accessible.

When defining your Model classes, you wanna ensure you stick to this pattern:

  • The file that contains your model class must reside within the application/models directory or subdirectory
  • One file can only contain one model class.
  • Model class files must have a .php file extension. The name of the Model class must be the same as the name of the file: UsersModel class should be in UsersModel.php.
  • Model classes and file names can optionally have the 'Model' suffix as UsersModel.
  • When accessing models classes specify the complete name without omiting the 'Model' suffix as use Models\UsersModel;
  • All model classes must extend the Model class.
  • Ensure you namespace your models, so that they will be autoloaded as expected. If your model class resides within a subdirectory like 'Admin' as application/models/Admin use namespace Models\Admin; - this follows psr-4 namespace pattern.
  • All methods and properties of the model class must be declared static and the model class methods and properties are accessed directly, without creating an instance of the model class by specifying the class name, the scope resolution operator and the property or method name as UsersModel::all()

In order to use a model in your controllers, load the model by use of the use keyword followed by the full namespace of the model. Say you have a model named UsersModel that resides within the Admin directory. Besides, our model has a static method getUser() that fetches the details of a user from the database. For us to access this model in our HomeController class as do as :

use Helpers\View\View;
use Models\Admin\UsersModel;

class HomeController extends BaseController {

  /**
   *This method loads user's profile page 
   *
   *@param null
   *@return void
   */
  public function getUser()
  {
    //call model to get user information, passing the $user_id
    $data['user'] = UsersModel::getUser($user_id);

    //load the users profile page
    View::render('home/user_profile', $data);

  }

}

For more information on how to make use of the Query Builder and ORM read more on the Database section of this documentation.