README.md

slim-angular

slim-angular is a complete skeleton app based on Slim Framework and AngularJS. It is designed to start a new project with a clean and efficient code base using :

• Slim Framework for the server-side scripting
• AngularJS for the frontend's interactions
• Bootstrap to get a responsive web design
• Less as a CSS pre-processor
• Composer to manage server-side dependencies
• NPM to manage frontend dependencies
• Gulp to generated minified JS and CSS resources
• Phing to build the project

Dependencies

Your development environment must have the following to install slim-angular :

• PHP 5.6+ or 7
• Composer
• Docker or npm

All these packages have repositories or easy-to-use installers, so please refer to their documentations to know how to get it. If you have Docker installed, you don't have to install nodejs and npm.

Installation

Once you have installed properly the dependencies above on your machine, just use composer to create a new project

composer create-project debril/slim-angular [my-app-name]

Replace [my-app-name] with the desired directory name for your new application. If Composer asks you about removing VCS directories, answer 'Yes' as you'll want to work in your own repository. Once the PHP packages installation is over, you'll need to install npm packages.

Skip this if you want to use Docker

If you want to run your application through Docker, you don't need to do this by yourself as Docker will do it for you. Otherwise, ask npm to install dependencies :

cd [my-app-name]
npm install

Running

The application will be available at : http://0.0.0.0:8080

With Docker

docker-compose up --build

And you're set. Docker will take charge of running Nginx, PHP and Gulp. No need to worry about launching gulp watch.

With Composer and Gulp

composer start

And in another terminal :

composer gulp

Architecture

slim-angular is designed to create efficient websites based on PHP, AngularJS and Bootstrap. The goal of slim-angular is to share responsibilities between the server-side and the frontend :

• the server-side is responsible for the business logic, the security and the application's initialization.
• the frontend is responsible for the user interface and the layout.

Which means that at the first hit the server will initialize a session, generate a lightweight HTML page and send it to the browser. Then, AngularJS will handle the user's interactions and communicate with the server when needed.

Out of the box, slim-angular is perfect for single page applications as it handles routes using angular-route. You may prefer to have routing on the server-side and if so, just use Slim's routing instead.

Server-Side

The backend is built with Slim, a really fast and easy to learn framework. Its purpose is to "receive an HTTP request, invoke an appropriate callback routine, and return an HTTP response".

public/

It has to be defined as the document root of your website. It contains index.php which is the front controller of your application.

php/

This folder contains all the server-side logic and configuration. app contains all your application's classes and templates all the templates handled by the server.

Frontend

css/

Contains styles written according to the Less pre-processor syntax. The files contained in css/ are compiled and then minified into the public/minified/styles.min.css file.

js/

Contains the frontend application built with AngularJS. The files contained in js/ are also minified, this time in the public/minified/app.min.js file.

Working with slim-angular

Working in a project created wit slim-angular is easy. All the server-side logic is in the php/ folder, styles are in css/ and javascripts in js/. There's two subtilities :

• you need to run Gulp to build styles and javascripts into the public/minified folder.
• HTTP requests must be secured using the tokenizer

Gulp

Gulp is pre-configured in the project, you just need to start it :

composer gulp

If Gulp is installed system-wide, you may prefer to start it without Composer :

gulp watch

Now, Gulp will watch css/ and js/ in order to compile and/or minify static resources in the public/minified/ folder.

Tokenizer

The server-side relies on slim/csrf to protect your application against CSRF. So everytime you call the server, you'll need to "tokenize" your request by adding the security token in your arguments. And there's an Angular service for that, which you can inject and use like this :

// we add the tokenizer service in our controller's dependencies
HelloController.$inject = ['$http', 'tokenizer'];

// inject tokenizer in the params
function HelloController($http, tokenizer) {
    var vm = this;

    vm.hello = function (string) {
        vm.error = '';
        $http.post('/hello',
            // tokenize params
            tokenizer.tokenize({
                'string': string
            })
        )
        .then(function (response) {
            vm.result = response.data.result;
        }, function (error) {
            vm.error = error;
        });
    };
}

Build and deployment

slim-angular includes a Phing XML script to build your application in an easy-to-deploy archive. The main steps are :

• copy php/and public/ in a packaging folder called dist/package/
• in the packaging folder : install dependencies with Composer in production mode (no development dependencies and with an optimized autoloader)
• rename public/minified/ to prevent cache issues
• create a Zip archive at the root of your application

The archive contains only the needed files for your application to work in a production environnment. Start the build with the following command :

composer build

Documentation

• Slim's first app Tutorial
• Angular's Tutorial
• CodeSchool's excellent course on AngularJS

Have fun with slim-angular

Feel free to open an issue if you have any question or suggestion about slim-angular