Merge pull request #184 from zf-fr/refactor

[WIP] ZfrRest NEXT

.travis.yml

@@ -1,7 +1,6 @@
 language: php
 
 php:
-  - 5.4
   - 5.5
   - 5.6
 

CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## 0.4.0
+
+* Complete rewrite of ZfrRest. All the concepts have been changed in favour of an explicit module, please read the
+new docs.
+* PHP dependency has been raised to PHP 5.5
+
 ## 0.3.4
 
 * ZfrRest now supports coalesce filtering for "hasMany" or "findMany" requests type through the new, optional

Module.php

@@ -5,4 +5,4 @@
  * It allows usage of this module even without composer.
  * The original Module.php is in 'src/ZfrRest' in order to respect PSR-0
  */
-require_once __DIR__ . '/src/ZfrRest/Module.php';
+require_once __DIR__ . '/src/Module.php';

README.md

@@ -8,32 +8,38 @@ ZfrRest
 [![Total Downloads](https://poser.pugx.org/zfr/zfr-rest/downloads.png)](https://packagist.org/packages/zfr/zfr-rest)
 [![Dependency Status](https://www.versioneye.com/package/php--zfr--zfr-rest/badge.png)](https://www.versioneye.com/package/php--zfr--zfr-rest)
 
-> If you are an Ember Data user, I have created a specific renderer that output JSON compliant payload. I didn't
-released it yet as it's not really clean, but if you're interested, please contact me :).
-
 ## Installation
 
 Install the module by typing (or add it to your `composer.json` file):
 
-`php composer.phar require zfr/zfr-rest:0.3.*`
+`php composer.phar require zfr/zfr-rest:0.4.*`
 
 Then, add the keys "ZfrRest" to your modules list in `application.config.php` file, and copy-paste the file
 `zfr_rest.global.php.dist` into your `autoload` folder (don't forget to remove the .dist extension at the end!).
 
+## ZfrRest 0.4+ vs ZfrRest 0.3
+
+Starting from version 0.4, ZfrRest has been completely rewritten from scratch. Previously, ZfrRest used to do a lot
+of things automatically for you, from rendering, to automatic routing and creation of routes. However, while nice for
+very simple use cases, it was actually very hard to extend, introduced a lot of performance problems and was quite
+unflexible.
+
+Now, ZfrRest is more a "small REST utility". It provides a simple way to handle HTTP exceptions, a lightweight
+controller that can both handle action and HTTP verbs, and a view layer adapted for resource rendering (that can
+optionally use versioning to render a resource differently based on the version). You can consider ZfrRest as a
+module that you can use if you want to create a REST API, instead of a full-blown module like Apigility or previous
+ZfrRest versions.
+
+Additionally, dependency to Doctrine has been completely remove and can be used by anyone.
+
 ## ZfrRest vs Apigility
 
 [Apigility](http://www.apigility.org) is a Zend Framework 2 API builder that also aims to simplify the creation of
 REST APIs.
 
-ZfrRest and Apigility philosophies are completely different. ZfrRest is Doctrine only, and focuses only on a very
-small subset on your REST API: it provides routing, validation and hydration.
-
-On the other hand, Apigility comes with a graphical user interface, versioning support, authorization, authentication
-HAL, content negotiation... ZfrRest will never provide **all** those functionalities, so if you need them, just go
-with Apigility.
-
-ZfrRest's scope is much more limited (although I'd really like to add support for versioning and links), but I
-really think it's a nice product too. So give it a try to both products, and choose the one you prefer!
+Starting from ZfrRest 0.4+, there is actually nothing in common between those two libraries. Apigility is a full-blown
+module that does a lot of things, from headers negotiation, automatic rendering, link generation, a code-generator...
+On the other hand, ZfrRest is the bare metal, and leave most of the responsability and power to you.
 
 ## Documentation
 

composer.json

@@ -25,11 +25,7 @@
     ],
     "minimum-stability": "beta",
     "require": {
-        "php": ">=5.4",
-        "jms/metadata": "~1.5",
-        "doctrine/common": "~2.4",
-        "doctrine/doctrine-module": "~0.8",
-        "zendframework/zend-cache": "~2.2",
+        "php": ">=5.5",
         "zendframework/zend-http": "~2.2",
         "zendframework/zend-inputfilter": "~2.2",
         "zendframework/zend-mvc": "~2.2",
@@ -41,14 +37,17 @@
     },
     "require-dev": {
         "zendframework/zendframework": "~2.2",
-        "doctrine/doctrine-orm-module": "~0.8",
-        "phpunit/phpunit": "~3.7",
-        "squizlabs/php_codesniffer": "1.4.*",
-        "satooshi/php-coveralls": "~0.6"
+        "phpunit/phpunit": "~4.1",
+        "squizlabs/php_codesniffer": "1.4.*"
     },
     "autoload": {
-        "psr-0": {
+        "psr-4": {
             "ZfrRest\\": "src/"
         }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "ZfrRestTest\\": "tests/"
+        }
     }
 }

config/module.config.php

@@ -16,56 +16,65 @@
  * and is licensed under the MIT license.
  */
 
+use ZfrRest\Factory\HttpExceptionListenerFactory;
+use ZfrRest\Factory\HydrateObjectPluginFactory;
+use ZfrRest\Factory\ModuleOptionsFactory;
+use ZfrRest\Factory\ResourceRendererFactory;
+use ZfrRest\Factory\ResourceStrategyFactory;
+use ZfrRest\Factory\ValidateIncomingDataPluginFactory;
+use ZfrRest\Mvc\Controller\Plugin\HydrateObject;
+use ZfrRest\Mvc\Controller\Plugin\ValidateIncomingData;
+use ZfrRest\Mvc\HttpExceptionListener;
+use ZfrRest\Mvc\ResourceResponseListener;
+use ZfrRest\Options\ModuleOptions;
+use ZfrRest\View\Helper\RenderPaginator;
+use ZfrRest\View\Helper\RenderResource;
+use ZfrRest\View\Renderer\ResourceRenderer;
+use ZfrRest\View\Strategy\ResourceStrategy;
+
 return [
     'service_manager' => [
-        'factories' => [
-            /* Factories that do not map to a class */
-            'ZfrRest\Cache'                                                   => 'ZfrRest\Factory\CacheFactory',
-            'ZfrRest\View\Renderer\ResourceRenderer'                          => 'ZfrRest\Factory\DefaultResourceRendererFactory',
-
-            /* Factories that map to a class */
-            'ZfrRest\Mvc\HttpExceptionListener'                               => 'ZfrRest\Factory\HttpExceptionListenerFactory',
-            'ZfrRest\Mvc\Controller\MethodHandler\MethodHandlerPluginManager' => 'ZfrRest\Factory\MethodHandlerPluginManagerFactory',
-            'ZfrRest\Options\ModuleOptions'                                   => 'ZfrRest\Factory\ModuleOptionsFactory',
-            'ZfrRest\Resource\Metadata\ResourceMetadataFactory'               => 'ZfrRest\Factory\ResourceMetadataFactoryFactory',
-            'ZfrRest\Resource\ResourcePluginManager'                          => 'ZfrRest\Factory\ResourcePluginManagerFactory',
-            'ZfrRest\Router\Http\Matcher\AssociationSubPathMatcher'           => 'ZfrRest\Factory\AssociationSubPathMatcherFactory',
-            'ZfrRest\Router\Http\Matcher\BaseSubPathMatcher'                  => 'ZfrRest\Factory\BaseSubPathMatcherFactory',
-            'ZfrRest\View\Strategy\ResourceStrategy'                          => 'ZfrRest\Factory\ResourceStrategyFactory'
+        'invokables' => [
+            ResourceResponseListener::class => ResourceResponseListener::class
         ],
 
-        'invokables' => [
-            'ZfrRest\Mvc\HttpMethodOverrideListener'               => 'ZfrRest\Mvc\HttpMethodOverrideListener',
-            'ZfrRest\Router\Http\Matcher\CollectionSubPathMatcher' => 'ZfrRest\Router\Http\Matcher\CollectionSubPathMatcher'
+        'factories' => [
+            HttpExceptionListener::class => HttpExceptionListenerFactory::class,
+            ModuleOptions::class         => ModuleOptionsFactory::class,
+            ResourceRenderer::class      => ResourceRendererFactory::class,
+            ResourceStrategy::class      => ResourceStrategyFactory::class
         ]
     ],
 
-    'route_manager' => [
+    'controller_plugins' => [
         'factories' => [
-            'ZfrRest\Router\Http\ResourceGraphRoute' => 'ZfrRest\Factory\ResourceGraphRouteFactory'
+            ValidateIncomingData::class => ValidateIncomingDataPluginFactory::class,
+            HydrateObject::class          => HydrateObjectPluginFactory::class
         ],
 
         'aliases' => [
-            'resourceGraphRoute' => 'ZfrRest\Router\Http\ResourceGraphRoute'
-        ],
+            'validateIncomingData' => ValidateIncomingData::class,
+            'hydrateObject'        => HydrateObject::class
+        ]
     ],
 
-    'controller_plugins' => [
+    'view_helpers' => [
         'invokables' => [
-            'paginatorWrapper' => 'ZfrRest\Mvc\Controller\Plugin\PaginatorWrapper',
-            'resourceModel'    => 'ZfrRest\Mvc\Controller\Plugin\ResourceModel'
+            RenderPaginator::class => RenderPaginator::class,
+            RenderResource::class  => RenderResource::class
+        ],
+
+        'aliases' => [
+            'renderPaginator' => RenderPaginator::class,
+            'renderResource'  => RenderResource::class
         ]
     ],
 
     'view_manager' => [
         'strategies' => [
-            'ZfrRest\View\Strategy\ResourceStrategy',
-            'ViewJsonStrategy'
+            ResourceStrategy::class
         ]
     ],
 
-    'zfr_rest' => [
-        // Plugin managers configurations
-        'method_handlers' => []
-    ]
+    'zfr_rest' => []
 ];

config/zfr_rest.global.php.dist

@@ -7,32 +7,6 @@
 
 return [
     'zfr_rest' => [
-        /**
-         * Service name of the object manager instance. It is retrieved from the service manager. For instance, if you
-         * are using Doctrine ORM Module, this value may be "doctrine.entitymanager.orm_default"
-         */
-        // 'object_manager' => 'doctrine.entitymanager.orm_default',
-
-        /**
-         * Specify the resource metadata drivers. This is used by ZfrRest to extract your mapping. Currently one
-         * method is supported: annotations.
-         *
-         * To add an annotation driver:
-         *
-         *      'drivers' => [
-         *          [
-         *              'class' => 'ZfrRest\Resource\Metadata\Driver\AnnotationDriver'
-         *          ]
-         *      ]
-         */
-        // 'drivers' => [],
-
-        /**
-         * Either a service name that returns a Zend\Cache\StorageInterface OR Doctrine\Common\Cache\Cache OR
-         * a Zend\Cache\StorageInterface compliant config.
-         */
-        // 'cache' => ['adapter' => 'apc'],
-
         /**
          * Allow to map a custom exception to a HTTP exception. For instance:
          *
@@ -47,23 +21,11 @@ return [
          * a header "X-HTTP-Method-Override". This header allows to change the HTTP verb. This is useful in
          * some contexts (for instance, some companies' proxies only allow GET and POST methods)
          */
-        // 'register_http_method_override_listener' => false,
-
-        /**
-         * If enabled, it allows the REST router to filter a collection list by identifiers. For instance, considering
-         * a query /customers?$ids[]=1&$ids[]=2, it will be able to return a filtered collections
-         */
-        // 'enable_coalesce_filtering' => false,
-
-        /**
-         * The coalesce filtering query key
-         */
-        // 'coalesce_filtering_query_key' => '$ids',
-
-        /**
-         * Service manager configuration to configure the method handlers. A method handler handles a HTTP request
-         * like GET, PUT...
-         */
-        // 'method_handlers' => []
+        // 'register_http_method_override_listener' => false
     ]
 ];
+
+### Navigation
+
+* Continue to [**Controllers**](/docs/02. Controllers.md)
+* Back to [the Index](/docs/README.md)

docs/01. Installation and configuration.md

@@ -0,0 +1,16 @@
+# Installation and Configuration
+
+Starting from ZfrRest 0.4.*, ZfrRest has very few options. Once you have retrieved it from Composer, all the
+available options can be configured by copying the `zfr_rest.global.php.dist` file into your `config/autoload` folder.
+
+Here are the possible options:
+
+* `exception_map`: allows to map an exception to a ZfrRest exception. It will automatically be catched by the listener
+and create an appropriate JSON response. You can learn more about error handling [in this section](/docs/01. Installation and configuration.md).
+* `register_http_method_override_listener`: in some companies, or if you are using standard HTML forms, you can be
+limited in the choice of HTTP verbs (most of the time, only POST and GET). By enabling this option, you can now send
+a header `X-HTTP-Method-Override` whose value is the HTTP method. ZfrRest will automatically replace the verb of the
+request.
+
+* Continue to [**Controllers**](/docs/02. Controllers.md)
+* Back to [the Index](/docs/README.md)