server api tools added (request validator, response factory and exception transformer) (#2)

Author: Triplkrypl

.github/README.md

@@ -17,6 +17,9 @@ consider package version as unsupported except last version.
 
 ## Usage
 
+- [Api client](#api-client-service)
+- [Api server](#api-server-controller-tools)
+
 ### Api client service
 
 Api client require guzzle client, psr client interface is not good enough because absence of async request.
@@ -84,3 +87,83 @@ catch (\SimpleAsFuck\ApiToolkit\Model\Client\ApiException $exception) {
 }
 
 ```
+
+### Api server controller tools
+
+For request handling is prepared Validator and Response factories.
+More information about validation rules you can find in
+[Simple as fuck / Php Validator](https://github.com/simple-as-fuck/php-validator) readme.
+
+If you using symfony request and responses, you can use factories from different namespace, commented in example.
+
+```php
+
+// star of your action
+
+$rules = \SimpleAsFuck\ApiToolkit\Factory\Server\Validator::make($request);
+//$rules = \SimpleAsFuck\ApiToolkit\Factory\Symfony\Validator::make($request);
+
+// validate some query parameter
+$someQueryValidValue = $rules->query()->key('someKey')->string()->parseInt()->min(1)->notNull();
+
+// validate something from request body with json format
+$someJsonValidValue = $rules->json()->object()->property('someProperty')->string()->notEmpty()->max(255)->notNull();
+
+
+
+// end fo your action
+
+/**
+ * @var YourClass $yourModelForResponseBody
+ * @var \SimpleAsFuck\ApiToolkit\Service\Transformation\Transformer<YourClass> $transformer 
+ */
+
+// response with one object
+$response = \SimpleAsFuck\ApiToolkit\Factory\Server\ResponseFactory::makeJson($yourModelForResponseBody, $transformer, \Kayex\HttpCodes::HTTP_OK);
+//$response = \SimpleAsFuck\ApiToolkit\Factory\Symfony\ResponseFactory::makeJson($yourModelForResponseBody, $transformer, \Kayex\HttpCodes::HTTP_OK);
+
+// response with some array or collection (avoiding out of memory problem recommended some lazy loading iterator)
+$response = \SimpleAsFuck\ApiToolkit\Factory\Server\ResponseFactory::makeJsonStream(new \ArrayIterator([$yourModelForResponseBody]), $transformer);
+//$response = \SimpleAsFuck\ApiToolkit\Factory\Symfony\ResponseFactory::makeJsonStream(new \ArrayIterator([$yourModelForResponseBody]), $transformer);
+
+```
+
+### Api server middleware tools
+
+If anything go wrong you can use Exception transformers in your exception catching middleware or in some exception handler.
+
+For laravel is prepared Laravel config adapter which load automatically configuration for ExceptionTransformer,
+you can easily get this transformer from DI, without any new configuration (standard configuration from Laravel is used).
+
+```php
+
+/**
+ * @var \SimpleAsFuck\ApiToolkit\Service\Config\Repository $configRepository
+ */
+
+try {
+    // some breakable logic
+}
+catch(\SimpleAsFuck\ApiToolkit\Model\Server\ApiException $exception) {
+//catch(\Symfony\Component\HttpKernel\Exception\HttpException $exception) {
+    $response = \SimpleAsFuck\ApiToolkit\Factory\Server\ResponseFactory::makeJson(
+    //$response = \SimpleAsFuck\ApiToolkit\Factory\Symfony\ResponseFactory::makeJson(
+        $exception,
+        // transformer will convert exception in to json object with message property with original exception message
+        new \SimpleAsFuck\ApiToolkit\Service\Server\ApiExceptionTransformer(),
+        $exception->getStatusCode()
+    );
+}
+catch (\Throwable $exception) {
+    $response = \SimpleAsFuck\ApiToolkit\Factory\Server\ResponseFactory::makeJson(
+    //$response = \SimpleAsFuck\ApiToolkit\Factory\Symfony\ResponseFactory::makeJson(
+        $exception,
+        // transformer will convert exception in to json object with message property
+        // if application has turned off debug, message property contain only "Internal server error"
+        // but with enabled debug message contains exception type, message, file and line where was exception thrown
+        new \SimpleAsFuck\ApiToolkit\Service\Server\ExceptionTransformer($configRepository),
+        \Kayex\HttpCodes::HTTP_INTERNAL_SERVER_ERROR
+    );
+}
+
+```

.github/workflows/main.yml

@@ -24,6 +24,9 @@ jobs:
       - name: Run static analysis
         run: vendor/bin/phpstan analyse
 
+      - name: Run tests
+        run: vendor/bin/phpunit test/
+
   php81laraver8:
     name: "php 8.1, laravel 8"
     runs-on: ubuntu-latest
@@ -38,6 +41,9 @@ jobs:
       - name: Run static analysis
         run: vendor/bin/phpstan analyse
 
+      - name: Run tests
+        run: vendor/bin/phpunit test/
+
   php80:
     name: "php 8.0"
     runs-on: ubuntu-latest
@@ -52,6 +58,9 @@ jobs:
       - name: Run static analysis
         run: vendor/bin/phpstan analyse
 
+      - name: Run tests
+        run: vendor/bin/phpunit test/
+
   php74:
     name: "php 7.4"
     runs-on: ubuntu-latest
@@ -65,3 +74,6 @@ jobs:
 
       - name: Run static analysis
         run: vendor/bin/phpstan analyse
+
+      - name: Run tests
+        run: vendor/bin/phpunit test/

composer.json

@@ -5,14 +5,18 @@
         "ext-json": "*",
         "psr/http-message": "^1.0",
         "psr/http-factory": "^1.0",
-        "simple-as-fuck/php-validator": "^0.2.3",
+        "simple-as-fuck/php-validator": "^0.2.5",
         "guzzlehttp/guzzle": "^7.4",
         "illuminate/support": "^8.81|^9.0",
-        "kayex/http-codes": "^1.1"
+        "kayex/http-codes": "^1.1",
+        "guzzlehttp/psr7": "^2.1",
+        "symfony/psr-http-message-bridge": "^2.1",
+        "symfony/http-kernel": "^5.4"
     },
     "require-dev": {
         "phpstan/phpstan": "^1.2",
-        "friendsofphp/php-cs-fixer": "^3.4"
+        "friendsofphp/php-cs-fixer": "^3.4",
+        "phpunit/phpunit": "^9.5"
     },
     "autoload": {
         "psr-4": {"SimpleAsFuck\\ApiToolkit\\": "src/"}

phpstan.neon.dist

@@ -2,3 +2,4 @@ parameters:
     level: max
     paths:
         - src
+        - test

src/Factory/Server/ApiValidationException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimpleAsFuck\ApiToolkit\Factory\Server;
+
+use SimpleAsFuck\Validator\Factory\Exception;
+
+final class ApiValidationException extends Exception
+{
+    public function create(string $message): \Exception
+    {
+        return new \SimpleAsFuck\ApiToolkit\Model\Server\ApiException($message, 400);
+    }
+}

src/Factory/Server/ResponseFactory.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimpleAsFuck\ApiToolkit\Factory\Server;
+
+use GuzzleHttp\Psr7\HttpFactory;
+use GuzzleHttp\Psr7\PumpStream;
+use GuzzleHttp\Utils;
+use Kayex\HttpCodes;
+use Psr\Http\Message\ResponseFactoryInterface;
+use Psr\Http\Message\ResponseInterface;
+use SimpleAsFuck\ApiToolkit\Service\Transformation\Transformer;
+
+final class ResponseFactory
+{
+    /**
+     * @template TBody
+     * @param TBody|null $body
+     * @param Transformer<TBody>|null $transformer
+     * @param int<100,505> $code
+     * @param array<non-empty-string, string|array<string>> $headers
+     */
+    public static function makeJson($body, ?Transformer $transformer = null, int $code = HttpCodes::HTTP_OK, array $headers = []): ResponseInterface
+    {
+        $factory = new HttpFactory();
+        $response = self::makeResponse($factory, $code, $headers);
+
+        if ($body !== null) {
+            if ($transformer) {
+                $body = $transformer->toApi($body);
+            }
+        }
+        return $response->withBody($factory->createStream(Utils::jsonEncode($body)));
+    }
+
+    /**
+     * @template TBody
+     * @param \Iterator<TBody> $body
+     * @param Transformer<TBody>|null $transformer
+     * @param int<100,505> $code
+     * @param array<non-empty-string, string|array<string>> $headers
+     * @param float $speedLimit speed limit in KB/s for sending response slow down, zero means no slow down (this is not precise but is something)
+     */
+    public static function makeJsonStream(\Iterator $body, ?Transformer $transformer = null, int $code = HttpCodes::HTTP_OK, array $headers = [], float $speedLimit = 0): ResponseInterface
+    {
+        $factory = new HttpFactory();
+        $response = self::makeResponse($factory, $code, $headers);
+
+        $start = true;
+        $previousItemTime = \microtime(true);
+        return $response->withBody(new PumpStream(function (int $size) use ($body, $transformer, $speedLimit, &$start, &$previousItemTime): ?string {
+            $item = '';
+            if ($start) {
+                $start = false;
+                if (! $body->valid()) {
+                    return '[]';
+                }
+                $item = '[';
+            }
+
+            if (! $body->valid()) {
+                return null;
+            }
+
+            $responseData = $body->current();
+            if ($transformer) {
+                $responseData = $transformer->toApi($responseData);
+            }
+
+            $item .= Utils::jsonEncode($responseData);
+            $body->next();
+            if ($body->valid()) {
+                $item .= ',';
+                if ($speedLimit > 0) {
+                    $timeLimit = (strlen($item) / 1024) / $speedLimit;
+                    $timeOverHead = $timeLimit - (\microtime(true) - $previousItemTime);
+                    if ($timeOverHead > 0) {
+                        \usleep((int) ($timeOverHead * 1000000));
+                    }
+                }
+            } else {
+                $item .= ']';
+            }
+
+            $previousItemTime = \microtime(true);
+            return $item;
+        }));
+    }
+
+    /**
+     * @param int<100,505> $code
+     * @param array<non-empty-string, string|array<string>> $headers
+     */
+    private static function makeResponse(ResponseFactoryInterface $factory, int $code, array $headers): ResponseInterface
+    {
+        $response = $factory->createResponse($code);
+
+        foreach ($headers as $name => $header) {
+            $response = $response->withHeader($name, $header);
+        }
+
+        return $response;
+    }
+}

src/Factory/Server/Validator.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimpleAsFuck\ApiToolkit\Factory\Server;
+
+use Psr\Http\Message\ServerRequestInterface;
+use SimpleAsFuck\ApiToolkit\Model\Server\RequestRules;
+
+final class Validator
+{
+    public static function make(ServerRequestInterface $request): RequestRules
+    {
+        return new RequestRules(new ApiValidationException(), $request);
+    }
+}

src/Factory/Symfony/BadRequestException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimpleAsFuck\ApiToolkit\Factory\Symfony;
+
+use SimpleAsFuck\Validator\Factory\Exception;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+final class BadRequestException extends Exception
+{
+    public function create(string $message): \Exception
+    {
+        return new BadRequestHttpException($message);
+    }
+}

src/Factory/Symfony/ResponseFactory.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimpleAsFuck\ApiToolkit\Factory\Symfony;
+
+use Kayex\HttpCodes;
+use SimpleAsFuck\ApiToolkit\Service\Transformation\Transformer;
+use Symfony\Bridge\PsrHttpMessage\Factory\HttpFoundationFactory;
+
+final class ResponseFactory
+{
+    /**
+     * @template TBody
+     * @param TBody|null $body
+     * @param Transformer<TBody>|null $transformer
+     * @param int<100,505> $code
+     * @param array<non-empty-string, string|array<string>> $headers
+     */
+    public static function makeJson($body, ?Transformer $transformer = null, int $code = HttpCodes::HTTP_OK, array $headers = []): \Symfony\Component\HttpFoundation\Response
+    {
+        $factory = new HttpFoundationFactory();
+        return $factory->createResponse(\SimpleAsFuck\ApiToolkit\Factory\Server\ResponseFactory::makeJson($body, $transformer, $code, $headers));
+    }
+
+    /**
+     * @template TBody
+     * @param \Iterator<TBody> $body
+     * @param Transformer<TBody>|null $transformer
+     * @param int<100,505> $code
+     * @param array<non-empty-string, string|array<string>> $headers
+     * @param float $speedLimit speed limit in KB/s for sending response slow down, zero means no slow down (this is not precise but is something)
+     */
+    public static function makeJsonStream(\Iterator $body, ?Transformer $transformer = null, int $code = HttpCodes::HTTP_OK, array $headers = [], float $speedLimit = 0): \Symfony\Component\HttpFoundation\Response
+    {
+        $factory = new HttpFoundationFactory();
+        return $factory->createResponse(\SimpleAsFuck\ApiToolkit\Factory\Server\ResponseFactory::makeJsonStream($body, $transformer, $code, $headers, $speedLimit), true);
+    }
+}

src/Factory/Symfony/Validator.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimpleAsFuck\ApiToolkit\Factory\Symfony;
+
+use GuzzleHttp\Psr7\HttpFactory;
+use SimpleAsFuck\ApiToolkit\Model\Server\RequestRules;
+use Symfony\Bridge\PsrHttpMessage\Factory\PsrHttpFactory;
+use Symfony\Component\HttpFoundation\Request;
+
+final class Validator
+{
+    public static function make(Request $request): RequestRules
+    {
+        $psrFactory = new HttpFactory();
+        $factory = new PsrHttpFactory($psrFactory, $psrFactory, $psrFactory, $psrFactory);
+        $request = $factory->createRequest($request);
+        return new RequestRules(new BadRequestException(), $request);
+    }
+}