fix a LOT of issues, but not all of them

Author: sebastianMindee

composer.json

@@ -34,6 +34,7 @@
   ],
   "scripts": {
     "lint": "php-cs-fixer fix --dry-run --diff",
+    "phpstan": "phpstan analyse src --level max",
     "format": "php-cs-fixer fix"
   }
 }

src/Dependency/DependencyChecker.php

@@ -93,7 +93,7 @@ public static function isImageMagickPolicyAllowed(): void
         $imagick = new Imagick();
         try {
             $imagick->readImage(
-            /** @phpstan-ignore-next-line */
+                /** @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,mixed>|null API details field as sent by the server.
      */
-    public $apiDetails;
+    public mixed $apiDetails;
     /**
-     * @var string|mixed|null API message field as sent by the server.
+     * @var string|array<string,mixed>|null API message field as sent by the server.
      */
-    public ?string $apiMessage;
+    public mixed $apiMessage;
 
     /**
-     * @param array $httpError Array containing the error data.
+     * @param array<string,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,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(mixed $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|boolean $response Raw server response.
      */
-    public static function handleError(string $url, $response): self
+    public static function handleError(string $url, mixed $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

@@ -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> $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,9 +207,8 @@ 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.%s_page%d-%d.%s', $filename ?? $this->filename, $format, $pageIndex, $index, $format);
         return new ExtractedImage($extractedImageData, $filename, $format, $pageIndex, $index);
     }
 
@@ -264,16 +265,15 @@ public function getInputSource(): LocalInputSource
     /**
      * Extracts images from a page.
      *
-     * @param array $fields List of Fields to extract.
+     * @param array<BaseField> $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;

src/Geometry/BBoxUtils.php

@@ -30,7 +30,7 @@ public static function generateBBoxFromPolygon(Polygon $polygon): ?BBox
     /**
      * Generates a BBox from an array of polygons. Returns null if no polygons are provided.
      *
-     * @param array $polygons Series of polygons to get the BBox of.
+     * @param array<Polygon> $polygons Series of polygons to get the BBox of.
      */
     public static function generateBBoxFromPolygons(array $polygons): ?BBox
     {
@@ -39,7 +39,7 @@ public static function generateBBoxFromPolygons(array $polygons): ?BBox
         }
         $merged = $polygons[0];
         foreach ($polygons as $polygon) {
-            if ($polygon && $merged !== $polygon) {
+            if ($merged !== $polygon) {
                 $merged = PolygonUtils::merge($merged, $polygon);
             }
         }
@@ -54,7 +54,7 @@ public static function generateBBoxFromPolygons(array $polygons): ?BBox
     /**
      * Merges an array of bboxes.
      *
-     * @param array $bboxes BBoxes to merge.
+     * @param array<BBox> $bboxes BBoxes to merge.
      */
     public static function mergeBBoxes(array $bboxes): ?BBox
     {

src/Geometry/MinMaxUtils.php

@@ -17,11 +17,14 @@ class MinMaxUtils
     /**
      * Retrieves the upper and lower bounds of the y-axis from an array of points.
      *
-     * @param array $points An array of points.
+     * @param array<Point>|Polygon $points An array of points.
      * @throws MindeeGeometryException Throws if the provided array is too small.
      */
-    public static function getMinMaxY(array $points): MinMax
+    public static function getMinMaxY(mixed $points): MinMax
     {
+        if (is_a(Polygon::class, $points)) {
+            $points = $points->getCoordinates();
+        }
         if (count($points) < 1) {
             throw new MindeeGeometryException(
                 'The provided point array must have at least 1 point to calculate the Y bounds.',
@@ -38,11 +41,14 @@ public static function getMinMaxY(array $points): MinMax
     /**
      * Retrieves the upper and lower bounds of the x-axis from an array of points.
      *
-     * @param array $points An array of points.
+     * @param array<Point>|Polygon $points An array of points.
      * @throws MindeeGeometryException Throws if the provided array is too small.
      */
-    public static function getMinMaxX(array $points): MinMax
+    public static function getMinMaxX(mixed $points): MinMax
     {
+        if (is_a(Polygon::class, $points)) {
+            $points = $points->getCoordinates();
+        }
         if (count($points) < 1) {
             throw new MindeeGeometryException(
                 'The provided point array must have at least 1 point to calculate the X bounds.',

src/Geometry/Point.php

@@ -5,10 +5,13 @@
 namespace Mindee\Geometry;
 
 use ArrayAccess;
+use BadMethodCallException;
 use InvalidArgumentException;
 
 /**
  * Representation of the coordinates of a point.
+ *
+ * @implements ArrayAccess<int, float>
  */
 class Point implements ArrayAccess
 {
@@ -101,12 +104,6 @@ public function offsetSet($offset, $value): void
      */
     public function offsetUnset($offset): void
     {
-        if ($offset === 0) {
-            $this->x = null;
-        } elseif ($offset === 1) {
-            $this->y = null;
-        } else {
-            throw new InvalidArgumentException("Use 0 for X or 1 for Y");
-        }
+        throw new BadMethodCallException("Cannot unset coordinates of a Point.");
     }
 }

src/Geometry/Polygon.php

@@ -12,7 +12,7 @@
 class Polygon
 {
     /**
-     * @var Point[]|null Vertices of the polygon.
+     * @var array<Point>|null Vertices of the polygon.
      */
     public ?array $coordinates;
 
@@ -27,7 +27,7 @@ class Polygon
     private MinMax $minMaxX;
 
     /**
-     * @param array|null $coordinates Coordinates of the polygon as a set of Points.
+     * @param array<array<float|integer>>|null $coordinates Coordinates of the polygon as a set of Points.
      */
     public function __construct(?array $coordinates = null)
     {
@@ -146,7 +146,7 @@ public function isEmpty(): bool
 
     /**
      * Retrieves the coordinates of the polygon.
-     *
+     * @return array<Point>|null Coordinates of the polygon.
      */
     public function getCoordinates(): ?array
     {