Added Transformer and Transformation feature. Included unit tests for Transformation classes. Updated CHANGELOG and README to reflect this change. Fixes #2

Author: Alistair Kearney

CHANGELOG.md

@@ -2,6 +2,16 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+#### Added
+- Transformer and Transformation classes.
+- Added APIFrameworkJSONRendererAppendTransformations delegate
+- Added phpunit to composer require-dev
+- Added unit tests for Transformation code
+
+#### Removed
+- Symphony PDO is not longer a Composer requirement as it is not used
+
 ## [0.1.1] - 2016-04-25
 #### Added
 - Added CONTRIBUTING.md and CHANGELOG.md
@@ -19,4 +29,5 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Initial release
 - Added Symphony PDO as requirement
 
+[Unreleased]: https://github.com/pointybeard/api_framework/compare/v0.1.1...master
 [0.1.1]: https://github.com/pointybeard/api_framework/compare/v0.1.0...v0.1.1

README.md

@@ -8,12 +8,11 @@ This is an extension for Symphony CMS. Add it to your `/extensions` folder in yo
 
 ### Requirements
 
-This extension requires the **[Symfony HTTP Foundation](https://github.com/symfony/http-foundation)** (`symfony/http-foundation`) and **[Symphony PDO](https://github.com/pointybeard/symphony-pdo)** (`pointybeard/symphony-pdo`) to be installed via Composer. Either require both of these in your main composer.json file, or run `composer install` on the `extension/api_framework` directory.
+This extension requires the **[Symfony HTTP Foundation](https://github.com/symfony/http-foundation)** (`symfony/http-foundation`) to be installed via Composer. Either require both of these in your main composer.json file, or run `composer install` on the `extension/api_framework` directory.
 
     "require": {
       "php": ">=5.6.6",
-      "symfony/http-foundation": "^3.0@dev",
-      "pointybeard/symphony-pdo": "~0.1"
+      "symfony/http-foundation": "^3.0@dev"
     }
 
 ## Usage
@@ -113,8 +112,6 @@ Would result in the following JSON
 }
 ```
 
-**Note that when there is a single, in the case, `<entry>` element, the a JSON array is not produced. This is a known limitation (see [https://github.com/pointybeard/api_framework/issues/2](https://github.com/pointybeard/api_framework/issues/2))**
-
 ### Controller Event
 
 Use the `API Framework: Controller` event to listen for PUT, POST, PATCH and DELETE requests. To create your own controller, make a folder called `controllers` in your `/workspace` directory.
@@ -240,3 +237,141 @@ Here is an example of a completed controller:
             return $this->render($response, $output);
         }
     }
+
+### Transformers
+
+Prior to converting the XML into JSON, transformers are run over it. Transformers mutate the result based on a test and action.
+
+`@jsonForceArray`
+
+This transformation will look for the attribute `jsonForceArray` on any XML elements. If it is set to "true", this transformation is applied. It relates to **[#issue-2](https://github.com/pointybeard/api_framework/issues/2)**. When there are multiple elements of the same name, for example 'entry', the JSON encode process will treat these as an array. E.g.
+
+```
+<data>
+  <entries>
+    <entry>
+      <id>2</id>
+      <title>Another Entry</title>
+    </entry>
+    <entry>
+      <id>1</id>
+      <title>An Entry</title>
+    </entry>
+  </entries>
+</data>
+```
+
+becomes
+
+
+```
+{
+    "entries": {
+        "entry": [
+            {
+                "id": "2",
+                "title": "Another Entry",
+            },
+            {
+                "id": "1",
+                "title": "An Entry",
+            }
+        ]
+    }
+}
+```
+
+However, if there is only a single 'entry' element, it is treated as an object. This is because internally it is just an associtive array, not an indexed array of 'entry' objects. E.g.
+
+```
+<data>
+  <entries>
+    <entry>
+      <id>2</id>
+      <title>Another Entry</title>
+    </entry>
+  </entries>
+</data>
+```
+
+results in
+
+```
+{
+    "entries": {
+        "entry": {
+            "id": "1",
+            "title": "An Entry",
+        }
+    }
+}
+```
+
+Notice that 'entry' is a JSON object. The problem with this is inconsistent data. It changes depending on how many entries are present. The solution is to set `jsonForceArray="true"` on the 'entry' element to trigger the transformation:
+
+```
+<data>
+  <entries>
+    <entry jsonForceArray="true">
+      <id>2</id>
+      <title>Another Entry</title>
+    </entry>
+  </entries>
+</data>
+```
+
+Which results in JSON
+
+```
+{
+    "entries": {
+        "entry": [
+            {
+                "id": "2",
+                "title": "Another Entry",
+            }
+        ]
+    }
+}
+```
+
+### Creating new Transformers
+
+This extention provides the delegate `APIFrameworkJSONRendererAppendTransformations` on all frontend pages with the `JSON` type. The context includes an instance of `Lib\Transformer`. Use the `append()` method to add your own transformations. E.g.
+
+```
+<?php
+
+use Symphony\ApiFramework\Lib;
+
+Class extension_example extends Extension
+{
+  public function getSubscribedDelegates(){
+    return[[
+      'page' => '/frontend/',
+      'delegate' => 'APIFrameworkJSONRendererAppendTransformations',
+      'callback' => 'appendTransformations'
+      ]];
+  }
+
+  public function appendTransformations($context) {
+
+    $context['transformer']->append(
+      new Lib\Transformation(
+
+        // This is the test. If it returns true, the action will be run
+        function(array $input, array $attributes=[]){
+          // do some tests in here and return either true or false
+          return true;
+        },
+
+        // This is the action. If the test passes, this code will be run
+        function(array $input, array $attributes=[]){
+          // Operate on $input and return the result.
+          return $input;
+        }
+      )
+    );
+  }
+}
+```

extension.driver.php

@@ -1,8 +1,11 @@
 <?php
 
-include __DIR__ . '/vendor/autoload.php';
+require_once __DIR__ . '/vendor/autoload.php';
 
-Class extension_api_framework extends Extension {
+use Symphony\ApiFramework\Lib;
+
+Class extension_api_framework extends Extension
+{
     public function getSubscribedDelegates(){
         return[
             [
@@ -15,16 +18,56 @@ public function getSubscribedDelegates(){
                 'delegate' => 'FrontendOutputPreGenerate',
                 'callback' => 'setBoilerplateXSL'
             ],
-
+            [
+                'page' => '/frontend/',
+                'delegate' => 'APIFrameworkJSONRendererAppendTransformations',
+                'callback' => 'appendTransformations'
+            ],
         ];
     }
 
+    public function appendTransformations($context) {
+
+      // Add the @jsonForceArray transformation
+      $context['transformer']->append(
+        new Lib\Transformation(
+          function(array $input, array $attributes=[]){
+              // First make sure there is an attributes array
+              if(empty($attributes)) {
+                  return false;
+              }
+              // Only looking at the jsonForceArray property
+              elseif(!isset($attributes['jsonForceArray']) || $attributes['jsonForceArray'] !== "true") {
+                  return false;
+              }
+              // This is already an indexed array.
+              elseif(!Lib\array_is_assoc($input)) {
+                  return false;
+              }
+              // jsonForceArray is set, and it's true
+              return true;
+          },
+          function(array $input, array $attributes=[]){
+              $result = [];
+              // Encapsulate everything in an array
+              foreach($input as $key => $value) {
+                  $result[$key] = $value;
+                  unset($input[$key]);
+              }
+              $input[] = $result;
+              return $input;
+          }
+        )
+      );
+    }
+
     public function setJSONLauncher($context)
     {
         if($_REQUEST['mode'] == 'administration') {
             return;
         }
         define('SYMPHONY_LAUNCHER', 'renderer_json');
+
         include __DIR__ . '/src/Includes/JsonRendererLauncher.php';
     }
 

src/Includes/JsonRendererLauncher.php

@@ -29,6 +29,22 @@ function renderer_json($mode){
           // use JSON_PRETTY_PRINT directly on a SimpleXMLElement object
           $outputArray = json_decode(json_encode($xml));
 
+          // Get the transforer object ready. Other extensions will
+          // add their transormations to this.
+          $transformer = new Lib\Transformer();
+
+          /**
+           * Allow other extensions to add their own transformers
+           */
+          Symphony::ExtensionManager()->notifyMembers(
+            'APIFrameworkJSONRendererAppendTransformations',
+            '/frontend/',
+            ['transformer' => &$transformer]
+          );
+
+          // Apply transformations
+          $outputArray = $transformer->run($outputArray);
+
           // Now put the array through a json_encode
           $output = json_encode($outputArray, JSON_PRETTY_PRINT);
 

src/Lib/Transformation.php

@@ -0,0 +1,21 @@
+<?php
+namespace Symphony\ApiFramework\Lib;
+
+class Transformation
+{
+  private $test;
+  private $action;
+
+  public function __construct(callable $test, callable $action)
+  {
+    $this->test = $test;
+    $this->action = $action;
+  }
+
+  public function __call($name, $args) {
+    if(!isset($this->$name) || !is_callable($this->$name)) {
+      throw new \Exception(__CLASS__ . " has no callable member '{$name}'.");
+    }
+    return call_user_func_array($this->$name, $args);
+  }
+}

src/Lib/Transformer.php

@@ -0,0 +1,76 @@
+<?php
+namespace Symphony\ApiFramework\Lib;
+
+function array_is_assoc(array $input) {
+    return array_keys($input) !== range(0, count($input) - 1);
+}
+
+function array_remove_empty($haystack)
+{
+    foreach ($haystack as $key => $value) {
+        if (is_array($value)) {
+            $haystack[$key] = array_remove_empty($haystack[$key]);
+        }
+        if (empty($haystack[$key])) {
+            unset($haystack[$key]);
+        }
+    }
+    return $haystack;
+}
+
+/**
+ * Transformer
+ * Modifies an array with various transformations
+ */
+class Transformer
+{
+
+  private $transformations = [];
+
+  public function append(Transformation $transformation) {
+    $this->transformations[] = $transformation;
+    return $this;
+  }
+
+  public function transformations() {
+    return $this->transformations;
+  }
+
+  public function run(array $input) {
+    foreach ($this->transformations as $t) {
+      $input = $this->recursiveApplyTransformationToArray($input, $t);
+    }
+
+    return $input;
+  }
+
+  private function recursiveApplyTransformationToArray(array $input, Transformation $transformation) {
+    $result = [];
+
+    $attributes = isset($input['@attributes']) ? $input['@attributes'] : [];
+    // Strip out the attributes.
+    unset($input['@attributes']);
+
+    // Run the input against the transformation test. If it passes, run
+    // the actual transformation
+    if($transformation->test($input, $attributes) === true) {
+        $input = $transformation->action($input, $attributes);
+    }
+
+    // Are we dealing with an associative array, or a sequential indexed array
+    $isAssoc = array_is_assoc($input);
+
+    // Iterate over each element in the array and decide if we need to move deeper
+    foreach($input as $key => $value) {
+        $next = (is_array($value)
+            // It's an array, so go deeper.
+            ? $this->recursiveApplyTransformationToArray($value, $transformation)
+            // Non-array, just append it back in and return
+            : $value
+        );
+        // Preserve array indexes
+        $isAssoc ? $result[$key] = $next : array_push($result, $value);
+    }
+    return $result;
+  }
+}