Merge pull request #63 from tomaj/typehints

Added typehints

Author: tomaj

CHANGELOG.md

@@ -7,6 +7,7 @@ Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) princip
 #### Changed
 
 * Update nette libs to version 3.0.0 (BC break)
+* Added typehints (BC break)
 * Pretty JSON output in API console - without escaping unicode and slashes
 * Replaced handler information array triplet (endpoint, handler, authorization) with Api
 

UPGRADE.md

@@ -0,0 +1,73 @@
+# UPGRADE
+
+## Upgrade from 1.x to 2.0.0
+
+### Removed support for old PHP versions
+New version not supported PHP versions 5.6 and 7.0 and also hhvm. Please use it with newer versions of PHP (>7.1)
+
+### Updated dependencies
+Version 2.0.0 requires nette packages in version 3.0, so probably you will have to upgrade whole your nette application 
+
+### Typehints
+There are some breaking changes because of typehints:
+
+#### ApiAuthorizationInterface
+Add typehints to methods:
+- `authorized(): bool`
+- `getErrorMessage(): ?string`
+
+#### ApiHandlerInterface
+Add typehints to methods:
+- `params(): array`
+- `handle(array $params): Tomaj\NetteApi\Response\ResponseInterface`
+
+#### ApiLoggerInterface
+Add typehints to method:
+- `log(int $responseCode, string $requestMethod, string $requestHeader, string $requestUri, string $requestIp, string $requestAgent, int $responseTime): bool`
+
+#### BearerTokenRepositoryInterface
+Add typehints to methods:
+- `validToken(string $token): bool`
+- `ipRestrictions(string $token): ?string`
+
+#### IpDetectorInterface
+Add typehints to method:
+- `getRequestIp(): string`
+
+#### ParamInterface
+Add typehints to methods:
+- `isValid(): bool`
+- `getKey(): string`
+
+#### EndpointInterface
+Add typehints to methods:
+- `getMethod(): string`
+- `getVersion(): int`
+- `getPackage(): string`
+- `getApiAction(): ?string`
+- `getUrl(): string`
+
+### Renamed methods
+Few methods have been renamed, please use their new versions:
+- `ApiDecider::addApiHandler()` -> `ApiDecider::addApi()`
+- `ApiDecider::getApiHandler()` -> `ApiDecider::getApi()`
+- `ApiDecider::getHandlers()` -> `ApiDecider::getApis()`
+
+### Final methods
+BaseHandler now have few final methods:
+- `setEndpointIdentifier` 
+- `getEndpoint`
+- `setupLinkGenerator`
+- `createLink`
+
+### Removed params
+Parameters $parent and $name have been removed from ApiListingControl. New usage is:
+```
+new ApiListingControl($apiDecider)
+```
+
+### Changed params
+Some parameters were strictly typed:
+- second parameter in `JsonApiResponse::__construct` (`$payload` formerly known as `$data`) is now `array`
+- fifth parameter in `JsonApiResponse::__construct` (`$expiration`) is now `DateTimeInteface` or `null`
+- fourth parameter in `InputParam::__construc` (`$availableValues`) is now `array` or `null`

src/Authorization/ApiAuthorizationInterface.php

@@ -9,13 +9,13 @@ interface ApiAuthorizationInterface
      *
      * @return boolean
      */
-    public function authorized();
+    public function authorized(): bool;
 
     /**
      * If authorization deny acces, this method should provide additional information
      * abount cause of restriction.
      *
-     * @return string|boolean
+     * @return string|null
      */
-    public function getErrorMessage();
+    public function getErrorMessage(): ?string;
 }

src/Authorization/BearerTokenAuthorization.php

@@ -13,9 +13,9 @@ class BearerTokenAuthorization implements ApiAuthorizationInterface
     private $tokenRepository;
 
     /**
-     * @var string|boolean
+     * @var string|null
      */
-    private $errorMessage = false;
+    private $errorMessage = null;
 
     /**
      * @var IpDetectorInterface
@@ -37,7 +37,7 @@ public function __construct(BearerTokenRepositoryInterface $tokenRepository, IpD
     /**
      * {@inheritdoc}
      */
