Cohesion PHP Framework¶

Origins¶

Cohesion started from me deciding to start a new project in PHP. I didn’t have much experience with many PHP frameworks so rather than looking through all the existing frameworks and picking the one that seemed to make the most sense to me, I decided to list all the ‘features’ I wanted in a framework before trying to find one suitable.

Coming from a long history of programming in a myriad of languages, I realised that one of my main requirements was to have a strong code structure to provide a strong backbone of the application so that it’s very easy to maintain in the future. I have managed large teams of software engineers maintaining large code bases and I know how painful it can be to add new features or change existing ones when every engineer decides to implement his own structure.

In going through all the existing frameworks I found that none of them really gave me what I wanted. Probably the closest ones would be Symfony and Laravel but still they didn’t really give me everything I needed. So I set out to develop a simple framework that will give me everything I need and will help make sure that I will be able to continue to easily add more features in the future even when my project has grown to hundreds of classes and will be able to easily go in and optimize the data access etc without having to worry about effecting any business logic etc.

One of the issues I have with many of the other frameworks is that they provide a good foundation for developing “anything” but then let the developers do whatever they want on top of it. They pride themselves as being extremely customizable and letting users choose how they want to use it. While that’s fantastic for many people, I want something that will provide more than a foundation, I don’t want other people to “use it how ever they want”. In going with this theme I’ve tightened “how” Cohesion can be used down a bit and don’t have as many “options”.

Philosophy¶

Cohesion is for people who envision their product continuing to grow and place a high value on maintainability and low technical debt.

Cohesion tries to bring many of the well established development “best practices” into the main development pipeline for PHP projects.

I’m sure Cohesion won’t be for everyone, as most people are happy with something they can quickly hack a website on top of and continue just quickly hacking stuff on top.

It provides the framework for you to create a service based architecture for your applications.

Requirements¶

Once PHP is installed and set up adding additional libraries will be handled by Composer but there are still a few things you need to install yourself before then.

• PHP version 5.4 or above
• PHP-FPM
• MySQLnd extension
• APCu extension
• CURL extension

sudo apt-get install php5 mysql-client php5-mysqlnd php5-fpm php5-curl php-pear php5-dev

sudo pecl install apcu

sudo echo "extension=apcu.so" > /etc/php5/mods-available/apcu.ini
sudo ln -s /etc/php5/mods-available/apcu.ini /etc/php5/conf.d/20-apcu.ini
sudo ln -s /etc/php5/mods-available/apcu.ini /etc/php5/fpm/conf.d/20-apcu.ini

sudo vi /etc/php5/fpm/pool.d/www.conf

[...]
;listen = 127.0.0.1:9000
listen = /var/run/php5-fpm.sock
[...]

Installing Composer¶

Composer is the package manager used by modern PHP applications and is the only recommended way to install Cohesion. To install composer run these commands:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Installing Nginx¶

It’s recommended to use Nginx with Cohesion. Nginx is a very lightweight web server and is much more efficient than Apache and very easy to configure:

sudo apt-get install nginx

Installing Cohesion with Composer¶

Once composer is installed run the following command to create a new project in a myproject directory using Cohesion:

composer create-project cohesion/cohesion-framework -sdev myproject

Composer will then download all required dependencies and create the project directory structure for you.

After composer finishes the installation process the installer will ask you Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? just hit <Enter> to safely remove the Cohesion git history. This will prevent you from polluting your projects version history with Cohesion commits. It will also make it easier to set up your own version control for your project.

Setting up Nginx server¶

Default Nginx configurations are provided within the /config/nginx/ directory of your project. So that we can keep our server configurations in version control we’ll just link to the configuration file you want to use for the current environment within our project:

sudo ln -s /full/path/to/myproject/conf/nginx/local.conf /etc/nginx/sites-available/myproject-local
sudo ln -s /etc/nginx/sites-available/myproject-local /etc/nginx/sites-enabled/myproject

Open up the configuration and set the root path to the www directory within your project:

vi config/nginx/local.conf

You can create additional Nginx configuration files for your different environments just remember to change the server_name, root path and APPLICATION_ENV.

Restart nginx:

sudo service nginx restart

Now you should be able to see a default Cohesion welcome page when you go to http://localhost.

Frontend¶

If you haven’t changed your configuration yet your default controller should be ‘Home’ with the default function on ‘index’. This means that if you go to http://localhost/ it should look for the HomeController and execute the index function on it.

The Cohesion Framework comes with a very simple home page. Open up www/controllers/HomeController.php you should see it looks like this:

