Phar Laravel Package

Getting Started

1. Install via Composer: Run composer require --dev psalm/phar. This installs Psalm as a PHAR without polluting your project’s Composer dependencies—ideal for avoiding version conflicts with other tools (e.g., PHPStan, PHP CS Fixer).
2. Run Psalm: Execute vendor/bin/psalm (or ./vendor/psalm/phar/psalm.phar if PHAR is auto-registered). The first run will scan your codebase and output issues.
3. Initial config: Generate a baseline or config with vendor/bin/psalm --init. This creates psalm.xml to configure error levels, custom stubs, and baseline files.

Implementation Patterns

• CI Integration: Add ./vendor/bin/psalm --output-format=checkstyle > psalm-report.xml to your CI pipeline (e.g., GitHub Actions, GitLab CI) for static analysis reports.
• Pre-commit Hook: Use vendor/bin/psalm --diff --output-format=diff in a pre-commit hook to prevent introducing new issues.
• Baseline-Driven Development: Run vendor/bin/psalm --set-baseline=psalm-baseline.xml to lock current issues, then incrementally fix them while keeping CI green.
• PHAR-Only Environments: Perfect for servers or containers where installing extensions or global PHARs is restricted—just rely on Composer-managed PHAR.

Gotchas and Tips

• PHP Version Requirement: Requires PHP 8.2+ (per composer.json). Do not use in legacy projects running PHP 7.4/8.0—upgrade PHP first or use vimeo/psalm (non-PHAR) instead.
• Stale PHAR: Last release was 2021-08-09. The PHAR may lag behind vimeo/psalm’s main branch (Psalm now recommends vimeo/psalm via Composer or PHAR download). Verify features like plugin support or PHP 8.2+ syntax parsing in your target Psalm version.
• Autoloading & Paths: Psalm scans relative to the config file (psalm.xml). Ensure psalm.xml is in your project root and your autoload-dev is correctly configured (or use --root flag).
• Plugins/Config: Custom plugins or advanced config (e.g., error handlers, stubs) require explicit inclusion via <stubs>/<plugins> in psalm.xml. PHAR does not auto-detect project plugins unless referenced.
• PHAR Verification: Always verify PHAR integrity if downloading manually—though composer require handles this, manual downloads may need phar.verify = On in php.ini.