Merge pull request #6 from DocnetUK/2.0

Merging 2.0 branch into master

Author: craig-mcmahon

.gitignore

@@ -11,3 +11,5 @@ Thumbs.db
 # IDE #
 #######
 .idea/
+
+build/

.travis.yml

@@ -0,0 +1,17 @@
+language: php
+
+php:
+  - 5.4
+  - 5.5
+  - 5.6
+
+before_script:
+  - composer self-update
+  - composer install --prefer-source --dev
+
+script:
+  - mkdir -p build/logs
+  - php vendor/bin/phpunit
+
+after_script:
+  - php vendor/bin/coveralls

LICENSE

@@ -186,7 +186,7 @@ Apache License
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2014 Docnet
+   Copyright 2015 Docnet
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,88 +1,65 @@
-# PHP JSON API Library #
+[![Build Status](https://api.travis-ci.org/DocnetUK/php-japi.svg?branch=2.0)](https://travis-ci.org/DocnetUK/php-japi)
+[![Coverage Status](https://coveralls.io/repos/DocnetUK/php-japi/badge.svg?branch=2.0)](https://coveralls.io/r/DocnetUK/php-japi)
 
-Simple library for building HTTP JSON APIs in PHP.
+# PHP JSON API Library #
 
-Sure, I know, there are loads of MVC frameworks out there - and a few very popular ones - that can do this for
-you and a lot more besides.
+Version 2 of our library for building HTTP JSON APIs in PHP.
 
-BUT, `php-japi` is designed to ONLY do HTTP JSON APIs, so it's small and fast.
+Some major changes in version 2
+- Adopt better code practices, allowing for Dependency Injection
+- Adopt our new "Single Responsibility Controller" approach
+- Decouple Router from JAPI container
+- Use PSR logging
+- Adopt PHP 5.4 minimum version
 
 As we expand our Service Orientated Architecture (SOA) at Docnet, we're using this more and more - so I hope it's useful
 to someone else ;)
 
 Intended to use HTTP status codes wherever possible for passing success/failure etc. back to the client.
 
-Data/payload is your responsibility!
+## Single Responsibility Controller ##
 
-## Hello, World! ##
+We've adopted a new (for us) take on routing and controller complexity in 2.0. As such, where previously, you might have 
+had multiple actions (methods) on the same class like this:
 
-Let's assume we want our API to respond on the following URL: `api.example.com/hello/world`
+- `BasketController::fetchDetailAction()`
+- `BasketController::addAction()`
+- `BasketController::removeAction()`
+- `BasketController::emptyAction()`
 
-So, here's the JAPI controller we'll need:
-
-```php
-<?php
-class Hello extends \Docnet\JAPI\Controller
-{
-    public function worldAction()
-    {
-        $this->setResponse(array(
-            'message' =>'Hello, World!'
-        ));
-    }
-}
-```
+Now this would be 4 name-spaced classes, like this
 
-See the examples folder for a working demo.
+- `Basket\FetchDetail`
+- `Basket\Add`
+- `Basket\Remove`
+- `Basket\Empty`
 
-## Getting Started ##
+This allows for 
+- Greater code modularity
+- Smaller classes
+- Much easier Dependency Injection via `__construct()` as each "action" is it's own class.
 
-### Install with Composer ###
+You can still share common code via extension/composition - whatever takes your fancy!
 
-Here's the require line for Composer users...
+JAPI will call the `dispatch()` method on your controller.
 
-`"docnet/php-japi": "v1.1.1"`
+### SOLID Routing ###
 
-...or just download and use the src folder.
+The bundled router will accept any depth of controller namespace, like this
 
-### Entry Point (index.php) ###
+- `/one` => `One`
+- `/one/two` => `One\Two`
+- `/one/two/three` => `One\Two\Three`
 
-Assuming:
-
-- You've got Apache/whatever set up to route all requests to this file
-- An auto-loader is present (like the Composer example here) or you've included all files necessary
-- Your controllers are not name spaced and you're happy with our default configuration
-
-then something like this is all the code you need
+When you construct the Router, you can give it a "root" namespace, like this:
 
 ```php
-<?php
-require_once('vendor/autoload.php');
-$api = new \Docnet\JAPI();
-$api->run();
+$router = new \Docnet\JAPI\SolidRouter('\\Docnet\\App\\Controller\\');
 ```
 
-See the examples folder for a working demo (api.php).
-
-## Routing ##
-
-The standard routing is quite strict, and (at the time ot writing) expects a controller + action pair for all requests.
-
-e.g. `api.example.com/hello/world`
-
-URLs without a 2-part controller + action pair will result in a 404, such as
+Which results in this routing:
 
-- `api.example.com`
-- `api.example.com/`
-- `api.example.com/controller`
-
-We do conversion to `StudlyCaps` classes and `camelCase` methods, splitting on hyphens and suffix 'Action' for the
-method. e.g.
-
-- `api.example.com/hello/world` becomes `Hello::worldAction()`
-- `api.example.com/hello-world/long-name` becomes `HelloWorld::longNameAction()`
-
-I seem to recall this is similar to ZF1.
+- `/one/two` => `\Docnet\App\Controller\One\Two`
 
 ### Static Routes ###
 
@@ -92,39 +69,51 @@ and so make calls very slightly faster.
 Add a single custom route
 
 ```php
-<?php
-$api = new \Docnet\JAPI();
-$api->getRouter()->addRoute('/goodbye', 'Hello', 'worldAction');
-$api->run();
+$router = new \Docnet\JAPI\SolidRouter();
+$router->addRoute('/hello', '\\Some\\Controller');
 ```
 
 Or set a load of them
 
 ```php
-<?php
-$api = new \Docnet\JAPI();
-$api->getRouter()->setRoutes(array(
-    '/goodbye'  => array('Hello', 'worldAction'),
-    '/testing'  => array('SomeController', 'testAction'),
-));
-$api->run();
+$router = new \Docnet\JAPI\SolidRouter();
+$router->setRoutes([
+    '/hello' => '\\Some\\Controller',
+    '/world' => '\\Other\\Controller'
+]);
 ```
 
-### Custom Router ###
+## Installation ##
+
+Here's the require line for Composer users (during 2-series development)...
 
-If you want to write your own Router class? no problem!
+`"docnet/php-japi": "2.0.*@dev"`
 
-Perhaps you want to route based on HTTP request methods (GET/POST/PUT/DELETE).
+...or just download and use the src folder.
+
+## Bootstrapping ##
 
-There's a Router interface and you can follow and you can change the router through the JAPI object like this:
+Assuming...
+
+- You've got Apache/whatever set up to route all requests to this file
+- An auto-loader is present (like the Composer example here) or you've included all files necessary
+
+...then something like this is all the code you need in your `index.php`
 
 ```php
-<?php
-$api = new \Docnet\JAPI();
-$api->setRouter(new MyAwesomeRouter());
-$api->run();
+(new \Docnet\JAPI())->bootstrap(function(){
+
+    $obj_router = new \Docnet\JAPI\SolidRouter();
+    $obj_router->route();
+
+    $str_controller = $obj_router->getController();
+    return new $str_controller();
+
+});
 ```
 
+See the examples folder for a working demo (api.php).
+
 ## Coding Standards ##
 
-Desired adherence to [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md).
+Desired adherence to [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md). Uses [PSR-3](https://github.com/php-fig/log) logging.

composer.json

@@ -1,17 +1,29 @@
 {
     "name": "docnet/php-japi",
     "type": "library",
-    "description": "Simple framework for building HTTP JSON APIs in PHP",
+    "description": "Simple framework for building HTTP JSON APIs in PHP. 2.",
+    "authors": [
+        {
+            "name": "Tom Walder",
+            "email": "[email protected]"
+        }
+    ],
     "keywords": ["docnet", "json", "http", "api"],
     "homepage": "https://github.com/DocnetUK/php-japi",
     "license": "Apache-2.0",
     "require": {
-        "php": ">=5.3.0"
+        "php": ">=5.4.0",
+        "psr/log": "~1.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "~4.0",
+        "satooshi/php-coveralls": "dev-master"
     },
     "autoload": {
         "classmap": [
             "src/"
-        ]
+        ],
+        "psr-4": {"Docnet\\": "src/Docnet/"}
     },
     "include-path": ["src/"]
 }