Release 12.0.2

Author: MarcinOrlowski

.github/workflows/coverage.yml

@@ -28,7 +28,7 @@ jobs:
       matrix:
         # quotes are needed it is treated as a number and zero at decimal part is gone
         # at runtime i.e. 8.10 -> 8.1, while "8.10" => "8.10".
-        laravel: ["11.0"]
+        laravel: ["12.0"]
         php: ["8.2"]
 
     runs-on: ubuntu-latest

.github/workflows/phpstan.yml

@@ -14,26 +14,73 @@ name: "Static Analysis"
 on:
   push:
     branches:
-    - "master"
+      - "master"
   pull_request:
     branches:
-    - "master"
-    - "dev"
+      - "master"
+      - "dev"
 
 jobs:
+  analyze_sources:
+    name: "Is there any source code to work on?"
+    runs-on: ubuntu-latest
+
+    outputs:
+      # Export 'filter' step check result so next step can use it.
+      run_action: ${{ steps.filter.outputs.src }}
+      # These are source files matching our filter that are affected by the PR.
+      changed_files: ${{ steps.filter.outputs.src_files }}
+
+    steps:
+      # https://github.com/marketplace/actions/checkout
+      - name: "Checkout sources"
+        uses: actions/checkout@v4
+
+      # https://github.com/marketplace/actions/paths-changes-filter
+      - name: "Look for changes that matters for us..."
+        uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          # Token is optional for public repos, but required for private repos
+          token: ${{ secrets.GITHUB_TOKEN }}
+          list-files: 'escape'
+          filters: |
+            src:
+              - 'src/**/*.php'
+              - 'tests/**/*.php'
+
+      - name: "Will action step be run?"
+        run: |
+          found="NO"
+          [[ ${{ steps.filter.outputs.src }} == 'true' ]] && found="YES"
+          echo "run_action=${found}" >> $GITHUB_OUTPUT
+          echo -e "\n****************************************\n"
+          echo "${found}"
+          echo -e "****************************************"
+
   check:
+    # Will run only if analyze_sources determined it is needed.
+    needs: analyze_sources
+    if: needs.analyze_sources.outputs.run_action == 'true'
+
     strategy:
       # do not stop the workflow if single run failed
       fail-fast: false
       matrix:
-        # quotes are needed it is treated as a number and zero at decimal part is gone
+        # Quotes are needed it is treated as a number and zero at decimal part is gone
         # at runtime i.e. 8.10 -> 8.1, while "8.10" => "8.10".
-        laravel: ["11.0"]
-        php: ["8.2"]
+        php: [ "8.2" ]
 
     runs-on: ubuntu-latest
 
     steps:
+      # https://github.com/marketplace/actions/setup-php-action
+      - name: "Setup PHP ${{ matrix.php }}"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "${{ matrix.php }}"
+
+      # https://github.com/marketplace/actions/checkout
       - name: "Checkout repository..."
         uses: actions/checkout@v4
 
@@ -45,18 +92,6 @@ jobs:
           php_version: "${{ matrix.php }}"
           dev: yes
 
-      # # https://github.com/marketplace/actions/phpstan-php-actions
-      # - name: "Running PHPStan..."
-      #   uses: php-actions/phpstan@v3
-      #   with:
-      #     configuration: "phpstan.neon"
-      #     php_version: "${{ matrix.php }}"
-      #     # memory_limit: "16M"
-
-      # - name: "Making cache folder writable"
-      #   shell: bash
-      #   run: chmod 777 vendor/orchestra/testbench-core/laravel/bootstrap/cache
-
       - name: "Running PHPStan..."
         shell: bash
-        run: vendor/bin/phpstan
+        run: composer lint

.pre-commit-config.yaml

