Added command transaction interface and implementation

Adjusted request and response return types in both interfaces and implementations.

Added factories to the package.

Simplified README for easier maintenance.

CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 4.0.0 - 2019-10-10
+### Added
+- Command interface and implementation.
+- Factories for Requests and Commands.
+
+### Changed
+- Request and response methods return types to simplify implementing the 
+objects in applications.
+- Simplified the README for easier maintenance.
+
+### Deprecated
+- Nothing
+
+### Removed
+- Nothing
+
+### Fixed
+- Nothing
+
+### Security
+- Nothing
+
 ## 3.0.0 - 2019-05-16
 ### Added
 - MethodEnum to make a more strict definition of the available methods.

README.md

@@ -16,43 +16,55 @@ composer require ulrack/transaction
 
 ## Usage
 
-### Request
+### [Request](src/Transaction/Request.php)
 
-The implementation of a `\Ulrack\Transaction\Common\RequestInterface` is provided
-in `\Ulrack\Transaction\Transaction\Request`.
-Requests expect their arguments in the constructor.
+A simple data access object for defining incoming web requests.
+This instance requires one of the [MethodEnum](src/Common/MethodEnum.php) 
+options to be passed.
 
-The first argument expects a method. This method can be picked from the
-`\Ulrack\Transaction\Common\MethodEnum` and should be one of:
-- `MethodEnum::GET()`
-- `MethodEnum::POST()`
-- `MethodEnum::PUT()`
-- `MethodEnum::PATCH()`
-- `MethodEnum::DELETE()`
+### [Response](src/Transaction/Response.php)
 
-The second argument expects a target for the request.
-In the case of a HTTP request this would the URI for the request.
+A simple data access object for defining outgoing web responses. 
 
-The third argument is optional and expects an associative array with parameters.
-In the case of a HTTP request, this expects the GET parameters.
+### [Command](src/Transaction/Command.php)
 
-The fourth argument is optional and expects the payload of the request.
-The payload would be the body of a request, in the case of a HTTP POST request, this would be the form data.
+A simple data access object for defining incoming CLI instructions. 
 
-The fifth argument is optional and expects an associative array with headers.
+### Factories
 
-### Response
+#### [CommandFactory](src/Factory/CommandFactory.php)
 
-The implementation of a `\Ulrack\Transaction\Common\ResponseInterface` is provided
-in `\Ulrack\Transaction\Transaction\Response`.
+A static factory which creates [Commands](src/Transaction/Command.php) based on
+provided arguments. 
 
-The first parameter of a response object expects a boolean representing whether the request was success.
+The following example will generate a command object.
 
-The second parameter expects the body of the response which was received from the request.
+```php
+<?php
 
-The third parameter expects an integer representing the status code of the response.
+use Ulrack\Transaction\Factory\CommandFactory;
+use Ulrack\Transaction\Common\CommandInterface;
 
-The fourth parameter is optional and expects an associative array of response headers.
+/** @var CommandInterface $subject */
+$subject = CommandFactory::create($_SERVER['argv']);
+```
+
+#### [RequestFactory](src/Factory/RequestFactory.php)
+
+A static factory which creates [Requests](src/Transaction/Request.php) based on
+provided arguments. 
+
+The following example will generate a request object.
+
+```php
+<?php
+
+use Ulrack\Transaction\Factory\RequestFactory;
+use Ulrack\Transaction\Common\RequestInterface;
+
+/** @var RequestInterface $subject */
+$subject = RequestFactory::create($_SERVER, $_GET, $_POST);
+```
 
 ## Change log
 

src/Common/CommandInterface.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * Copyright (C) Jyxon, Inc. All rights reserved.
+ * See LICENSE for license details.
+ */
+
+namespace Ulrack\Transaction\Common;
+
+interface CommandInterface
+{
+    /**
+     * Returns the command.
+     *
+     * @return string
+     */
+    public function getCommand(): string;
+
+    /**
+     * Returns the parameters.
+     *
+     * @return array
+     */
+    public function getParameters(): array;
+
+    /**
+     * Returns the options.
+     *
+     * @return array
+     */
+    public function getOptions(): array;
+
+    /**
+     * Returns the flags.
+     *
+     * @return array
+     */
+    public function getFlags(): array;
+}

src/Common/RequestInterface.php

@@ -11,16 +11,16 @@ interface RequestInterface
     /**
      * Retrieves the method of the request.
      *
-     * @return string
+     * @return MethodEnum
      */
-    public function getMethod(): string;
+    public function getMethod(): MethodEnum;
 
     /**
      * Retrieves the request headers.
      *
-     * @return string[]|null
+     * @return string[]
      */
-    public function getHeaders(): ?array;
+    public function getHeaders(): array;
 
     /**
      * Retrieves a header by its' name.
@@ -48,7 +48,7 @@ public function getPayload();
     /**
      * Retrieves a associative array of parameters of the request.
      *
-     * @return array|null
+     * @return array
      */
-    public function getParameters(): ?array;
+    public function getParameters(): array;
 }

src/Common/ResponseInterface.php

@@ -32,9 +32,9 @@ public function getStatusCode(): int;
     /**
      * Retrieves the response headers.
      *
-     * @return string[]|null
+     * @return string[]
      */
