🔧 Enhance Type Safety and Code Quality with PHPStan Level 4 Improvements #380

anilkumarthakur60 · 2025-05-25T09:16:38Z

This PR upgrades the codebase to PHPStan level 4, significantly improving static analysis, type safety, and overall code clarity. Key changes include:

✅ Summary of Changes:

Replaced phpstan/phpstan with larastan/larastan for better Laravel integration.
Raised PHPStan level to 4 and updated phpstan.neon configuration.
Improved type annotations throughout:
- Method docblocks (@param, @return, @var) with explicit types (e.g. Collection<int, Media>)
- Refined PHP type hints in method signatures.
- Added @throws annotations where exceptions are expected.
Modernized some property and method definitions (e.g., visibility, return types).
Cleaned up unnecessary use statements and improved PSR compliance.

These changes are non-breaking and aim to improve maintainability and developer confidence through enhanced static analysis.

Let me know if any adjustments are needed!

- Replaced `phpstan/phpstan` with `larastan/larastan` in `composer.json`. - Updated PHPStan configuration in `phpstan.neon` to include Larastan extensions and increased analysis level to 2. - Added PHPStan ignore comments in `ImageManipulator.php` for specific lines. - Refactored return types and method signatures in `Media.php` and `Mediable.php` for better type safety. - Enhanced `MediableCollection` methods to accept array|string for tags. - Added new media loading methods in `SampleMediable.php` for better tag handling.

- Increased PHPStan analysis level from 2 to 3 in `phpstan.neon`. - Enhanced type annotations in `ImportMediaCommand.php` and `CreateImageVariants.php` for better type safety, specifying `Collection<int, Media>` for existing media collections and models.

…files - Increased PHPStan analysis level from 3 to 4 in `phpstan.neon`. - Added an ignore error rule for unused traits in PHPStan configuration. - Improved type annotations in `HandlesMediaUploadExceptions.php`, `ImageManipulator.php`, `Media.php`, and `MediaUploader.php` for better type safety. - Refactored method signatures to include return types and exception documentation. - Updated visibility modifiers for class constants in `MediaUploader.php` and `StreamAdapter.php`.

Introduced a driver check to skip tests when format conversion isn't supported under the current configuration. Updated ImageManipulator to dynamically select between 'gd' and 'imagick' drivers based on availability. This ensures compatibility and prevents test failures in unsupported environments.

frasmage

This is great! though a few changes are needed

src/Commands/ImportMediaCommand.php

src/ImageManipulator.php

src/Media.php

src/MediaUploader.php

src/SourceAdapters/SourceAdapterFactory.php

tests/Mocks/SampleMediable.php

Apply fixes from StyleCI

frasmage · 2025-05-27T01:18:35Z

config/mediable.php

+            '^https?://'       => Plank\Mediable\SourceAdapters\RemoteUrlAdapter::class,
+            '^/'               => Plank\Mediable\SourceAdapters\LocalPathAdapter::class,
+            '^[a-zA-Z]:\\\\'   => Plank\Mediable\SourceAdapters\LocalPathAdapter::class,


style nit: looks like you reformated the whole codebase? I don't mind many of the changes (e.g. various newlines), but please don't align variables/params/array values/annotations. That's not part of the PSR-12 recommendation and means every new could require reformatting the whitespace of all other lines.

Might I recommend keeping this PR focused on phpstan compatibility and performing formatting changes in another PR, if desired? This PR is now 1.5k lines which makes it much harder to review

Condensed conditional statements for better readability and updated PHPStan annotations for Intervention Image compatibility. Added missing exception annotations to methods and loosened type constraints in `SourceAdapterFactory` for flexibility.

Updated type declarations for better consistency and clarified parameter order in `makeVariantOf`. Simplified `if` condition in `ImageManipulator` and removed redundant newlines in `MediaUploader`. These changes improve readability and maintainability.

frasmage

Went through with a fine toothed comb. Just a handful of nits to cleanup (and one merge conflict), then it should be looking good

frasmage · 2025-05-29T22:48:38Z

