Add PHPDoc annotations and PHPStan for static analysis

.github/workflows/ci-cd.yaml

@@ -31,6 +31,19 @@ jobs:
         run: composer install --no-ansi --no-interaction --no-progress
       - name: Run test suite
         run: vendor/bin/phpunit
+  PHPStan:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: shivammathur/[email protected]
+        with:
+          php-version: '8.1'
+          tools: composer:v2
+      - uses: actions/checkout@v3
+      - name: Install Dependencies
+        run: composer install --no-ansi --no-interaction --no-progress
+      - name: Run PHPStan
+        run: vendor/bin/phpstan analyse
   Integration_tests:
     if: github.event_name == 'push'
     runs-on: ${{ matrix.os }}

composer.json

@@ -30,7 +30,8 @@
   },
 
   "require-dev": {
-    "phpunit/phpunit": "^4.8 || ^5.7 || ^6.5 || ^7.5 || ^8.4 || ^9.3"
+    "phpunit/phpunit": "^4.8 || ^5.7 || ^6.5 || ^7.5 || ^8.4 || ^9.3",
+    "phpstan/phpstan": "^1.0"
   },
 
   "autoload": {

lib/Tinify.php

@@ -12,29 +12,52 @@ class Tinify {
     private static $compressionCount = NULL;
     private static $client = NULL;
 
+    /**
+     * @param string $key
+     * @return void
+     */
     public static function setKey($key) {
         self::$key = $key;
         self::$client = NULL;
     }
 
+    /**
+     * @param string $appIdentifier
+     * @return void
+     */
     public static function setAppIdentifier($appIdentifier) {
         self::$appIdentifier = $appIdentifier;
         self::$client = NULL;
     }
 
+    /**
+     * @param string $proxy
+     * @return void
+     */
     public static function setProxy($proxy) {
         self::$proxy = $proxy;
         self::$client = NULL;
     }
 
+    /**
+     * @return int|null
+     */
     public static function getCompressionCount() {
         return self::$compressionCount;
     }
 
+    /**
+     * @param int $compressionCount
+     * @return void
+     */
     public static function setCompressionCount($compressionCount) {
         self::$compressionCount = $compressionCount;
     }
 
+    /**
+     * @return Client
+     * @throws AccountException
+     */
     public static function getClient() {
         if (!self::$key) {
             throw new AccountException("Provide an API key with Tinify\setKey(...)");
@@ -47,43 +70,95 @@ public static function getClient() {
         return self::$client;
     }
 
+    /**
+     * @param Client $client
+     * @return void
+     */
     public static function setClient($client) {
         self::$client = $client;
     }
 }
 
+/**
+ * @param string $key
+ * @return void
+ */
 function setKey($key) {
     return Tinify::setKey($key);
 }
 
+/**
+ * @param string $appIdentifier
+ * @return void
+ */
 function setAppIdentifier($appIdentifier) {
     return Tinify::setAppIdentifier($appIdentifier);
 }
 
+/**
+ * @param string $proxy
+ * @return void
+ */
 function setProxy($proxy) {
     return Tinify::setProxy($proxy);
 }
 
+/**
+ * @return int|null
+ */
 function getCompressionCount() {
     return Tinify::getCompressionCount();
 }
 
+/**
+ * @return int|null
+ */
 function compressionCount() {
     return Tinify::getCompressionCount();
 }
 
+/**
+ * @param string $path
+ * @return Source
+ * @throws AccountException
+ * @throws ClientException
+ * @throws ServerException
+ * @throws ConnectionException
+ */
 function fromFile($path) {
     return Source::fromFile($path);
 }
 
+/**
+ * @param string $string
+ * @return Source
+ * @throws AccountException
+ * @throws ClientException
+ * @throws ServerException
+ * @throws ConnectionException
+ */
 function fromBuffer($string) {
     return Source::fromBuffer($string);
 }
 
+/**
+ * @param string $string
+ * @return Source
+ * @throws AccountException
+ * @throws ClientException
+ * @throws ServerException
+ * @throws ConnectionException
+ */
 function fromUrl($string) {
     return Source::fromUrl($string);
 }
 
+/**
+ * @return bool
+ * @throws AccountException
+ * @throws ServerException
+ * @throws ConnectionException
+ */
 function validate() {
     try {
         Tinify::getClient()->request("post", "/shrink");

lib/Tinify/Client.php

@@ -10,15 +10,28 @@ class Client {
 
     private $options;
 
+    /**
+     * @return string
+     */
     public static function userAgent() {
         $curl = curl_version();
         return "Tinify/" . VERSION . " PHP/" . PHP_VERSION . " curl/" . $curl["version"];
     }
 
+    /**
+     * @return string
+     */
     private static function caBundle() {
         return __DIR__ . "/../data/cacert.pem";
     }
 
+    /**
+     * @param string $key
+     * @param string|null $app_identifier
+     * @param string|null $proxy
+     * @throws ClientException
+     * @throws ConnectionException
+     */
     function __construct($key, $app_identifier = NULL, $proxy = NULL) {
         $curl = curl_version();
 
@@ -70,6 +83,16 @@ function __construct($key, $app_identifier = NULL, $proxy = NULL) {
         }
     }
 
+    /**
+     * @param string $method
+     * @param string $url
+     * @param string|array|null $body
+     * @return \stdClass Object with 'body' (string) and 'headers' (array) properties
+     * @throws AccountException
+     * @throws ClientException
+     * @throws ServerException
+     * @throws ConnectionException
+     */
     function request($method, $url, $body = NULL) {
         $header = array();
         if (is_array($body)) {
@@ -155,6 +178,10 @@ function request($method, $url, $body = NULL) {
         }
     }
 
+    /**
+     * @param string|array $headers
+     * @return array
+     */
     protected static function parseHeaders($headers) {
         if (!is_array($headers)) {
             $headers = explode("\r\n", $headers);

lib/Tinify/Exception.php

@@ -5,6 +5,12 @@
 class Exception extends \Exception {
     public $status;
 
+    /**
+     * @param string $message
+     * @param string $type
+     * @param int $status
+     * @return Exception|AccountException|ClientException|ServerException
+     */
     public static function create($message, $type, $status) {
         if ($status == 401 || $status == 429) {
             $klass = "Tinify\AccountException";
@@ -20,6 +26,11 @@ public static function create($message, $type, $status) {
         return new $klass($message, $type, $status);
     }
 
+    /**
+     * @param string $message
+     * @param string|null $type
+     * @param int|null $status
+     */
     function __construct($message, $type = NULL, $status = NULL) {
         $this->status = $status;
         if ($status) {

lib/Tinify/Result.php

@@ -5,31 +5,54 @@
 class Result extends ResultMeta {
     protected $data;
 
+    /**
+     * @param array $meta
+     * @param string $data
+     */
     public function __construct($meta, $data) {
         $this->meta = $meta;
         $this->data = $data;
     }
 
+    /**
+     * @return string
+     */
     public function data() {
         return $this->data;
     }
 
+    /**
+     * @return string
+     */
     public function toBuffer() {
         return $this->data;
     }
 
+    /**
+     * @param string $path
+     * @return int|false
+     */
     public function toFile($path) {
         return file_put_contents($path, $this->toBuffer());
     }
 
+    /**
+     * @return int
+     */
     public function size() {
         return intval($this->meta["content-length"]);
     }
 
+    /**
+     * @return string
+     */
     public function mediaType() {
         return $this->meta["content-type"];
     }
 
+    /**
+     * @return string
+     */
     public function contentType() {
         return $this->mediaType();
     }

lib/Tinify/ResultMeta.php

@@ -5,22 +5,37 @@
 class ResultMeta {
     protected $meta;
 
+    /**
+     * @param array $meta
+     */
     public function __construct($meta) {
         $this->meta = $meta;
     }
 
+    /**
+     * @return int
+     */
     public function width() {
         return intval($this->meta["image-width"]);
     }
 
+    /**
+     * @return int
+     */
     public function height() {
         return intval($this->meta["image-height"]);
     }
 
+    /**
+     * @return string|null
+     */
     public function location() {
         return isset($this->meta["location"]) ? $this->meta["location"] : null;
     }
 
+    /**
+     * @return string|null
+     */
     public function extension() {
         if (isset($this->meta["content-type"])) {
             $parts = explode("/", $this->meta["content-type"]);