🔧 add PHPstan and remove PHP Code Sniffer (#188)

Author: sebastianMindee

.github/workflows/_static-analysis.yml

@@ -34,4 +34,7 @@ jobs:
     - name: Run lint
       run: |
         composer lint
-    
+
+    - name: Run PHPStan
+      run: |
+        composer phpstan

composer.json

@@ -16,7 +16,8 @@
   "require-dev": {
     "friendsofphp/php-cs-fixer": "^3.38",
     "phpunit/phpunit": "^9.6",
-    "madewithlove/license-checker": "^v1.0"
+    "madewithlove/license-checker": "^v1.0",
+    "phpstan/phpstan": "^2.1"
   },
   "suggest": {
     "ext-imagick": "Required for PDF rasterization and image processing features",
@@ -33,6 +34,7 @@
   ],
   "scripts": {
     "lint": "php-cs-fixer fix --dry-run --diff",
+    "phpstan": "phpstan analyse src --level 6",
     "format": "php-cs-fixer fix"
   }
 }

docs/code_samples/v2_ocr.txt

@@ -1,8 +1,8 @@
 <?php
 
 use Mindee\V2\Client;
-use Mindee\V2\Product\Ocr\Params\OcrParameters;
-use Mindee\V2\Product\Ocr\OcrResponse;
+use Mindee\V2\Product\OCR\Params\OCRParameters;
+use Mindee\V2\Product\OCR\OCRResponse;
 use Mindee\Input\PathInput;
 
 $apiKey = "MY_API_KEY";
@@ -14,7 +14,7 @@ $mindeeClient = new Client($apiKey);
 
 // Set ocr parameters
 // Note: modelId is mandatory.