-    public function authorized()
+    public function authorized(): bool
     {
         $token = $this->readAuthorizationToken();
         if (!$token) {
@@ -61,7 +61,7 @@ public function authorized()
     /**
      * {@inheritdoc}
      */
-    public function getErrorMessage()
+    public function getErrorMessage(): ?string
     {
         return $this->errorMessage;
     }
@@ -77,12 +77,12 @@ public function getErrorMessage()
      *
      * @return boolean
      */
-    private function isValidIp($ipRestrictions)
+    private function isValidIp(?string $ipRestrictions): bool
     {
-        if ($ipRestrictions === false) {
+        if ($ipRestrictions === null) {
             return false;
         }
-        if ($ipRestrictions == '*' || $ipRestrictions == '' || $ipRestrictions === null) {
+        if ($ipRestrictions === '*' || $ipRestrictions === '') {
             return true;
         }
         $ip = $this->ipDetector->getRequestIp();
@@ -108,36 +108,36 @@ private function isValidIp($ipRestrictions)
      * @param string $range  is in IP/CIDR format eg 127.0.0.1/24
      * @return boolean
      */
-    private function ipInRange($ip, $range)
+    private function ipInRange(string $ip, string $range): bool
     {
         list($range, $netmask) = explode('/', $range, 2);
         $range_decimal = ip2long($range);
-        $ip_decimal = ip2long($ip);
-        $wildcard_decimal = pow(2, (32 - $netmask)) - 1;
+        $ipDecimal = ip2long($ip);
+        $wildcard_decimal = pow(2, (32 - (int)$netmask)) - 1;
         $netmask_decimal = ~ $wildcard_decimal;
-        return (($ip_decimal & $netmask_decimal) == ($range_decimal & $netmask_decimal));
+        return (($ipDecimal & $netmask_decimal) == ($range_decimal & $netmask_decimal));
     }
 
     /**
      * Read HTTP reader with authorization token
      * If everything is ok, it return token. In other situations returns false and set errorMessage.
      *
-     * @return string|boolean
+     * @return string|null
      */
-    private function readAuthorizationToken()
+    private function readAuthorizationToken(): ?string
     {
         if (!isset($_SERVER['HTTP_AUTHORIZATION'])) {
             $this->errorMessage = 'Authorization header HTTP_Authorization is not set';
-            return false;
+            return null;
         }
         $parts = explode(' ', $_SERVER['HTTP_AUTHORIZATION']);
-        if (count($parts) != 2) {
+        if (count($parts) !== 2) {
             $this->errorMessage = 'Authorization header contains invalid structure';
-            return false;
+            return null;
         }
-        if (strtolower($parts[0]) != 'bearer') {
+        if (strtolower($parts[0]) !== 'bearer') {
             $this->errorMessage = 'Authorization header doesn\'t contains bearer token';
-            return false;
+            return null;
         }
         return $parts[1];
     }

src/Authorization/NoAuthorization.php

@@ -7,16 +7,16 @@ class NoAuthorization implements ApiAuthorizationInterface
     /**
      * {@inheritdoc}
      */
-    public function authorized()
+    public function authorized(): bool
     {
         return true;
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getErrorMessage()
+    public function getErrorMessage(): ?string
     {
-        return false;
+        return null;
     }
 }

src/Component/ApiConsoleControl.php

@@ -5,6 +5,7 @@
 use Nette\Application\UI\Control;
 use Nette\Application\UI\Form;
 use Nette\Http\IRequest;
+use Nette\Utils\ArrayHash;
 use Tomaj\Form\Renderer\BootstrapRenderer;
 use Tomaj\NetteApi\Authorization\ApiAuthorizationInterface;
 use Tomaj\NetteApi\Authorization\BearerTokenAuthorization;
@@ -32,13 +33,13 @@ public function __construct(IRequest $request, EndpointIdentifier $endpoint, Api
         $this->request = $request;
     }
 
-    public function render()
+    public function render(): void
     {
         $this->getTemplate()->setFile(__DIR__ . '/console.latte');
         $this->getTemplate()->render();
     }
 
-    protected function createComponentConsoleForm()
+    protected function createComponentConsoleForm(): Form
     {
         $form = new Form();
 
@@ -124,12 +125,12 @@ protected function createComponentConsoleForm()
         return $form;
     }
 
-    private function getLabel(InputParam $param)
+    private function getLabel(InputParam $param): string
     {
         return ucfirst(str_replace('_', ' ', $param->getKey()));
     }
 
-    private function getParamLabel(InputParam $param)
+    private function getParamLabel(InputParam $param): string
     {
         $title = $this->getLabel($param);
         if ($param->isRequired()) {
@@ -139,7 +140,7 @@ private function getParamLabel(InputParam $param)
         return $title;
     }
 
-    public function formSucceeded($form, $values)
+    public function formSucceeded(Form $form, ArrayHash $values): void
     {
         $url = $values['api_url'];
 

src/Component/ApiListingControl.php

@@ -3,7 +3,6 @@
 namespace Tomaj\NetteApi\Component;
 
 use Nette\Application\UI\Control;
-use Nette\ComponentModel\IContainer;
 use Tomaj\NetteApi\ApiDecider;
 use Closure;
 use Exception;
@@ -17,25 +16,25 @@ class ApiListingControl extends Control
     /** @var Closure|null */
     private $clickCallback;
 
-    public function __construct(IContainer $parent, $name, ApiDecider $apiDecider)
+    public function __construct(ApiDecider $apiDecider)
     {
         $this->apiDecider = $apiDecider;
     }
 
-    public function onClick(Closure $callback)
+    public function onClick(Closure $callback): void
     {
         $this->clickCallback = $callback;
     }
 
-    public function render()
+    public function render(): void
     {
         $apis = $this->apiDecider->getApis();
         $this->getTemplate()->add('apis', $this->groupApis($apis));
         $this->getTemplate()->setFile(__DIR__ . '/api_listing.latte');
         $this->getTemplate()->render();
     }
 
-    public function handleSelect($method, $version, $package, $apiAction)
+    public function handleSelect(string $method, int $version, string $package, ?string $apiAction = null)
     {
         if (!$this->clickCallback) {
             throw new Exception('You have to set onClick callback to component!');
@@ -48,7 +47,7 @@ public function handleSelect($method, $version, $package, $apiAction)
      * @param Api[] $handlers
      * @return array
      */
-    private function groupApis($handlers)
+    private function groupApis(array $handlers): array
     {
         $versionHandlers = [];
         foreach ($handlers as $handler) {

src/EndpointIdentifier.php

@@ -12,38 +12,38 @@ class EndpointIdentifier implements EndpointInterface
 
     private $apiAction;
 
-    public function __construct($method, $version, $package, $apiAction = '')
+    public function __construct(string $method, int $version, string $package, ?string $apiAction = null)
     {
         $this->method = strtoupper($method);
         $this->version = $version;
         $this->package = $package;
         $this->apiAction = $apiAction;
     }
 
-    public function getMethod()
+    public function getMethod(): string
     {
         return $this->method;
     }
 
-    public function getVersion()
+    public function getVersion(): int
     {
         return $this->version;
     }
 
-    public function getPackage()
+    public function getPackage(): string
     {
         return $this->package;
     }
 
-    public function getApiAction()
+    public function getApiAction(): ?string
     {
-        if ($this->apiAction == '') {
+        if ($this->apiAction === '') {
             return null;
         }
         return $this->apiAction;
     }
 
-    public function getUrl()
+    public function getUrl(): string
     {
         return "v{$this->version}/{$this->package}/{$this->apiAction}";
     }

src/EndpointInterface.php

@@ -4,13 +4,13 @@
 
 interface EndpointInterface
 {
-    public function getMethod();
+    public function getMethod(): string;
 
-    public function getVersion();
+    public function getVersion(): int;
 
-    public function getPackage();
+    public function getPackage(): string;
 
-    public function getApiAction();
+    public function getApiAction(): ?string;
 
-    public function getUrl();
+    public function getUrl(): string;
 }

src/Handlers/AlwaysOkHandler.php

@@ -3,13 +3,14 @@
 namespace Tomaj\NetteApi\Handlers;
 
 use Tomaj\NetteApi\Response\JsonApiResponse;
+use Tomaj\NetteApi\Response\ResponseInterface;
 
 class AlwaysOkHandler extends BaseHandler
 {
     /**
      * {@inheritdoc}
      */
-    public function handle($params)
+    public function handle(array $params): ResponseInterface
     {
         return new JsonApiResponse(200, ['status' => 'ok']);
     }