1. Download and Unpack

Download the latest version of Katharsis Framework and unpack it to your local php workspace. (XAMPP default folder: htdocs)

2. Project Structure

When you open the project directory you will see a project structure as per margin.

application

In this directory you see three subdirectories: controller, model and view - these are the three parts of the MVC-Design-Pattern.

controller

With specifying several Controllers you arrange the different parts of your application into groups of methods, for example access, administration, index. These Controller classes contain several methods called Actions.

model

Models are classes that cummunicate with any external data provider, for example a mysql database, a xml-file or a webservice. Models also process business logic.

view

The view .phtml files are templates that determine what your different GUI pages contain and how they look like.

config

Any configuration files for example the database.config.ini, that defines mysql database connection details.

library

Store any external PHP classes and libraries, that you want to use in this directory. \ For example any additional parser classes, a template engine like Smarty, or even the whole Zend library.

It contains the Katharsis library by default.

public

Here you deposit all files that have to be called via web directly, like images, stylesheets, javascripts and so on.

If possible, this should be the only public directory. That means that your apache root directory of your domain or subdomain should point to this folder.

Also you can see a .htaccess file as well as index.php. You will read about them in the chapter "How It Works".

3. Get Started

Controllers And Actions

In Katharsis projects the url are designed by the following scheme:

http://localhost/KatharsisExample/public/index/index

This will effect, that the indexAction in the IndexController is going to be called.

Writing Controllers and Templates

If you open up the IndexController.php file you will see, that there is already a pretty basic example of a controller class. Take a look at the following lines:

public function indexAction()
{
    $this->_view->someVariableName = 'Katharsis';

    echo $this->_view->render('welcome');
}

By assigning values to variables in the view, you can make dynamic data accessible in your templates, like in this example. The string 'Katharsis' is being assigned to the view variable someVariableName. The render method renders your whished template and returns the result. Don't forget to echo it ;)

Now you are able to access someVariableName in your template file. In this case welcome.phtml

<p>
    This is an empty <?=$this->someVariableName?> project.
</p>

4. How-It-Works

.htaccess

The processing of every Katharsis project begins with the .htaccess file in the public folder. It makes shure, that every HTTP request will be rewritten to the public index.php file unless it is directed to a file that is actually existing in the public folder like images, script and style files.

Public index.php

This is the beginning of the actual PHP processing of a Katharsis project. It initialises everything the framework needs, registers plugins and runs the bootstrap process.

Bootstrap

The heart of Katharsis. It processes the plugin interface and the controller routing.

5. Mysql Database Connector

Setting up database.config.ini

First thing to do if you want to use the Katharsis Mysql interface is to type in your database connections into the config/database.config.ini file. You will find a sample connection in there, that is commented out by semicolons.

[connection:development:default]
host = localhost
user = root
password = 
database = myDatabaseName

It is possible to use multiple database connections as well. Just apply to the following scheme of ini section name:

[connection:NameOfYourConnection]

If you want, you can add :default to your main connection.

Connecting

Katharsis automatically connects to all connections that are typed into the config file.

In all controllers and model classes you can access the default connection by using this:

$this->_con

Otherwise you will have to connect like this:

$con = Katharsis_DatabaseConnector::getConnection('NameOfYourConnection');

If you call getConnection() without a parameter, the default connection will be choosen.

Executing a Statement

The most common way to execute a SQL statement:

$sql = "SELECT id, name FROM table WHERE group = :mygroup AND category = :c";

$values = array("mygroup" => 6, "category" => 'stuff');
$sql = $this->_con->createStatement($sql, $values);

$result = $this->_con->fetchAll($sql);

Important Database Methods

Method Description

createStatement($sql, $values) Builds a clean SQL string fetchAll(\$sql) Returns a multidimensional array result fetchOne(\$sql) Returns one result row as a onedimensional array fetchField(\$sql) Returns the value of one field insert($table, $values) Inserts one row into a table count(\$sql) Counts result rows analyseLast() Prints out detailled information about the last statement lastInsertId() Returns the value of one field

7. Plugin Interface

With plugins it is possible to call methods before and/or after the controller is processed.

Write a Plugin

class MyPlugin extends Katharsis_Controller_Plugin_Abstract
{
    public function preController()
    {
        // some actions
    }

    public function postController()
    {
        // some actions
    }
}

Take a look at the example above. Notice that your plugin has to extend the Katharsis_Controller_Plugin_Abstract class. You just need to overwrite the method preController and/or postController to get going.

Register Plugins

It is important to register all plugins that you want to be called. Open the public/index.php file and place your plugin registrations in there like this:

chdir('..');
require_once('library/Katharsis/Bootstrap.php');
Katharsis_Autoload::init();

Katharsis_Controller_Plugin::registerPlugin(new MyAccessPlugin());
Katharsis_Controller_Plugin::registerPlugin(new MyRenderPlugin());

try {
    Katharsis_Bootstrap::run();
} catch(Exception $e)
{
    echo '<h2>Exception thrown</h2>';
    echo '<h3>' . $e->getMessage() . '</h3>';
    echo '<pre>';
    print_r($e);
}

Your plugins will be called in the same order as you register them:

1. MyAccessPlugin -> preController
2. MyRenderPlugin -> preController
3. Controller -> Action
4. MyAccessPlugin -> postController
5. MyRenderPlugin -> postController

Take a look at the diagram in the chapter "How It Works" for a better understanding.

Request Manipulation

It is a usual method to manipulate the controller or action that is going to be called by using the preController plugin hook. You can use this for building an access control.

class MyAccessPlugin extends Katharsis_Controller_Plugin_Abstract
{
    public function preController()
    {
        session_start();

        if(Katharsis_Request::getControllerName() != 'access')
        {
            if($_SESSION['loggedIn'] != 'yes')
            {
                Katharsis_Request::setControllerName('access');
                Katharsis_Request::setActionName('gate');
            }
        } 
    }
}