use \Cohesion\Structure\Controller;
use \Cohesion\Structure\Factory\ViewFactory;

class HomeController extends Controller {

    public function index() {
        $view = ViewFactory::createView('Home');
        return $view->generateView();
    }
}

Here we can see it’s creating a ‘Home’ view. This can be found at www/views/HomeView.php.

class HomeView extends MyView {
    public function __construct($template, $engine, $vars) {
        parent::__construct($template, $engine, $vars);
        $vars['page'] = 'home';
        $vars['title'] = $vars['site_name'] . ' Home';
        $this->addVars($vars);
    }
}

As you can see this is extending MyView class. All your views should extend that class (feel free to rename it) and that is where you can put any common logic that all your views should have access to.

Next we see it’s calling it’s parent constructor and passing through the template engine and variables. Don’t worry too much about this, this is just setting up the templating engine.

The last thing in this file we see is that it’s adding a new variable, ‘page’ and setting it to ‘home’. You can add as many variables as you want here and they will all be available within the front end template. page is a special variable though and must be set in every view. The variable set in page is used to decide which template to use. In this case it will be using the home.html template. title is the variable that will be used for the title of this page. You can see here it’s using one of the default variables set in the configuration ‘site_name’.

Let’s look at the root template www/templates/index.html. All pages use the same template by default. It’s possible to override this behaviour in the View class but most of the time you’ll probably want all your pages to have the same header and footer.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>{{title}}</title>
    </head>
    <body>
        {{> header}}
        {{> page}}
        {{> footer}}
    </body>
</html>

As you can see this template is extremely simple and you’ll probably want to fill it out much more. Here you can start to see the Mustache templating library in action. {{title}} will be replaced with the title set in the view.

In Mustache the > modifier is used to load a sub template (partial). In Cohesion the partial template name can be overwritten by setting a variable with that name. Since we set the variable page to home it will load the www/templates/home.html template in the middle. But the header and footer weren’t overwritten so they will just use the templates www/templates/header.html and www/templates/footer.html. So if you modify the header template it will update the header on every page then we can just change the page variable to set the main content of the page.

Backend / Services¶

Your main code for all your business logic will go into folders within the src/ directory.

Let’s run through creating a user.

We’ll start by creating a directory src/user/ and adding a User.php file to it as our DTO:

use \Cohesion\Structure\DTO;

class User extends DTO {
    protected $id;
    protected $username;
    protected $email;
    protected $password;

    const MIN_USERNAME_LENGTH = 3;
    const MAX_USERNAME_LENGTH = 30;
    const MIN_PASSWORD_LENGTH = 6;

    public function setUsername($username) {
        if (strlen($username) < self::MIN_USERNAME_LENGTH) {
            throw new UserSafeException('Username must be at least ' . self::MIN_USERNAME_LENGTH . ' characters long.');
        } else if (strlen($username) > self::MAX_USERNAME_LENGTH) {
            throw new UserSafeException('Username cannot be longer than ' . self::MAX_USERNAME_LENGTH . ' characters.');
        }
        $this->username = $username;
    }

    public function setEmail($email) {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new UserSafeException('Invalid email address');
        }
        $this->email = $email;
    }

    public function getUsername() {
        return $this->username;
    }

    public function getEmail() {
        return $this->email;
    }
}

That’s all that’s needed for now. The constructor of the parent DTO class will be able to take in an associative array and call the appropriate mutator functions. And also provides a getVars() function that will return the protected variables as an associative array.

Next lets create a UserService at src/user/UserService.php. The service is the external API for everything other components need to do with “users”. Normally it would include a bunch of authorization code etc but for now let’s just keep it simple.

use \Cohesion\Structure\Service;
use \Cohesion\Auth\AuthException;

class UserService extends Service {
    public function getUser($id) {
        return $this->dao->getUser($id);
    }

    public function getUserByUsername($username) {
        return $this->dao->getUserFromUsername($username);
    }

    public function createUser($user) {
        $user = $this->dao->getUserFromUsername($user->getUsername());
        if ($user) {
            throw new AuthException("Username {$user->getUsername()} is already taken");
        }
        try {
            $this->dao->createUser($user);
        } catch (DBException $e) {
            throw new AuthException('Unable to register new user');
        }
        return $user;
    }
}

The constructor of the parent Service will create the dao for us and will look for a class named UserDAO so let’s create that now. src/user/UserDAO.php:

use \Cohesion\Structure\DAO;

class UserDAO extends DAO {