@@ -0,0 +1,83 @@
+##################################################################################
+#
+# Laravel API Response Builder PHPStan config file
+#
+# @author    Marcin Orlowski <mail (#) marcinOrlowski (.) com>
+# @copyright 2016-2025 Marcin Orlowski
+# @license   http://www.opensource.org/licenses/mit-license.php MIT
+# @link      https://github.com/MarcinOrlowski/laravel-api-response-builder
+#
+##################################################################################
+#
+# Using pre-commit hooks #
+#
+# To improve quality of your commit, it's recommended to use "pre-commit"
+# (http://pre-commit.com) hooks, that will block  your commits unless all tests
+# pass. This project comes with template configuration file
+# `.pre-commit-config.yaml.dist`.
+#
+# Brief installation instruction:
+#
+# * Ensure you got Python installed
+# * Install pre-commit: `pip install pre-commit`
+# * Go to your Logisim-evolution source code root directory
+# * Copy provided config file template: `cp .pre-commit-config.yaml.dist .pre-commit-config.yaml`
+# * Plug hooks into Git pipeline: `pre-commit install`
+#
+# See `pre-commit` official installation docs too: https://pre-commit.com/#install
+#
+# To see how pre-commit identifies given file (i.e. for 'exclude_type' config) use `identify-cli <FILE>`
+#
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Prevent giant files from being committed
+      - id: check-added-large-files
+        args: [ '--maxkb=1555550' ]
+      # This hook checks yaml files for parseable syntax
+      - id: check-yaml
+      # Check for files that would conflict in case-insensitive filesystems
+      - id: check-case-conflict
+      # Ensures that (non-binary) executables have a shebang.
+      - id: check-executables-have-shebangs
+      # Check for files that contain merge conflict strings
+      - id: check-merge-conflict
+      # Prevent addition of new git submodules
+      - id: forbid-new-submodules
+      # Replaces or checks mixed line ending
+      - id: mixed-line-ending
+        args: [ '--fix=no' ]
+
+  - repo: https://github.com/jumanjihouse/pre-commit-hooks
+    rev: 3.0.0
+    hooks:
+      # Non-executable shell script filename ends in .sh
+      - id: script-must-have-extension
+
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.5
+    hooks:
+      # Forbid files containing CRLF end-lines to be committed
+      - id: forbid-crlf
+        exclude: \.svg$
+
+  - repo: https://github.com/MarcinOrlowski/pre-commit-hooks
+    rev: 1.3.1
+    hooks:
+      # This hook trims trailing whitespace.
+      - id: trailing-whitespaces
+        exclude_types: [ 'binary', 'xml', 'png', 'jpeg', 'pdf', 'svg' ]
+        args: [ '--markdown-linebreak-ext=md', '--fix=yes' ]
+      # Ensures that a file is either empty, or ends with one newline
+      - id: end-of-file
+        exclude_types: [ 'binary', 'xml', 'png', 'jpeg', 'pdf', 'svg' ]
+        args: [ '--fix=yes' ]
+
+  - repo: https://github.com/digitalpulp/pre-commit-php.git
+    rev: 1.4.0
+    hooks:
+      # Runs PHPStan analyser
+      - id: php-stan
+        files: \.(php)$

composer.json

@@ -2,7 +2,7 @@
   "name": "marcin-orlowski/laravel-api-response-builder",
   "description": "Helps building nice, normalized and easy to consume Laravel REST API.",
   "homepage": "https://github.com/MarcinOrlowski/laravel-api-response-builder",
-  "version": "12.0.1",
+  "version": "12.0.2",
   "keywords": [
     "laravel",
     "laravel10",
@@ -63,7 +63,7 @@
     ],
     "lint": [
       "Composer\\Config::disableProcessTimeout",
-      "vendor/bin/phpstan analyse --no-progress --no-interaction -c phpstan.neon"
+      "vendor/bin/phpstan analyse --no-progress --no-interaction src/"
     ],
     "mdlint": [
       "Composer\\Config::disableProcessTimeout",

docs/CHANGES.md

@@ -18,6 +18,12 @@ should be able to easily backport future new features to older versions rather e
 
 ## CHANGE LOG ##
 
+* v12.0.2 (2025-07-10)
+  * [GH-263] Fixed `Validator::assertIsType()` not validating provided exception class against `InvalidTypeExceptionContract`.
+  * [GH-263] Added unit tests for `Validator::assertIsType()`.
+  * [GH-265] Fixed PHP 8.4 deprecation `Implicitly nullable parameters...` (reporeted by @technetius)
+  * Fixed typehints to make PHPStan green on `max` sensitivity level.
+
 * v12.0.1 (2025-04-16)
   * [RB-255] Fixed `ToArrayConverter` using a new Request instance instead of the actual request.
   * [BR-256] Fixed `ToArrayConverter` potentially causing fatal error if object lacks `toArray` method.

phpstan.neon

@@ -12,9 +12,8 @@
 includes:
   - vendor/larastan/larastan/extension.neon
 parameters:
-  checkGenericClassInNonGenericObjectType: false
   level: max
-  checkMissingIterableValueType: false
+  treatPhpDocTypesAsCertain: false
   paths:
     - src/
     - tests/

src/ApiCodesHelpers.php

@@ -59,6 +59,8 @@ public static function getMaxCode(): int
 
     /**
      * Returns array of error code constants defined in this class. Used mainly for debugging/tests
+     *
+     * @return array<string, mixed>
      */
     public static function getApiCodeConstants(): array
     {
@@ -69,6 +71,7 @@ public static function getApiCodeConstants(): array
     /**
      * Returns complete error code to locale string mapping array
      *
+     * @return array<int, string>
      * @throws Ex\IncompatibleTypeException
      * @throws Ex\InvalidTypeException
      * @throws Ex\MissingConfigurationKeyException Thrown when builder map is not configured.
@@ -83,8 +86,10 @@ public static function getMap(): array
         }
         Validator::assertIsArray(RB::CONF_KEY_MAP, $user_map);
 
-        /** @var array $user_map */
-        return Util::mergeConfig(BaseApiCodes::getBaseMap(), $user_map);
+        /** @var array<int, string> $user_map */
+        $result = Util::mergeConfig(BaseApiCodes::getBaseMap(), $user_map);  // @phpstan-ignore-line
+        /** @var array<int, string> $result */
+        return $result;
     }
 
     /**
@@ -108,7 +113,7 @@ public static function getCodeMessageKey(int $api_code): ?string
 
         $map = static::getMap();
 
-        return $map[ $api_code ] ?? null;
+        return $map[$api_code] ?? null;
     }
 
     /**

src/ApiResponse.php

@@ -22,10 +22,11 @@ protected function __construct()
 
     public static function fromJson(string $jsonString): self
     {
-        /** @var array $decoded_json */
+        /** @var array<string, mixed> $decoded_json */
         $decoded_json = \json_decode($jsonString, true, 32, JSON_THROW_ON_ERROR);
 
         // Ensure all response elements are present.
+        /** @var array<string, array<string>> $keys */
         $keys = [
             ResponseBuilder::KEY_SUCCESS => [Type::BOOLEAN],
             ResponseBuilder::KEY_CODE    => [Type::INTEGER],
@@ -37,11 +38,7 @@ public static function fromJson(string $jsonString): self
             if (!\array_key_exists($key, $decoded_json)) {
                 throw new \InvalidArgumentException("Missing key '$key' in JSON response.");
             }
-            /** @var mixed|null $allowed_types */
-            if (!empty($allowed_types)) {
-                /** @var array $allowed_types */
-                Validator::assertIsType($key, $decoded_json[ $key ], $allowed_types);
-            }
+            Validator::assertIsType($key, $decoded_json[$key], $allowed_types);
         }
 
         // Ensure certain elements are not empty.
@@ -57,16 +54,29 @@ public static function fromJson(string $jsonString): self
                 "The '{$key}' in JSON response cannot be NULL.");
         }
 
