PHP MVC Framework Documentation

Description

Introduction

MVC Frameworks have existed for quite some time for all the major languages including PHP. One may ask why on Earth would we need another? The simple answer is agility, flexibility, and a small learning curve.

Developers using PHP eventually reach a point where they realize mixing PHP and HTML together in the same file creates code that can be messy and generally impossible for a designer without knowledge of PHP to update in the future. The below framework makes use of only a single PHP library known as the Smarty Template Engine.

Related Project Logs

Structure

When a new PHP MVC application from scratch it's best to design a folder hierarchy that makes logical sense. All smarty class files are stored in /libs/smarty/, all application class files are stored in /libs/classes/. Template files can be stored in the root of the /templates/ folder however to maintain a site with multiple template versions they must be stored in their own directories, /templates/version1/ for example would be the first version of the sites template. All assets for the template should be stored inside its template folder keeping multiple versions of site images and javascript separate from the other versions. The /templates_c/ folder contains a cached copy of the template as it was last rendered minus variables that were assigned allowing smarty to quickly render the next request for that page. The /config.php file is where all classes get included and constant variables get defined that will be used throughout the entire application, for example the current version and name of the company.

  • libs
    • classes
      • accounts.inc.php
      • general.inc.php
      • routing.inc.php
    • smarty
      • Smarty.class.php
  • templates
    • default
      • css
        • style.css
      • js
        • jquery.min.js
        • functions.js
      • images
      • footer.tpl
      • header.tpl
      • index.tpl
      • accounts.tpl
  • config.php
  • index.php

MVC

Model

The Smarty template engine allows you to assign data that will be used when rendering the given template file(s). Assigning data to the Smarty object is simple and most data types such as string, integer, double, array, are allowed.

$strTitle = 'My First Smarty Webpage';
$Smarty->assign('pagetitle', $strTitle);

$arrAccounts = Array(
  'General McNugget',
  'Tom Flansey',
  'Mr. Fires'
);
$Smarty->assign('accounts', $arrAccounts);

View

Smarty templates mix HTML with special tags recognized by the template engine while rendering the given template file(s). Any PHP function can be called from within a Smarty tag with most common functions built in. Using if statements and for loops its possible to conditionally output other sections of HTML or create lists.

{include file="header.tpl"}
  <table>
  {foreach from=$accounts item=account}
    <tr>
      <td>{$account}</td>
    </tr>
  {/foreach}
  </table>
{include file="footer.tpl"}

Controller

Switching between views can be handled with many different approaches. Generally the controller of a PHP application is the index.php file which either does the routing itself or calls a function or class which performs this action.

$Routing = new Routing();
$Routing->processPageRequest($_GET['m']);

class Routing {

  function processPageRequest($page) {

    global $Smarty;

    switch ($page) {
      case '':
      case 'home':
        $Smarty->display('index.tpl');
        break;

      case 'accounts':
        $Accounts = new Accounts();
        $Smarty->assign('accounts', $Accounts->listAccounts());
        $Smarty->display('accounts.tpl');
        break;

      default:
        $Smarty->display('pagenotfound.tpl');
    }

  }

}

Example Explained

config.php

The config.php contains all our global application settings and includes all our class and function files. The below first defines the domain or host that is currently being used to access the site and next we let our application know the expected path shown in the browsers address bar to access the page.

define('WEB_DOMAIN', (($_SERVER['HTTP_HOST']) ? $_SERVER['HTTP_HOST'] : $_SERVER['SERVER_NAME']));
define('WEB_DIR', '/path/in/browser/');

These are put in all my projects since most applications will use most if not all of these variables and more to brand the application. We set these here so they can be changed in one location without updating all your template files.

define('COMPANY_NAME', 'Xodus Technologies');
define('APP_TITLE', 'Xodus Tech');
define('APP_VERSION', '0.1.0');
define('APP_AUTHOR', 'Travis Brown');
define('SMARTY_CACHING', 0);

Now we have PHP automatically detect the directory where config.php is located and then setup other general paths that will be used to include our classes and templates.

define('INSTALL_DIR', dirname(__FILE__).'/');

define('LIBS_DIR', 'libs/');
define('CLASSES_DIR', LIBS_DIR.'classes/');
define('TEMPLATES_DIR', 'templates/');
define('TEMPLATES_C_DIR', 'templates_c/');

With the paths all setup we can now start including the application's various class and functions files.

require_once(CLASSES_DIR.'accounts.inc.php');
require_once(CLASSES_DIR.'general.inc.php');
require_once(CLASSES_DIR.'routing.inc.php');

Lastly we include the Smarty Template Engine class file.

require_once(LIBS_DIR.'smarty/Smarty.class.php');

index.php

The index.php is the controller for this application. It's purpose is to setup Smarty and then process the URL using the Routing class to determine the proper view to show. The first thing we do is include config.php which as described above sets up the basic structure of our application.

require_once('config.php');

Now we create a new instance of the Smarty class and set caching to enabled or disabled per the setting placed in config.php.

$Smarty = new Smarty();
$Smarty->caching = SMARTY_CACHING;

Next we set some variables to be used when rendering the template file(s) for the views we will display later on. WEB_DIR and REL_TEMPLATE are important as they preserve the path to the root of the application as seen by the browser. This comes into play when loading resources like images from addresses that may be called from sub directories of the application root.

$Smarty->assign('APP_TITLE', APP_TITLE);
$Smarty->assign('WEB_DIR', WEB_DIR);
$Smarty->assign('REL_TEMPLATE', WEB_DIR.TEMPLATES_DIR);

Lastly we send our URL request to the Routing class which decides which displays the appropriate view.

$Routing = new Routing();
$Routing->processPageRequest($_GET['m']);

Creator

PHP MVC Framework was created by Travis Brown, email: WarriorRocker@gmail.com.