New Intermesh frameworks

New technologies for the web are rising rapidly. As an application development company it's important to keep up with new technologies. I've explored and finally started to develop two frameworks that we will use for new applications.

On the server I want to create an API that's just communicating with clients through JSON requests. The server and client should be completely decoupled in my opinion. The server runs with the Intermesh PHP framework that features:

• Api documentation with ApiGen
• Model View Controller design pattern
• ActiveRecord models for database ORM
• Simple routing of HTTP requests to controller action methods
• User authentication and role based permissions
• Unit testing with phpunit
• Composer support

On the client side I've developed an AngularJS framework for building an Angular client. The framework features:

• API documentation with ngdocs
• AngularJS uses the Model View Controller design pattern
• bower support
• services, directives and filters to communicate with the Intermesh PHP server API.
• grunt to build the application, documentation and maintain index.html so it's not needed to add new scripts all the time.

Notes about the tools used

Composer

Composer is an essential tool. It takes care of:

1. Installing and maintaining 3rd party libraries
2. Autoloading PHP classes using the PSR-04 standard

There's no need to write your own autoloading script any more. Just install packages and you're good to go just by using the class names.

ApiGen

Documentation was always something that was pushed to a later date. So it's important to get this right at the start of a new project. I've tried various documentation generators PHPDoc, SAMI and ApiGen. The first two we're disappointing in the result. PHPDoc is more active and has more feature but the out of the box templates are just not good enough. ApiGen was the only one that produced a very usable result out of the box!

PHPUnit

I think the only and best tool for unit testing. Works flawlessly out of the box.

Bower

An essential tool that is similar to Composer but for javascript packages.

Grunt

Grunt is a javascript task runner. I used it for a couple of things. When I started with the AngularJS project I wanted to keep each component in a separate Javascript file to keep the code organized. Each time a new file was created I had to add it to the index.html file. As I'm a lazy programmer I don't like to do such annoying tasks :) Grunt can do that for me using the "fileblocks" module. Each time I add a file it's automatically inserted. Apart from that you also don't want to deploy your application like that. To improve performance grunt can concatenate and minify the Javascript, CSS and HTML for you.

ngdocs

Getting AngularJS documentation was tricky to setup. First of all there is some package confusion. I've tried ngdoc, ngdocs and dgeni. I couldn't get ngdoc to work at all so I moved on to ngdocs which worked well out of the box. I noticed the dgeni project is more active and used by AngularJS but it doesn't seem to be ready for community use yet. Perhaps it will grow out to be better than ngdocs.
The hardest thing to get going were the live inline examples. I used grunt to build a special script that includes all the Intermesh angular modules. With the "scripts" option for the ngdocs grunt task I was able to add those scripts to the docs so they started to work. See my Gruntfile.js for an example.
Here's an example of the ngdoc syntax for live examples:
https://github.com/Intermesh/intermesh-angular-framework/blob/master/src/intermesh/core/translate-provider.js

Getting started

To get started with development you will need to install:

• git
• Composer
• bower
• grunt

I use Ubuntu to develop on. If you want to install on Ubuntu you can install git and the Node Package Manager npm with this command:

$ sudo apt-get install git npm 

I had to work around some bug with (see https://github.com/joyent/node/issues/3911):

$ sudo ln -s /usr/bin/nodejs /usr/bin/node 

Install grunt, bower with the node package manager (use -g for global install):

$ sudo npm install -g grunt-cli bower

Install composer:

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

Then install the server and client examples. Installation instructions are on the project pages on Github:

• intermesh-php-example
• intermesh-angular-example