src/ImageManipulator.php

    private function imageToStream(
        Image $image,
        string $outputFormat,
        int $outputQuality
    ) {
-        if (class_exists(StreamCommand::class)) {
+        if (class_exists(Intervention\Image\Commands\StreamCommand::class)) {


I believe there should be a leading \ on this FQCN

frasmage · 2025-05-29T22:49:08Z

src/Jobs/CreateImageVariants.php

@@ -21,7 +21,7 @@ class CreateImageVariants implements ShouldQueue
     */
    private array $variantNames;
    /**
-     * @var Collection<Media>
+     * @var Collection<int, Media>


Suggested change

* @var Collection<int, Media>

* @var Collection<Media>

or array-key

frasmage · 2025-05-29T22:49:28Z

src/Jobs/CreateImageVariants.php

@@ -32,7 +32,7 @@ class CreateImageVariants implements ShouldQueue

    /**
     * CreateImageVariants constructor.
-     * @param Media|Collection|Media[] $models
+     * @param Media|Collection<int, Media>|Media[] $models


Suggested change

* @param Media|Collection<int, Media>|Media[] $models

* @param Media|Collection<Media>|Media[] $models

frasmage · 2025-05-29T22:54:02Z

src/Mediable.php

+        if (
+            static::hasGlobalScope(SoftDeletingScope::class)


style nit: no newline after if

frasmage · 2025-05-29T23:32:13Z

src/Mediable.php

@@ -628,7 +630,8 @@ public function load($relations)
            $relations = func_get_args();
        }

-        if (array_key_exists('media', $relations)
+        if (


style nit: no newline after if

frasmage · 2025-05-29T23:37:15Z

src/ImageManipulator.php

@@ -142,6 +145,7 @@ public function createImageVariant(
            $image = $this->imageManager->read($media->contents());
        } else {
            // Intervention Image <3.0
+            /** @phpstan-ignore-next-line */


switch to @phpstan-ignore <error type>

frasmage · 2025-05-29T23:37:50Z

src/ImageManipulator.php

-            && $variant->getDiskPath() === $originalVariant->getDiskPath()
-        ) {
+    ): void {
+        if ($originalVariant && $variant->disk === $originalVariant->disk && $variant->getDiskPath() === $originalVariant->getDiskPath()) {


style nit: please don't change the multiline codestyle

frasmage · 2025-05-29T23:38:16Z

src/ImageManipulator.php

            // Intervention Image  <3.0
+            /** @phpstan-ignore-next-line */


switch to @phpstan-ignore

frasmage · 2025-05-29T23:53:32Z

src/Media.php

-        if (static::hasGlobalScope(SoftDeletingScope::class)
-            && (!property_exists($this, 'forceDeleting') || !$this->forceDeleting)
-        ) {
+        if (static::hasGlobalScope(SoftDeletingScope::class) && (!property_exists($this, 'forceDeleting') || !$this->forceDeleting)) {


style nit: please don't change the multiple line conditional style

frasmage · 2025-05-29T23:54:44Z

src/MediaUploader.php

-        if (empty($this->config['image_manipulation'])
-            || $model->aggregate_type !== Media::TYPE_IMAGE
-        ) {
+        if (empty($this->config['image_manipulation'])|| $model->aggregate_type !== Media::TYPE_IMAGE) {


style nit: please don't change the multiple line conditional style

anilkumarthakur60 added 8 commits May 25, 2025 09:13

Update automated test workflow to include Imagick extension for PHP

d529915

test and ci reverted

8cf8648

fix: minor changes [skip ci]

c142416

styleci fixes

73846d7

frasmage reviewed May 26, 2025

View reviewed changes

anilkumarthakur60 and others added 7 commits May 26, 2025 20:42

fix: update PHPDoc types and improve error handling

fb6939d

Apply fixes from StyleCI

288a94f

test fixes

2d6b953

Merge branch 'phpstan-level-4-fixes' into analysis-W6BQ9y

cab0439

Merge pull request #2 from anilkumarthakur60/analysis-W6BQ9y

e31f38a

Apply fixes from StyleCI

fix: update migration class syntax and improve PHPDoc comments

61bf6a1

dock block fixes

0f71ba3

frasmage reviewed May 27, 2025

View reviewed changes

anilkumarthakur60 added 4 commits May 27, 2025 08:07

fix: update PHPDoc types and improve error handling

972e32f

commit reverted

1fac4a8

anilkumarthakur60 marked this pull request as draft May 27, 2025 13:21

frasmage reviewed May 29, 2025

View reviewed changes

	* @param Media\|Collection<int, Media>\|Media[] $models
	* @param Media\|Collection<Media>\|Media[] $models

🔧 Enhance Type Safety and Code Quality with PHPStan Level 4 Improvements #380

Are you sure you want to change the base?

🔧 Enhance Type Safety and Code Quality with PHPStan Level 4 Improvements #380

Uh oh!

Conversation

anilkumarthakur60 commented May 25, 2025

✅ Summary of Changes:

Uh oh!

frasmage left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frasmage left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frasmage May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

frasmage May 29, 2025 •

edited

Loading