-    public function getHeaders(): ?array;
+    public function getHeaders(): array;
 
     /**
      * Retrieves a header by its' name.

src/Exception/InvalidRequestException.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * Copyright (C) Jyxon, Inc. All rights reserved.
+ * See LICENSE for license details.
+ */
+
+namespace Ulrack\Transaction\Exception;
+
+use Exception;
+
+class InvalidRequestException extends Exception
+{
+    /**
+     * Constructor
+     *
+     * @param string $message
+     */
+    public function __construct(string $message)
+    {
+        parent::__construct(
+            sprintf(
+                'Invalid request: %s.',
+                $message
+            )
+        );
+    }
+}

src/Factory/CommandFactory.php

@@ -0,0 +1,78 @@
+<?php
+/**
+ * Copyright (C) Jyxon, Inc. All rights reserved.
+ * See LICENSE for license details.
+ */
+
+namespace Ulrack\Transaction\Factory;
+
+use Ulrack\Transaction\Transaction\Command;
+use Ulrack\Transaction\Common\CommandInterface;
+
+class CommandFactory
+{
+    /**
+     * Creates a CLI command request.
+     *
+     * @param array $arguments The arguments passed to the command line.
+     *
+     * @return CommandInterface
+     */
+    public static function create(array $arguments): CommandInterface
+    {
+        return new Command(
+            ...static::prepareArguments(
+                $arguments
+            )
+        );
+    }
+
+    /**
+     * Prepare the CLI arguments.
+     *
+     * @return array
+     */
+    private static function prepareArguments(array $arguments): array
+    {
+        // Strip the script
+        array_shift($arguments);
+
+        $command = array_shift($arguments);
+        $flags = [];
+        $options = [];
+        $parameters = [];
+        while ($argument = array_shift($arguments)) {
+            // First find out if there is a flag or parameter passed.
+            if (substr($argument, 0, 1) === '-') {
+                // The --parameter=value markdown is used
+                if (strpos($argument, '=') > 0) {
+                    $expArg = explode('=', $argument);
+                    $parameters[ltrim($expArg[0], '-')] = $expArg[1];
+
+                    continue;
+                }
+
+                // No subsequent value starting without a "-"
+                // It must be a flag
+                if (empty($arguments[0])
+                || substr($arguments[0], 0, 1) === '-') {
+                    $flags[] = ltrim($argument, '-');
+
+                    continue;
+                }
+
+                // There was a subsequent value starting without a "-"
+                // It counts as a parameter
+                $argument = ltrim($argument, '-');
+                $parameters[$argument] = array_shift($arguments);
+
+                continue;
+            }
+
+            // Additional arguments go into the options array
+            $options[] = $argument;
+        }
+
+        return [$command, $parameters, $options, $flags];
+    }
+}

src/Factory/RequestFactory.php

@@ -0,0 +1,92 @@
+<?php
+/**
+ * Copyright (C) Jyxon, Inc. All rights reserved.
+ * See LICENSE for license details.
+ */
+
+namespace Ulrack\Transaction\Factory;
+
+use Ulrack\Transaction\Common\MethodEnum;
+use Ulrack\Transaction\Transaction\Request;
+use Ulrack\Transaction\Common\RequestInterface;
+use Ulrack\Transaction\Exception\InvalidRequestException;
+
+class RequestFactory
+{
+    /**
+     * Creates a Web request.
+     *
+     * @param array $server The server parameters.
+     * @param array $get The get parameters.
+     * @param array $post The post payload.
+     *
+     * @return RequestInterface
+     *
+     * @throws InvalidRequestException When a invalid request method is detected.
+     */
+    public static function create(
+        array $server,
+        array $get = [],
+        array $post = []
+    ): RequestInterface {
+        $methods = MethodEnum::getOptions();
+        if (!isset($methods[$server['REQUEST_METHOD']])) {
+            throw new InvalidRequestException('Invalid request method.');
+        }
+
+        return new Request(
+            new MethodEnum($methods[$server['REQUEST_METHOD']]),
+            strtok($server['REQUEST_URI'], '?'),
+            $get,
+            $post,
+            static::parseHeaders($server)
+        );
+    }
+
+    /**
+     * Parse the headers to normalized key value pairs.
+     *
+     * @param array $server
+     *
+     * @return array
+     */
+    private static function parseHeaders(array $server): array
+    {
+        $headers = [];
+        foreach ($server as $key => $header) {
+            if (substr($key, 0, 5) === 'HTTP_') {
+                $headers[static::normalizeKey(substr($key, 5))] = $header;
+
+                continue;
+            }
+
+            $headers[static::normalizeKey($key)] = $header;
+        }
+
+        return $headers;
+    }
+
+    /**
+     * Normalize key name to standard format.
+     *
+     * @param string $key
+     *
+     * @return string
+     */
+    private static function normalizeKey(string $key): string
+    {
+        return str_replace(
+            ' ',
+            '-',
+            ucwords(
+                strtolower(
+                    str_replace(
+                        '_',
+                        ' ',
+                        $key
+                    )
+                )
+            )
+        );
+    }
+}