Merge branch 'release/0.1.0'

CHANGELOG.md

@@ -1,3 +1,6 @@
-# Changelog
+# Change log
 All Notable changes to `allay` will be documented in this file
 
+## 0.1.0 (released 2015-10-11)
+- Core concept realised.
+- Added tests.

README.md

@@ -56,13 +56,28 @@ This can be done by adding the following code to the **/config/app.php**.
      */
     ...,
 
-    ByCedric\Allay\AllayServiceProvider::class,
+    ByCedric\Allay\Providers\LaravelServiceProvider::class,
 
 ]
 ```
 
 > Please add the service provider to the **bottom** of the providers list. If you don't, routes cannot be overwritten.
 
+### [Lumen](http://lumen.laravel.com/)
+You can also get `Allay` working on Lumen, a light-weight and blazing fast Laravel version.
+This can be done by adding the following code to the **/bootstrap/app.php**.
+
+```php
+/*
+|--------------------------------------------------------------------------
+| Register Service Providers
+|--------------------------------------------------------------------------
+...
+*/
+
+$app->register(ByCedric\Allay\Providers\LumenServiceProvider::class);
+```
+
 ## Usage
 To get started with `Allay` take a look at the [wiki](../../wiki) pages.
 

composer.json

@@ -21,12 +21,15 @@
     "require": {
         "php": ">=5.5.9",
         "illuminate/contracts": "5.1.*",
+        "illuminate/database": "5.1.*",
         "illuminate/http": "5.1.*",
         "illuminate/support": "5.1.*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^4.8.9",
+        "illuminate/routing": "5.1.*",
+        "laravel/lumen-framework": "5.1.*",
         "mockery/mockery": "^0.9.4",
+        "phpunit/phpunit": "^4.8.9",
         "satooshi/php-coveralls": "^0.6.1"
     },
     "autoload": {

src/Config/LaravelConfig.php

@@ -0,0 +1,135 @@
+<?php
+
+/*
+ * This file is part of the Allay package.
+ *
+ * (c) Cedric van Putten <me@bycedric.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Resources
+    |--------------------------------------------------------------------------
+    |
+    | A restful API consists of many data object, also known as resources or
+    | models. To allow a single model to be accessible through the API you
+    | have to "white list" it with a certain name. The name will be the link to
+    | the URL's and the model. All listed models will be registered
+    | to the provided resource manager.
+    |
+    | The example below allows a model "\App\Project" to be accessible through
+    | "https://api.myawesomeproject.com/v1/projects".
+    |
+    | Note, it's recommended to NOT include the "User" model since it's very
+    | security sensitive. Use default Laravel handling or write custom
+    | controllers instead of using the model directly.
+    |
+    */
+
+    'resources' => [
+        'manager'  => ByCedric\Allay\Resource\Manager::class,
+        'resolver' => ByCedric\Allay\Resource\Resolvers\LaravelResolver::class,
+        'models'   => [
+            // 'projects' => App\Project::class
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Routes
+    |--------------------------------------------------------------------------
+    |
+    | An API contains routes that defines the actions a resource can receive.
+    | For example; some people wants to `create` projects, others would love to
+    | `update` the project name. So basically, all those simple actions are
+    | executed by a controller. Here you can define the controller it SHOULD
+    | use. As you might have noticed, this is only one controller. Think of it as
+    | an `one size fits all` controller. It's quite repetitive to define all
+    | actions, for every resource model again. Therefore the models are being
+    | injected using the resource manager.
+    |
+    | And last, but not least, you can specify all settings you would like to
+    | pass to the route's group. Like the middleware it SHOULD use, and/or a
+    | security it SHOULD add. Customize it, to fit your project.
+    |
+    */
+
+    'routes' => [
+        'controller' => ByCedric\Allay\Http\Controllers\LaravelController::class,
+        'settings'   => [
+            'prefix'     => 'v1',
+            'middleware' => [
+                ByCedric\Allay\Http\Middleware\TransformResponseToArray::class,
+                ByCedric\Allay\Http\Middleware\UpdateStatusCodeByRequestMethod::class,
+                ByCedric\Allay\Http\Middleware\CatchExceptionsWithManager::class,
+            ],
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Transformer
+    |--------------------------------------------------------------------------
+    |
+    | Every API response is formatted using a pre-defined format. This can be a
+    | json-api format, or hal. Even plain array is a format that you SHOULD be
+    | able to use. Therefore you can define a transformer that will transform
+    | any returned value, from the controllers, to a plain response array.
+    |
+    */
+
+    'transformer' => ByCedric\Allay\Transformers\ArrayTransformer::class,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Exceptions
+    |--------------------------------------------------------------------------
+    |
+    | Inside Allay we use exceptions to stop and respond with a certain message.
+    | Every exception has to be rendered to a valid response, therefore we make
+    | use of a general exception manager. You can add your own handlers to
+    | extend the manager, or just totally replace the manager.
+    |
+    | Note, this does not interact with the default Laravel exception handler
+    | since these handlers SHOULD only catch exceptions, for respond purposes
+    | For example, this SHOULD only catch the ModelNotFoundException or
+    | ValidationException. Those aren't "real" exceptions, like
+    | InvalidArgumentException. The "real" exceptions MUST not be caught by
+    | this manager, and MUST be handled by Laravel's exception handler.
+    |
+    */
+
+    'exceptions' => [
+        'manager'  => ByCedric\Allay\Exceptions\Manager::class,
+        'handlers' => [
+            ByCedric\Allay\Exceptions\Handlers\ResourceHandler::class,
+            ByCedric\Allay\Exceptions\Handlers\ModelNotFoundHandler::class,
+            ByCedric\Allay\Exceptions\Handlers\ValidationHandler::class,
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Statuses
+    |--------------------------------------------------------------------------
+    |
+    | Each request SHOULD respond with a applicable http status code. Here you
+    | can define each http request, with their default http status code. This
+    | will then be applied when successfully executing a resource action.
+    |
+    */
+
+    'statuses' => [
+        Illuminate\Http\Request::METHOD_GET    => 200,
+        Illuminate\Http\Request::METHOD_POST   => 201,
+        Illuminate\Http\Request::METHOD_PUT    => 204,
+        Illuminate\Http\Request::METHOD_PATCH  => 204,
+        Illuminate\Http\Request::METHOD_DELETE => 204,
+    ],
+
+];

src/Config/LumenConfig.php

@@ -0,0 +1,135 @@
+<?php
+
+/*
+ * This file is part of the Allay package.
+ *
+ * (c) Cedric van Putten <me@bycedric.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Resources
+    |--------------------------------------------------------------------------
+    |
+    | A restful API consists of many data object, also known as resources or
+    | models. To allow a single model to be accessible through the API you
+    | have to "white list" it with a certain name. The name will be the link to
+    | the URL's and the model. All listed models will be registered
+    | to the provided resource manager.
+    |
+    | The example below allows a model "\App\Project" to be accessible through
+    | "https://api.myawesomeproject.com/v1/projects".
+    |
+    | Note, it's recommended to NOT include the "User" model since it's very
+    | security sensitive. Use default Laravel handling or write custom
+    | controllers instead of using the model directly.
+    |
+    */
+
+    'resources' => [
+        'manager'  => ByCedric\Allay\Resource\Manager::class,
+        'resolver' => ByCedric\Allay\Resource\Resolvers\LumenResolver::class,
+        'models'   => [
+            // 'projects' => App\Project::class
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Routes
+    |--------------------------------------------------------------------------
+    |
+    | An API contains routes that defines the actions a resource can receive.
+    | For example; some people wants to `create` projects, others would love to
+    | `update` the project name. So basically, all those simple actions are
+    | executed by a controller. Here you can define the controller it SHOULD
+    | use. As you might have noticed, this is only one controller. Think of it as
+    | an `one size fits all` controller. It's quite repetitive to define all
+    | actions, for every resource model again. Therefore the models are being
+    | injected using the resource manager.
+    |
+    | And last, but not least, you can specify all settings you would like to
+    | pass to the route's group. Like the middleware it SHOULD use, and/or a
+    | security it SHOULD add. Customize it, to fit your project.
+    |
+    */
+
+    'routes' => [
+        'controller' => ByCedric\Allay\Http\Controllers\LumenController::class,
+        'settings'   => [
+            'prefix'     => 'v1',
+            'middleware' => [
+                ByCedric\Allay\Http\Middleware\TransformResponseToArray::class,
+                ByCedric\Allay\Http\Middleware\UpdateStatusCodeByRequestMethod::class,
+                ByCedric\Allay\Http\Middleware\CatchExceptionsWithManager::class,
+            ],
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Transformer
+    |--------------------------------------------------------------------------
+    |
+    | Every API response is formatted using a pre-defined format. This can be a
+    | json-api format, or hal. Even plain array is a format that you SHOULD be
+    | able to use. Therefore you can define a transformer that will transform
+    | any returned value, from the controllers, to a plain response array.
+    |
+    */
+
+    'transformer' => ByCedric\Allay\Transformers\ArrayTransformer::class,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Exceptions
+    |--------------------------------------------------------------------------
+    |
+    | Inside Allay we use exceptions to stop and respond with a certain message.
+    | Every exception has to be rendered to a valid response, therefore we make
+    | use of a general exception manager. You can add your own handlers to
+    | extend the manager, or just totally replace the manager.
+    |
+    | Note, this does not interact with the default Laravel exception handler
+    | since these handlers SHOULD only catch exceptions, for respond purposes
+    | For example, this SHOULD only catch the ModelNotFoundException or
+    | ValidationException. Those aren't "real" exceptions, like
+    | InvalidArgumentException. The "real" exceptions MUST not be caught by
+    | this manager, and MUST be handled by Laravel's exception handler.
+    |
+    */
+
+    'exceptions' => [
+        'manager'  => ByCedric\Allay\Exceptions\Manager::class,
+        'handlers' => [
+            ByCedric\Allay\Exceptions\Handlers\ResourceHandler::class,
+            ByCedric\Allay\Exceptions\Handlers\ModelNotFoundHandler::class,
+            ByCedric\Allay\Exceptions\Handlers\ValidationHandler::class,
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Statuses
+    |--------------------------------------------------------------------------
+    |
+    | Each request SHOULD respond with a applicable http status code. Here you
+    | can define each http request, with their default http status code. This
+    | will then be applied when successfully executing a resource action.
+    |
+    */
+
+    'statuses' => [
+        Illuminate\Http\Request::METHOD_GET    => 200,
+        Illuminate\Http\Request::METHOD_POST   => 201,
+        Illuminate\Http\Request::METHOD_PUT    => 204,
+        Illuminate\Http\Request::METHOD_PATCH  => 204,
+        Illuminate\Http\Request::METHOD_DELETE => 204,
+    ],
+
+];

src/Contracts/Exceptions/Handler.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the Allay package.
+ *
+ * (c) Cedric van Putten <me@bycedric.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ByCedric\Allay\Contracts\Exceptions;
+
+interface Handler
+{
+    /**
+     * Determine if the handler is capable of handling the given exception.
+     *
+     * @param  \Exception $error
+     * @return bool
+     */
+    public function capable(\Exception $error);
+
+    /**
+     * Handle the given exception to return a valid response.
+     *
+     * @param  \Exception                $error
+     * @return \Illuminate\Http\Response
+     */
+    public function handle(\Exception $error);
+}

src/Contracts/Exceptions/Manager.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * This file is part of the Allay package.
+ *
+ * (c) Cedric van Putten <me@bycedric.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ByCedric\Allay\Contracts\Exceptions;
+
+interface Manager
+{
+    /**
+     * Register a new handler, that is capable of converting exceptions to responses.
+     *
+     * @param  \ByCedric\Allay\Contracts\Exceptions\Handler $handler
+     * @return void
+     */
+    public function register(Handler $handler);
+
+    /**
+     * Determine if the given exception manager is capable of handling the exception.
+     *
+     * @param  \Exception $error
+     * @return bool
+     */
+    public function capable(\Exception $error);
+
+    /**
+     * Handle the given exception to return a valid response.
+     *
+     * @param  \Exception                $error
+     * @return \Illuminate\Http\Response
+     */
+    public function handle(\Exception $error);
+}