Psalm Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev vimeo/psalm
   

   Initialize Psalm with default config:

   vendor/bin/psalm --init
   

   This generates a psalm.xml in your project root.

2. First Run:

   vendor/bin/psalm
   

   Analyze specific files:

   vendor/bin/psalm src/Controller/UserController.php
   

3. Key Configurations:

   • Edit psalm.xml to define:

     <projectFiles>
         <directory name="src" />
         <directory name="app" />
     </projectFiles>
     

   • Set PHP version:

     <phpVersion>8.1</phpVersion>
     

4. First Use Case: Run Psalm in CI/CD pipelines to catch type errors early:

   # .github/workflows/psalm.yml
   jobs:
     psalm:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - run: composer install
         - run: vendor/bin/psalm --no-cache
   

Implementation Patterns

Daily Workflow

1. Pre-Commit Hook:

   composer require --dev php-parallel-lint/php-parallel-lint
   composer require --dev dealerdirect/phpcodesniffer-composer-installer
   

   Add to composer.json:

   "scripts": {
     "test": [
       "@phpcs",
       "@psalm"
     ]
   }
   

   Create .php-cs-fixer.dist.php and .phpcs.xml for linting.

2. Incremental Analysis: Use --diff for faster local runs:

   vendor/bin/psalm --diff
   

3. Team Integration:

   • Use --shepherd to track type coverage in Shepherd.
   • Configure psalm.xml to ignore tests:

     <ignoreFiles>
         <directory name="tests" />
     </ignoreFiles>
     

4. Custom Rules: Extend Psalm with custom rules by creating a Ruleset class:

   // src/Rules/NoHardcodedUrlsRule.php
   namespace App\Rules;
   
   use Psalm\Plugin\Ruleset\Ruleset;
   
   class NoHardcodedUrlsRule extends Ruleset {
       public function getRules(): array {
           return [
               NoHardcodedUrls::class,
           ];
       }
   }
   

   Register in psalm.xml:

   <pluginClass>App\Rules\NoHardcodedUrlsRule</pluginClass>
   

5. Fixing Issues: Use psalter to auto-fix common issues:

   vendor/bin/psalter --issues=MissingReturnType --dry-run
   

Gotchas and Tips

Common Pitfalls

1. False Positives:

   • Suppress warnings with @psalm-suppress:

     /** @psalm-suppress MixedReturnStatement */
     function foo() {
         return $this->bar(); // bar() returns mixed
     }
     

   • Use @var annotations for dynamic types:

     /** @var array<int, string> */
     $dynamicArray = [];
     

2. Performance:

   • Cache issues with --no-cache to force a full analysis.
   • Use --threads=8 for multi-core systems (adjust based on your machine).

3. Configuration Quirks:

   • Strict Mode: Enable with <strictness>1</strictness> for stricter checks.
   • Platform Checks: Use <platform> tags to define global constants:

     <platform>
         <constant name="APP_ENV" value="local" />
     </platform>
     

   • Excluded Directories: Ensure vendor/ is excluded:

     <excludeFiles>
         <directory name="vendor" />
     </excludeFiles>
     

4. Debugging:

   • Verbose Output: Use --stats to see analysis details:

     vendor/bin/psalm --stats
     

   • Log Level: Increase verbosity with --log-level=3.

5. Refactoring Risks:

   • Always use --dry-run with psalm-refactor:

     vendor/bin/psalm-refactor --move "App\Old\*" --into "App\New\" --dry-run
     

   • Test refactored code in a staging environment before merging.

6. Plugin Limitations:

   • Custom plugins must implement Psalm\Plugin\Manipulation\Manipulation for psalter.
   • Plugins may not handle all edge cases (e.g., complex PHPDoc).

7. CI/CD Tips:

   • Cache Psalm’s storage directory between runs:

     - uses: actions/cache@v3
       with:
         path: ~/.cache/psalm
         key: ${{ runner.os }}-psalm-${{ hashFiles('**/composer.lock') }}
     

   • Fail builds on errors:

     vendor/bin/psalm || exit 1
     

8. Type Coverage:

   • Aim for 80%+ type coverage (tracked via Shepherd).
   • Use @psalm-assert for runtime assertions:

     /** @psalm-assert string $var */
     $var = $this->getString();
     

9. Legacy Code:

   • Gradually enable strictness with <strictness>0</strictness> initially.
   • Use @psalm-ignore-all for entire files if needed (last resort).

10. Edge Cases:

    • Dynamic Properties: Annotate with @property:

      class DynamicClass {
          /** @property string $dynamicProp */
      }
      

    • Magic Methods: Use @method for __call:

      class Proxy {
          /** @method string getData() */
      }