-$ocrParams = new OcrParameters(
+$ocrParams = new OCRParameters(
     // ID of the model, required.
     $modelId,
 );

src/Dependency/DependencyChecker.php

@@ -93,6 +93,7 @@ public static function isImageMagickPolicyAllowed(): void
         $imagick = new Imagick();
         try {
             $imagick->readImage(
+                /** @phpstan-ignore-next-line */
                 TestingUtilities::getV1DataDir() . "/products/expense_receipts/default_sample.jpg"
             );
         } catch (Exception $e) {

src/Error/MindeeHttpException.php

@@ -25,20 +25,20 @@ class MindeeHttpException extends MindeeException
      */
     public int $statusCode;
     /**
-     * @var string|mixed|null API code as sent by the server.
+     * @var string|null API code as sent by the server.
      */
     public ?string $apiCode;
     /**
-     * @var mixed|null API details field as sent by the server.
+     * @var string|array<string, int|float|string|bool|null|array<array-key, mixed>>|null API details field as sent by the server.
      */
-    public $apiDetails;
+    public string|array|null $apiDetails;
     /**
-     * @var string|mixed|null API message field as sent by the server.
+     * @var string|array<string, int|float|string|bool|null|array<array-key, mixed>>|null API message field as sent by the server.
      */
-    public ?string $apiMessage;
+    public string|array|null $apiMessage;
 
     /**
-     * @param array $httpError Array containing the error data.
+     * @param array<string, int|float|string|bool|null|array<array-key, mixed>> $httpError Array containing the error data.
      * @param string $url Remote URL the error was found on.
      * @param integer $code Error code.
      */
@@ -71,11 +71,11 @@ public function __construct(array $httpError, string $url, int $code)
     /**
      * Builds an appropriate error object from the server reply.
      *
-     * @param array|string $response Parsed server response.
+     * @param array<string, int|float|string|bool|null|array<array-key, mixed>>|string|null $response Parsed server response.
      * @return string[]
      * @throws MindeeException Throws if the error itself can't be built.
      */
-    public static function createErrorObj($response): array
+    public static function createErrorObj(array|string|null $response): array
     {
         if (is_string($response)) {
             if (str_contains($response, 'Maximum pdf pages')) {
@@ -125,7 +125,7 @@ public static function createErrorObj($response): array
         ) {
             return $response['api_request']['error'];
         }
-        if (!$response) {
+        if (!isset($response)) {
             throw new MindeeException(
                 "Request to the API failed.",
                 ErrorCode::API_REQUEST_FAILED
@@ -139,9 +139,9 @@ public static function createErrorObj($response): array
 
     /**
      * @param string $url Remote URL the error was found on.
-     * @param array|string|boolean $response Raw server response.
+     * @param array<string, mixed>|string|null $response Raw server response.
      */
-    public static function handleError(string $url, $response): self
+    public static function handleError(string $url, array|string|null $response): self
     {
         if (is_array($response)) {
             $dataResponse = $response['data'] ?? ["data" => null];

src/Error/MindeeV2HttpException.php

@@ -4,6 +4,7 @@
 
 namespace Mindee\Error;
 
+use Mindee\V2\Parsing\ErrorItem;
 use Mindee\V2\Parsing\ErrorResponse;
 
 /**
@@ -29,7 +30,7 @@ class MindeeV2HttpException extends MindeeException
      */
     public ?string $errorCode;
     /**
-     * @var array List of associated errors.
+     * @var array<ErrorItem> List of associated errors.
      */
     public array $errors;
 

src/Extraction/ExtractedImage.php

@@ -47,15 +47,15 @@ class ExtractedImage
     /**
      * Initializes a new instance of the ExtractedImage class.
      *
-     * @param mixed $image The extracted image. Not explicitly typed as \Imagick to avoid errors.
+     * @param Imagick $image The extracted image.
      * @param string $filename The filename for the image.
      * @param string $saveFormat The format to save the image.
      * @param integer $pageIndex The page index of the image.
      * @param integer $index The element index of the image.
      *
      * @throws MindeeUnhandledException Throws if PDF operations aren't supported.
      */
-    public function __construct(mixed $image, string $filename, string $saveFormat, int $pageIndex, int $index)
+    public function __construct(Imagick $image, string $filename, string $saveFormat, int $pageIndex, int $index)
     {
         DependencyChecker::isImageMagickAvailable();
         DependencyChecker::isGhostscriptAvailable();
@@ -85,7 +85,7 @@ public function writeToFile(string $outputPath, ?string $format = null, int $qua
         $quality = min(100, max(0, $quality));
         if ('png' === $format) {
             $finalQuality = round($quality * 0.09);
-            $this->image->setOption('png:compression-level', $finalQuality);
+            $this->image->setOption('png:compression-level', (string) $finalQuality);
         } elseif (in_array($format, ['jpg', 'jpeg'], true)) {
             $this->image->setImageCompression(Imagick::COMPRESSION_JPEG);
         }

src/Extraction/ImageExtractor.php

@@ -4,13 +4,15 @@
 
 namespace Mindee\Extraction;
 
+use Exception;
 use Mindee\Dependency\DependencyChecker;
 use Mindee\Error\ErrorCode;
 use Mindee\Error\MindeeGeometryException;
 use Mindee\Error\MindeeImageException;
 use Mindee\Error\MindeePDFException;
 use Mindee\Geometry\BBox;
 use Mindee\Geometry\BBoxUtils;
+use Mindee\Geometry\Point;
 use Mindee\Geometry\Polygon;
 use Mindee\Input\LocalInputSource;
 use Mindee\V1\Parsing\Standard\BaseField;
@@ -129,11 +131,11 @@ public function getPageCount(): int
     /**
      * Extract multiple images on a given page from a list of fields having position data.
      *
-     * @param array $fields List of Fields to extract.
+     * @param array<BaseField<string|float|integer|boolean|Polygon>> $fields List of Fields to extract.
      * @param integer $pageIndex The page index to extract, begins at 0.
      * @param null|string $outputName The base output filename, must have an image extension.
      *
-     * @return array a list of extracted images
+     * @return array<ExtractedImage> a list of extracted images
      */
     public function extractImagesFromPage(array $fields, int $pageIndex, ?string $outputName = null): array
     {
@@ -144,12 +146,12 @@ public function extractImagesFromPage(array $fields, int $pageIndex, ?string $ou
     /**
      * Extracts images from a page.
      *
-     * @param array $polygons List of polygons to extract.
+     * @param array<Polygon|array<Point>> $polygons List of polygons to extract.
      * @param integer $pageIndex The page index to extract, begins at 0.
      * @param null|string $filenamePrefix Output filename prefix.
      * @param null|string $format Save format for extracted images. Defaults to the original format.
      *
-     * @return array an array of created images
+     * @return array<ExtractedImage> An array of created images
      * @throws MindeeImageException Throws if the image can't be processed.
      */
     public function extractPolygonsFromPage(
@@ -173,7 +175,7 @@ public function extractPolygonsFromPage(
                     $saveFormat
                 );
             }
-        } catch (ImagickException $e) {
+        } catch (Exception $e) {
             throw new MindeeImageException($e->getMessage(), $e->getCode(), $e);
         }
 
@@ -205,16 +207,15 @@ public function extractPolygonFromPage(
         } catch (ImagickException $e) {
             throw new MindeeImageException($e->getMessage(), $e->getCode(), $e);
         }
-        $filename ??= $this->filename;
         $format ??= $this->saveFormat;
-        $filename ??= sprintf('%s.%s_page%d-%d.%s', $filename, $format, $pageIndex, $index, $format);
+        $filename ??= sprintf('%s_page%d-%d.%s', $this->filename, $pageIndex, $index, $format);
         return new ExtractedImage($extractedImageData, $filename, $format, $pageIndex, $index);
     }
 
     /**
      * Extracts a single image from a Position field.
      *
-     * @param BaseField $field The field to extract.
+     * @param BaseField<string|float|integer|boolean|Polygon> $field The field to extract.
      * @param integer $pageIndex The page index to extract, begins at 0.
      * @param integer $index The index to use for naming the extracted image.
      * @param string $filename The output filename.
@@ -264,16 +265,15 @@ public function getInputSource(): LocalInputSource
     /**
      * Extracts images from a page.
      *
-     * @param array $fields List of Fields to extract.
+     * @param array<BaseField<string|float|integer|boolean|Polygon>> $fields List of Fields to extract.
      * @param integer $pageIndex The page index to extract, begins at 0.
      * @param string $outputName Name of the created file.
      * @param string $format The output format.
      *
-     * @return array an array of created images
+     * @return array<ExtractedImage> An array of created images
      */
     protected function extractFromPage(array $fields, int $pageIndex, string $outputName, string $format = 'jpg'): array
     {
-        $format ??= $this->saveFormat;
         $extractedImages = [];
 
         $i = 0;
@@ -316,7 +316,7 @@ protected function extractImageFromBbox(BBox $bbox, int|float $pageIndex): Imagi
      * Splits the filename into name and extension.
      *
      * @param string $filename Name of the file.
-     * @return array An array containing the name and extension of the file.
+     * @return array{0: string, 1: string} An array containing the name and extension of the file.
      */
     protected static function splitNameStrict(string $filename): array
     {

src/Extraction/PDFExtractor.php

@@ -86,14 +86,14 @@ public function getPageCount(): int
     /**
      * Extracts sub-documents from the source document using list of page indexes.
      *
-     * @param array|InvoiceSplitterV1InvoicePageGroups $pageIndexes List of sub-lists of pages to keep.
+     * @param array<array<integer>>|InvoiceSplitterV1InvoicePageGroups $pageIndexes List of sub-lists of pages to keep.
      *
      * @return ExtractedPDF[] list of extracted documents
      *
      * @throws MindeePDFException Throws if FDPF/FPDI wasn't able to handle the pdf during the extraction.
      * @throws InvalidArgumentException Throws if invalid indexes are provided.
      */
-    public function extractSubDocuments(mixed $pageIndexes): array
+    public function extractSubDocuments(array|InvoiceSplitterV1InvoicePageGroups $pageIndexes): array
     {
         $extractedPdfs = [];
 
@@ -141,12 +141,12 @@ public function extractSubDocuments(mixed $pageIndexes): array
     /**
      * Extracts invoices as complete PDFs from the document.
      *
-     * @param array|InvoiceSplitterV1InvoicePageGroups $pageIndexes List of sub-lists of pages to keep.
+     * @param array<array<integer>>|InvoiceSplitterV1InvoicePageGroups $pageIndexes List of sub-lists of pages to keep.
      * @param boolean $strict Whether to trust confidence scores or not.
      *
      * @return ExtractedPDF[] a list of extracted invoices
      */
-    public function extractInvoices(mixed $pageIndexes, bool $strict = false): array
+    public function extractInvoices(array|InvoiceSplitterV1InvoicePageGroups $pageIndexes, bool $strict = false): array
     {
         if (empty($pageIndexes)) {
             return [];

src/Geometry/BBox.php

@@ -83,9 +83,9 @@ public function getMaxY(): float
     /**
      * Extends the BBox with the provided points.
      *
-     * @param array|Polygon $points Series of points to add to the BBox.
+     * @param array<Point>|Polygon $points Series of points to add to the BBox.
      */
-    public function extendWith(Polygon|array $points): void
+    public function extendWith(array|Polygon $points): void
     {
         if ($points instanceof Polygon) {
             $sequence = $points->getCoordinates();