    public function getUser($id) {
        $result = $this->db->query('
            SELECT u.id, username, email
            FROM users
            WHERE id = {{id}}
            ', array('id' => $id));
        if ($row = $result->nextRow()) {
            return new User($row);
        } else {
            return null;
        }
    }

    public function getUserFromUsername($username) {
        $result = $this->db->query('
            SELECT u.id, username, email
            FROM users
            WHERE username = {{username}}
            ', array('username' => $username));
        if ($row = $result->nextRow()) {
            return new User($row);
        } else {
            return null;
        }
    }

    public function createUser(&$user) {
        $result = $this->db->query('
            INSERT INTO users
            (username, email, password)
            VALUES
            ({{username}}, {{email}}, {{password}})
            ', $user->getVars());
        $user->setId($result->insertId());
        return $user;
    }
}

The parent DAO constructor will set the db for us so we don’t need to worry about getting the database connection. If we wanted to be able to access other libraries from within the DAO we can override the constructor and define the extra data accesses we need.

For example if we wanted to use a cache we could add a constructor like this:

use \Cohesion\Structure\DAO;
use \Cohesion\DataAccess\Database\Database;
use \Cohesion\DataAccess\Cache\Cache;

class UserDAO extends DAO {

    protected $cache;

    public function __construct(Database $db, Cache $cache) {
        parent::__construct($db);
        $this->cache = $cache;
    }

    public function getUser($id) {
        $userData = $this->cache->get("user_$id");
        if (!$userData) {
            $result = $this->db->query('
                SELECT u.id, username, email
                FROM users
                WHERE id = {{id}}
                ', array('id' => $id));
            if ($userData = $result->nextRow()) {
                $this->cache->save("user_$id", $userData);
            }
        }
        if ($userData) {
            return new User($userData);
        } else {
            return null;
        }
    }
    // ...
}

We don’t need to change any code anywhere else other than making sure that the Cache is set up properly in the configuration files.

Services - Business Logic¶

Services contain all the business logic and only the business logic for a specific object. I’ve called the business logic section ‘Services’ because I want people to think of them as an independent Service for one portion of the application. The service will contain all the authorisations and validations before carrying out an operation. Services are the entry point for the DAOs, where only the UserService accesses the UserDAO. The UserService can be thought of as the internal API for everything to do with Users.

Data Transfer Objects (DTOs) - Object Data¶

DTOs are simple instance objects that contain the data about a specific object and don’t contain any business logic or data access logic. DTOs have accessors and mutators (getter and setters) and can contain minimal validation in the mutators.

Data Access Objects (DAOs) - Data Access Logic¶

DAOs contain all the logic to store and retrieve objects and data from external data sources such as RDBMSs, non relational data stores, cache, etc. The DAO does not contain any business logic and will simply perform the operations given to it, therefore it’s extremely important that all accesses to DAOs come from the correlating Service so that can perform the necessary checks before performing the storage or retrieval operations. The Service doesn’t care how the DAO stores or retrieves the data only that it does. If later down the line a system is needed to be converted from using MySQL to MongoDB the only code that should ever need to be touched would be to within the DAOs.

Controllers¶

The Controllers are the external facing code that access the input variables and returns the output of the relevant view. The Controller handles the authentication, accesses the relevant Service(s) then constructs the relevant view. It doesn’t contain any business logic including authorisation.

Views¶

Views take in the required parameters and return a rendering of what the user should see. Views don’t perform any logic and don’t do any calls to any function to get additional data. All data that the view will need should be provided to the view from the Controller.

File Structure¶

The configuration is very well structured and documented so make sure you take the time to read the comments in the cohesion default configuration file about what each setting does.

When constructing various objects and libraries they will be given a sub section of the configuration so it’s important to get the structure right.

All objects and libraries will have access to the global section.

Each Service that you create will get a copy of the application section. The view and templating library will get the view section. The database class will use a copy of the data_access.database. And so on and so forth.

Environment specific configurations¶

Cohesion can load an additional separate configuration for different environments such as different database settings, etc for your dev, staging and production environments. These are just examples you can have separate configuration for whatever different environments you might have. Simply create additional configuration files in the form {environment}-conf.json. For example, local-conf.json or production-conf.json.

Again these are cascaded so you only need to include the settings that are different for that environment and it will get the rest of the settings from your default-conf.json and the cohesion-default-conf.json.

Configuration Options¶

Dependency Injection simplified¶

If you’re not aware of what dependency injection is you can read about it on Wikipedia. But if you do you might get a bit scared off because they make it sound quite complex when it’s really actually quite simple. The idea is that rather than hard coding the other classes your class will use it takes them in via the constructor parameters or a setter method.

For example rather than in your class creating a MySQL connection to talk to the database you can specify that your class needs an instance of something that implements the Database interface and then it will be up to the code that calls your class to pass in the instance.

How Cohesion performs Dependency Injection¶

In Cohesion we’ve gone one step further and abstracted away creating the instances anywhere within your code and is instead up to the configuration to supply the information needed to decide how to create instances that implement the interface you need.

So basically you can just say, I need a Cache library, then in the config you can decide whether to use APC, Memcache, Redis, or whatever. And at any point you can change which type of cache you’re using just by updating your configuration.

The dependency injection relies heavily on PHP Reflection to inspect the object you want to create, look at the parameters the constructor is asking for, get the required library based on the config and pass in an instance. This is the job of the Factories.

class UserDAO extends DAO {
    protected $cache;
    protected $locationDao;

    public function __construct(Database $db, Cache $cache, LocationDAO $locationDao) {
        parent::__construct($db);
        $this->cache = $cache;
        $this->locationDao = $locationDao;
    }
    ...
}

Route matching¶

The current routing doesn’t get specified but instead in inferred by the path, class and function names of the Controllers.

Based on /{directory}/../{controller}/{function}/{var}. For example /user/list/all would call UserController->list('all').

hyphens (-) in the path are used as word separators so that it can match the correct capitalisation of controller and function names. /contact-us will match ContactUsController.

class FooController extends Controller {
    function index($param1, $param2, $param3 = null) {
        // ...
    }

    function bar($param1, $param2) {
        // ...
    }
}

Redirects¶

Redirects can be specified in the config. Each of the keys within the redirects configuration are used as regular expressions to match on the path. If the regex matches the page will be redirected to the value here.

For example this will match the default favicon most browsers will look for and redirect to the icon in the assets/images directory

{
    "routing": {
        "redirects": {
            "^/favicon.ico$": "/assets/images/favicon.ico"
        }
    }
}

Additional functionalities¶

{{> header}}
{{> content}}
{{> footer}}

<a href="{{#site_url}}about{{/site_url}}">About Us</a>

<script src="{{#asset_url}}{{asset_path.javascript}}main.js{{/asset_url}}"></script>

<script src="http://cdn.example.com/assets/js/main.js?v=365424d18c0e435388a859592b8f5e3e"></script>

Exceptions¶

You should create your own exceptions for your application so that they can be handled appropriately. Cohesion specifies a UserSafeException. You should use an implemenation of a UserSafeException for any errors that are safe for the user to see. This includes things such as invalid input etc. The message of UserSafeExceptions are displayed back to the user.

Error Output¶

When an exception isn’t caught within the code it will generate an error page. Different exceptions may generate different error Views. A NotFoundException will show a 404 page, an UnauthorizedException will show a 403 page, and other exceptions will show a 500 ServerError page. If the environment is set to ‘production’ non UserSafeExceptions will just generate a vague error message. But if the environment isn’t ‘production’ then it will show the exception error message as well as the stack trace for easier debugging.

If there’s an uncaught exception in an AJAX call it will determine the expected format and return a valid response in that format. For JSON it will return something similar to:

{
    "success": false,
    "errors": [
        "Server Error"
    ]
}

Database Interaction¶

A MySQL database library is included to provide safe interaction with MySQL databases. The database class includes support for master/slave queries, transactions, named variables, as well as many other features.

The Database library isn’t an ORM, it requires you to write SQL statements. This allows for better performance optimization and forces you to think about what SQL will actually be executed.

The database library uses Mustache style named parameters.

For more information on the database library read the documentation at the start of the MySQL.php file.

Configuration Library¶

A config object class is provided for easy and extendible configuration. The config object will read one or more JSON formatted files and sections of the config can be given to classes to provide either business rule constants or library configurations. It is designed so that you can have a default config file with all the default configurations for your application then you can have a production config file that will overwrite only the variables within that config file such as database access etc.

You can access sub settings using dot notation.

Input Handler¶

An extremely simple input handler is provided. The input handler doesn’t do anything to prevent SQL injection or XSS as these are handled by the Database library and the Views respectively.

Licence¶

Cohesion is open source and released under the MIT licence.

Code¶

Feel free to checkout the code directly from GitHub.

The Cohesion Framework repository

The cohesion-framework is the basic starting point for creating new projects and includes the cohesion-core package.

The Cohesion Core Package repository

The cohesion-core contains the main classes used in the Cohesion framework.

Cohesion Docs repository

The repository containing this documentation.