+        /** @var bool $success */
+        $success = $decoded_json[ResponseBuilder::KEY_SUCCESS];
+        /** @var int $code */
+        $code = $decoded_json[ResponseBuilder::KEY_CODE];
+        /** @var string $message */
+        $message = $decoded_json[ResponseBuilder::KEY_MESSAGE];
+        /** @var string $locale */
+        $locale = $decoded_json[ResponseBuilder::KEY_LOCALE];
+        /** @var array<string, mixed>|null $data */
+        $data = $decoded_json[ResponseBuilder::KEY_DATA];
+
         $api = (new self())
-            ->setSuccess($decoded_json[ ResponseBuilder::KEY_SUCCESS ])
-            ->setCode($decoded_json[ ResponseBuilder::KEY_CODE ])
-            ->setMessage($decoded_json[ ResponseBuilder::KEY_MESSAGE ])
-            ->setLocale($decoded_json[ ResponseBuilder::KEY_LOCALE ])
-            ->setData($decoded_json[ ResponseBuilder::KEY_DATA ]);
+            ->setSuccess($success)
+            ->setCode($code)
+            ->setMessage($message)
+            ->setLocale($locale)
+            ->setData($data);
 
         // Optional debug data
         if (\array_key_exists(ResponseBuilder::KEY_DEBUG, $decoded_json)) {
-            $api->setDebug($decoded_json[ ResponseBuilder::KEY_DEBUG ]);
+            /** @var array<string, mixed>|null $debug */
+            $debug = $decoded_json[ResponseBuilder::KEY_DEBUG];
+            $api->setDebug($debug);
         }
 
         return $api;
@@ -134,13 +144,20 @@ protected function setLocale(string $locale): self
 
     // ---------------------------------------------------------------------------------------------
 
+    /** @var array<string, mixed>|null */
     protected ?array $data;
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function getData(): ?array
     {
         return $this->data;
     }
 
+    /**
+     * @param array<string, mixed>|null $data
+     */
     protected function setData(?array $data): self
     {
         $this->data = $data;
@@ -149,13 +166,20 @@ protected function setData(?array $data): self
 
     // ---------------------------------------------------------------------------------------------
 
+    /** @var array<string, mixed>|null */
     protected ?array $debug = null;
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function getDebug(): ?array
     {
         return $this->debug;
     }
 
+    /**
+     * @param array<string, mixed>|null $debug
+     */
     public function setDebug(?array $debug): self
     {
         $this->debug = $debug;

src/BaseApiCodes.php

@@ -90,6 +90,7 @@ class BaseApiCodes
 	/**
 	 * Returns base code mapping array
 	 *
+	 * @return array<int, string>
 	 * @throws Ex\InvalidTypeException
 	 * @throws Ex\MissingConfigurationKeyException
 	 * @throws Ex\NotIntegerException

src/Contracts/ConverterContract.php

@@ -17,8 +17,9 @@ interface ConverterContract
      * Returns array representation of the object.
      *
      * @param object $obj    Object to be converted
-     * @param array  $config Converter config array to be used for this object (based on exact class
+     * @param array<string, mixed>  $config Converter config array to be used for this object (based on exact class
      *                       name match or inheritance).
+     * @return array<string, mixed>
      */
     public function convert(object $obj, array $config): array;