Category: MVC

A feature of good routing is the possibility to enforce policies that get specified for Controller classes and methods. For this purpose, frameworks such as ASP.NET use annotations on classes and methods. We wish to replicate this in PHP, but PHP does not support annotations.

phpDoc Comments

phpDoc comments are the official means to document class and function API in PHP. These comments are delimited by /** and */ character sequences (note the opening tag has 2* characters. The usual contents should include method parameters, return values, summaries, etc. We aim to add our own annotation to this phpDoc which we will in turn use to filter user access.

Consider a simple controller class with phpDoc comments as below:

In the above, we wish to apply the LoginFilter access policy to the entire class and the itemOwner policy only to Detail, Edit, and Delete methods.

ReflectionClass

For our purposes, phpDoc comments would serve no purpose without the means to efficiently extract them programatically. For this purpose, we use the ReflectionClass class, which provides an interface to all information about a selected class and its methods. Below, we extract the phpDoc comments of the class and each one of the methods:

More specifically for our purposes, we need to extract the phpDoc comments for the specific controller and method resolved in the routing algorithm. (If you have been reading this site, I place this functionality in the App class constructor.)

Below is an example of how, given a class, method, and parameters, we should extract, parse, and resolve the filters.

First, we initialize the ReflectionClass instance for this controller class and then extract the phpDoc comments for the class and method at hand. Then, we parse the phpDoc comment to retrieve any filter annotations and assemble these from the class and method in a single array. Then we run the filters and return the first redirection URL obtained, false otherwise. So the right time to call this method is right before calling the method on the controller class, as follows:

For any of this to work, of course, we must actually parse the phpDoc comments to extract the filter information, run the filters, and especially have filters to run in our code.

Parsing the phpDoc Comment

We must extract information from the phpDoc comments which resemble the following:

/**
Summary.
@accessFilter{filter1,filter2, filter3}
*/

For this purpose, we propose a method as follows:

On line 2, we extract all the accessFilter contents as elements in the $content array, with the key ‘content‘.

On line 3, we set $content to the value associated to the ‘content‘ key in $content, if any, or an empty string otherwise.

On line 4, we convert the string to an array of strings, one element per filter, without space characters.

Running the Filters

First and foremost, we must have filters to run. It is proposed to group these either in your routing class or a separate Filter class, as follows:

Each of the above methods will check conditions based on the session variables, parameters, or core functionality. For example, LoginFilter verifies if a user is logged in and returns a redirection URL otherwise, or false if the user need not be redirected. The function itemOwner compares the user id of the user logged in with the user id in the record to verify if the current user is not attempting to modify someone else’s data.

The strategy to run the filters is to run them one by one until a redirection is determined or all have been run. We then return the redirection to the calling method which will send it to the routing algorithm.

Conclusion

All the pieces are in place. We can now implement redirection policies and apply them to classes and methods with a simple phpDoc comment. Note that there should only be ONE phpDoc comment per class and per method, which integrates all relevant annotations, including ours: @accessFilter. Otherwise, the ReflectionClass method getDocComment will only be able to return the one before and closest to the class or method declaration.

PDO – PHP Data Objects – is a database access layer providing a uniform method of access to multiple database management systems. PDO does not account for database-specific syntax, but can allow for the process of switching databases and platforms to be fairly painless, simply by switching a connection string.

Database Support

The extension can support any database for which a PDO driver has been written. To find out which drivers you have, run the following command:

Connecting

Different databases may have slightly different connection methods. Below, the method to connect to MySQL databases is shown:

Take note of the try/catch block – you should always wrap your PDO operations in a try/catch, and use the exception mechanism. $DBH stands for ‘database handle’.

You can close any connection by setting the handle to null.

You can get more information on database-specific options and/or connection strings for other databases from PHP.net.

Exceptions and PDO

PDO can use exceptions to handle errors, which means anything you do with PDO should be wrapped in a try/catch block. You can force PDO into one of three error modes by setting the error mode attribute on your newly created database handle. Here’s the syntax:

No matter what error mode you set, an error connecting will always produce an exception, and creating a connection should always be contained in a try/catch block.

PDO::ERRMODE_SILENT

This is the default error mode. If you leave it in this mode, you’ll have to check for errors in the way you’re probably used to if you used the mysql or mysqli extensions. The other two methods are more ideal for DRY programming.

PDO::ERRMODE_WARNING

This mode will issue a standard PHP warning, and allow the program to continue execution. It’s useful for debugging.

PDO::ERRMODE_EXCEPTION

This is the mode you should want in most situations. It fires an exception, allowing you to handle errors gracefully and hide data that might help someone exploit your system. Here’s an example of taking advantage of exceptions:

There’s an intentional error in the select statement; this will cause an exception. The exception sends the details of the error to a log file, and displays a friendly (or not so friendly) message to the user.

Insert and Update

Inserting new data, or updating existing data is one of the more common database operations. Using PDO, this is normally a two-step process. Everything covered in this section applies equally to both UPDATE and INSERT operations.

Here’s an example of the most basic type of insert:

You could also accomplish the same operation by using the exec() method, with one less call. In most situations, you’re going to use the longer method so you can take advantage of prepared statements. Even if you’re only going to use it once, using prepared statements will help protect you from SQL injection attacks.

Prepared Statements

Using prepared statements will help protect you from SQL injection. A prepared statement is an SQL statement that can be executed multiple times just by changing the data and running the statement. It has the added advantage of automatically making the data used in the placeholders safe from SQL injection attacks, as part of the preparation. You use a prepared statement by including placeholders in your SQL. Here are three examples: one without placeholders, one with unnamed placeholders, and one with named placeholders.

You want to avoid the first method; it’s here for comparison. The choice of using named or unnamed placeholders will affect how you set data for those statements.

Unnamed Placeholders

Hint: read this only to understand how trrible this technique actually is. For a better technique see the following sections.

There are two steps here. First, we assign variables to the various placeholders (lines 2-4). Then, we assign values to those placeholders and execute the statement. To send another set of data, just change the values of those variables and execute the statement again.

Does this seem a bit unwieldy for statements with a lot of parameters? It is. However, if your data is stored in an array, there’s an easy shortcut:

The data in the array applies to the placeholders in order. $data[0] goes into the first placeholder, $data[1] the second, etc. However, if your array indexes are not in order, this won’t work properly, and you’ll need to re-index the array.

Named Placeholders

You could probably guess the syntax, but here’s an example:

You can use a shortcut here as well, but it works with associative arrays. Here’s an example:

The keys of your array do not need to start with a colon, but otherwise need to match the named placeholders. If you have an array of arrays you can iterate over them, and simply call the execute with each array of data.

Another nice feature of named placeholders is the ability to insert objects directly into your database, assuming the properties match the named fields. Here’s an example object, and how you’d perform your insert:

By casting the object to an array in the execute, the attribute names are mapped to keys and the values are set from each attribute.

Selecting Data

Data is obtained via the ->fetch(), a method of your statement handle. Before calling fetch, it’s best to tell PDO how you’d like the data to be fetched. You have the following options:

• PDO::FETCH_ASSOC: returns an array indexed by column name
• PDO::FETCH_BOTH (default): returns an array indexed by both column name and number
• PDO::FETCH_BOUND: Assigns the values of your columns to the variables set with the ->bindColumn() method
• PDO::FETCH_CLASS: Assigns the values of your columns to properties of the named class. It will create the properties if matching properties do not exist
• PDO::FETCH_INTO: Updates an existing instance of the named class
• PDO::FETCH_LAZY: Combines PDO::FETCH_BOTH/PDO::FETCH_OBJ, creating the object variable names as they are used
• PDO::FETCH_NUM: returns an array indexed by column number
• PDO::FETCH_OBJ: returns an anonymous object with property names that correspond to the column names

In reality, there are three which will cover most situations: FETCH_ASSOC, FETCH_CLASS, and FETCH_OBJ. In order to set the fetch method, the following syntax is used:

You can also set the fetch type directly within the ->fetch() method call.

FETCH_ASSOC

This fetch type creates an associative array, indexed by column name. This should be quite familiar to anyone who has used the mysql/mysqli extensions. Here’s an example of selecting data with this method:

The while loop will continue to go through the result set one row at a time until complete.

FETCH_OBJ

This fetch type creates an object of std class for each row of fetched data. Here’s an example:

FETCH_CLASS

Important note: when using this fetch mode, the properties of your object are set BEFORE the constructor is called. Therefore, you can use the constructor to modify and hide the data as required for your application.

This fetch method allows you to fetch data directly into a class of your choosing. When you use FETCH_CLASS, the properties of your object are set before the constructor is called. Read that again, it’s important. If properties matching the column names don’t exist, those properties will be created (as public) for you.

This means if your data needs any transformation after it comes out of the database, it can be done automatically by your object as each object is created.

As an example, imagine a situation where the address needs to be partially obscured for each record. We could do this by operating on that property in the constructor. Here’s an example:

As data is fetched into this class, the address has all its lowercase a-z letters and digits 0-9 replaced by the character *. Now, using the class and having that data transformation occur is completely transparent:

If the address was ‘123 Elm,’ you’d see ‘*** ***’ as your output. Of course, there may be situations where you want the constructor called before the data is assigned. PDO can also accommodate this by adding PDO::FETCH_PROPS_LATE as follows:

Now, when you repeat the previous example with this fetch mode the address will NOT be obscured, since the constructor was called before the properties were assigned.

Finally, if you really must, you can pass arguments to the constructor when fetching data into objects with PDO:

If you must pass different data to the constructor for each object, you can set the fetch mode inside the fetch method:

Some Other Helpful Methods

While this isn’t meant to cover everything in PDO (it’s a huge extension!) there are a few more methods you’ll want to know in order to do basic things with PDO.

The lastInsertId() method of PDO (not PDOStatement) will return the last inserted primary key value for this connection.

The exec() method is used for operations that cannot return data other than the number of affected rows.

The quote() method quotes strings so they are safe to use in queries. This is your fallback if you’re not using prepared statements.

The rowCount() method returns an integer indicating the number of rows affected by an operation.

MVC application output is defined in views. Four our PHP MVC application, these views are defined as .php files which mainly contain HTML/CSS/JavaScript code and some PHP to output model elements as required.

It is important to note here that the output formats depend on the application we are trying to build. For example, some applications, APIs, will output JSON data only and leave it up to a separate front-end to render the UI.

Going back to our example, let’s take a look at a simple view, itemList.php, stored in the /app/views/home/ folder:

<html>
<head><title>Item List</title></head>
<body>
<h1>List of items</h1>
<ul>
<?php
  foreach($data['items'] as $item){
    echo "<li>$item->name</li>";
  }
?>
</ul>
</body>
</html>

Much of the above view is directly output HTML code. However, the code between <?php ... ?> generates one <li>...</li> element per item in the $data[‘items’] collection passed to the view by the controller. The foreach loop is one of the most often used repetition instructions in PHP Views. For more information on all that can be done to produce correct output, refer to Hello PHP! and PHP: Getting Acquainted.

The main concern addressed by the Views is to format the data output as per the requirements for the application. This formatting is not a concern that the Model or Controller classes share. Concerns are task categories that should be handled by different classes when the separation of concerns is done correctly.

Tying this to the previous examples

Consider the following controller calling the above-defined view in its index method:

class HomeController extends Controller{
  public function index(){
    $items = $this->model('item')->get();
    $this->view('home/itemList',['items'=>$items])
  }
}

The above gets data from the storage and access interface through the call to $this->model('item')->get(). We assume item elements contain a name attribute. Then, this data is passed to the view on the following line. Notice how the view name is the folder and file name (less the .php) from the /app/views/ folder.

In the next post, we will look at building a model base class and model item class to match our example.

In MVC applications, HTTP requests lead to Controller method invocation (a.k.a. actions). It is inside controller methods that we define the application logic of an MVC application. In other words, this is where we define much of the application flow, user experience, features, etc.

The Controller base class

Given the orchestration role given to controllers, it will be their concern to invoke actions on Models (the data-handling part of the app) and call Views (the app output). We write the Controller base class to enable these methods.

Method model

Assume all model classes are contained in the /app/models folder in files with their class name.php. Furthermore, the program entry point is the index.php file in the document root.

protected function model($model){
  if(file_exists('app/models/' . $model . '.php')){
    require_once 'app/models/' . $model . '.php';
    return new $model();
  }else
    return null;
}

In the above, we check that the file exists and then require it to finally return a new object of this type. If the class definition does not exist, we return null. For the calling method, this will result in an object of the proper type to call the data processing methods.

Method view

The view method is invoked whenever the application is to produce output.

Assume all view files are located in the /app/views folder in files with their name.php. The program entry point is the index.php file in the document root.

protected function view($name, $data = []){
  if(file_exists('app/views/'.$name.'.php')){
    include('app/views/'.$name.'.php');
  } else {
    echo "ERROR: View $view not found!";
  }
}

This method checks the existence of a file and then includes it in order to produce the output defined in this file. If the file does not exist, it simply provides feedback to help the developer fix this error.

The complete Controller class

To complete the class, we simply assemble the two methods and wrap them in a class definition as follows:

class Controller{
  protected function model($model){
    if(file_exists('app/models/' . $model . '.php')){
      require_once 'app/models/' . $model . '.php';
      return new $model();
    }else
      return null;
  }
  
  protected function view($name, $data = []){
    if(file_exists('app/views/'.$name.'.php')){
      include('app/views/'.$name.'.php');
    } else {
      echo "ERROR: View $view not found!";
    }
  }
}

We will now require the Controller base class and extend it in all of the application classes in the /app/controllers folder.

Example Controller

We now explore the code for an example controller that will extend the Controller base class and use the Controller methods to produce useful results.

class HomeController extends Controller{
  public function index(){
    $items = $this->model('item')->get();
    $this->view('home/itemList',['items'=>$items])
  }
}

Given the correct model and view implementations, the above could get all items from a database table and display them in a list output for the user to see and act upon.

Tying it all together

For the controller class to be invoked, it is necessary to make sure that all dependencies are loaded properly and that the program is properly bootstrapped. To take care of the dependencies, we add a file named init.php in the /app folder:

<?php
  require_once 'core/App.php';
  require_once 'core/Controller.php';
?>

and include it from /index.php as in the following:

<?php
  require_once 'app/init.php';
  new App();
?>

With this application completed, the above-defined controller action could be called from a URL such as https://cstutoring.ca/Home/index.

In this post, we will explore a very naive but effective way of routing HTTP requests in Web applications.

The process for this routing scheme is to

1. Parse the URL into its components.
2. Map the URL components onto a Controller class, method, and parameters, if these exist.

Let’s start with the method which will be used to parse the URL:

private function parseUrl(){
    if(isset($_GET['url'])){
        return $url = explode('/', filter_var(rtrim($_GET['url'], '/'), FILTER_SANITIZE_URL));
    }
}

Here, we assume that a Query String parameter, url, contains the URL request. The method

• firstly verifies that this parameter exists,
• removes any leading “/” character,
• sanitizes the URL, and
• separates what remains into components, using the “/” character.

The explode function returns an array which would then contain, for instance, if /Teacher/StudentList were called:

['Teacher','StudentList']

Mapping to the Proper Class and Method

In this example application, all controller classes have Controller as a suffix in their names, are all contained in the /app/controllers folder in files with their class name.php. Furthermore, the program entry point is the index.php file in the document root.

The routing is handled in a class named App, written in the file App.php in /app/core as follows:

class App{
  //This class contains controller, method, & params
  //attributes, initialized with default values.
  public function __construct(){
      $url = $this->parseURL();

      if(file_exists('app/controllers/' . $url[0] . 'Controller.php')){
          $this->controller = $url[0] . 'Controller';
          unset($url[0]);
      }

      require_once 'app/controllers/' . $this->controller . '.php';
      $this->controller = new $this->controller();

      if(isset($url[1])){
          if(method_exists($this->controller, $url[1])){
              $this->method = $url[1];
              unset($url[1]);
          }
      }
      $this->params = $url ? array_values($url) : [];

      call_user_func_array([$this->controller, $this->method], $this->params);
  }

  private function parseUrl(){
      if(isset($_GET['url'])){
          return $url = explode('/', filter_var(rtrim($_GET['url'], '/'), FILTER_SANITIZE_URL));
    }
  }

}

Once the URL has been parsed into an array, the two first elements are examined to see if they match a Controller class and a method within this controller class. Then the call is made to this method, with any components of the URL leftover in the array as parameters. The process is invoked then the App class is instantiated into an object.

Handling Dependencies

We will add a file where all core dependencies for the application will be listed. We will call this file init.php and place it in the /app folder:

<?php
  require_once 'core/App.php';
?>

Tying it all together

In order for the routing to happen, it is necessary to bootstrap the application with a .htaccess file and an index.php file as follows:

<?php
  require_once 'app/init.php';
  new App();
?>

For example, the URL /Teacher/StudentList would yield a call to the StudentList method of the TeacherController class, without any parameters.

Moreover, the URL /Student/message/Alice would yield a call to the message method of the StudentController class, with one parameter containing the value Alice.