Weave Code
Psalm Tester Laravel Package
phpyh/psalm-tester
Run and compare Psalm static analysis results across versions and configurations. Handy for CI, regression checks, and testing plugin or baseline changes, with simple CLI tooling to spot new issues or verify improvements quickly.
phpyh/psalm-tester is a lightweight helper package for running and validating Psalm static analysis in a consistent, test-friendly way. It’s aimed at PHP/Laravel projects that want repeatable checks in CI and clear pass/fail signals when Psalm’s output changes.
Use it to standardize how Psalm is executed and to make static analysis results easier to assert and maintain across environments.
- Provides a simple interface to execute Psalm programmatically
- Designed for test suites/CI to verify expected analysis outcomes
- Helps keep analysis runs reproducible across machines
- Supports checking error baselines/output to catch regressions
- Lightweight setup with minimal project overhead
Frequently asked questions about Psalm Tester
- How do I integrate **phpyh/psalm-tester** into an existing Laravel project with Psalm?
- Start by requiring the package via Composer (`composer require phpyh/psalm-tester`), then configure a baseline file (e.g., `tests/PsalmBaseline.txt`) to capture initial Psalm output. Use the `PsalmTester` class in your test suite to assert expected results, like `PsalmTester::assertNoErrors()` for critical files. Ensure your `psalm.json` is already set up for Laravel’s autoloading paths.
- Can I use this package to enforce Psalm checks in CI without slowing down builds?
- Yes, the package is designed for CI efficiency. Cache Psalm’s stubs and internal directories (e.g., `vendor/psalm/`) in GitHub Actions or GitLab CI to reduce runtime. Run it as a separate job or parallelize checks using Psalm’s `--parallel` flag. For large projects, limit initial coverage to high-risk directories like `app/Http/`.
- Will this work with Laravel’s Facades or dynamic service providers that Psalm might flag?
- The package doesn’t override Psalm’s core logic, so it respects all Psalm configurations, including Facade stubs or custom rules. However, you may need to adjust your `psalm.json` to exclude or suppress false positives in dynamic Laravel features. Use `assertErrorsMatchBaseline()` to document and track expected warnings for these cases.
- How do I handle Psalm version upgrades that change error messages or rule behavior?
- Update your baseline file (`PsalmBaseline.txt`) manually when Psalm’s output format or messages change. The package provides `assertErrorsMatchBaseline()` to catch regressions, so you’ll need to re-run tests and commit the updated baseline. For automated handling, consider scripting baseline diffs or using Psalm’s `--output-format=json` for programmatic comparison.
- Can I run Psalm checks alongside Pest or PHPUnit tests in Laravel?
- Absolutely. Use the `PsalmTester` trait in your test classes alongside Pest or PHPUnit. For example, add `it('has no Psalm errors', fn() => PsalmTester::assertNoErrors(app_path('Http/Controllers/')))` to feature tests. The package integrates seamlessly with Laravel’s testing ecosystem, including test events or custom Artisan commands.
- Does this package support parallel execution for large Laravel codebases?
- While the package itself doesn’t enforce parallelism, you can combine it with Psalm’s built-in `--parallel` flag or Laravel’s queue workers to distribute checks. For CI, run Psalm in parallel jobs targeting different directories (e.g., `app/`, `app/Http/`, `app/Console/`). Cache results aggressively to minimize overhead.
- How do I gradually introduce Psalm checks to a legacy Laravel project?
- Start by configuring `psalm.json` to ignore legacy code (e.g., `exclude_files: ['old/']`) and focus on new or critical files. Use `PsalmTester::assertNoErrors()` selectively for high-priority paths, then expand coverage incrementally. Document suppressed warnings in your baseline file to avoid false failures during migration.
- Will this conflict with PHPStorm or VSCode Psalm plugins?
- No, the package is purely for programmatic execution and validation—it doesn’t interfere with IDE plugins. However, running Psalm via the package in CI or tests may trigger duplicate analysis if IDE plugins also run Psalm. Disable IDE checks during test runs or use environment-specific Psalm configurations to avoid redundancy.
- Can I use this for deployment-time validation in Laravel Forge/Envoyer?
- Yes, integrate the package into a custom Artisan command or deploy hook. For example, add a pre-deploy task in Envoyer to run `php artisan psalm:test` (if you’ve created a command) or call `PsalmTester::run()` directly. This ensures Psalm passes before code reaches production, catching type safety issues early.
- Are there alternatives to this package for Laravel Psalm integration?
- For basic Psalm execution, you can use Psalm’s CLI directly or tools like `roave/infection` for mutation testing. However, **phpyh/psalm-tester** uniquely focuses on test-driven validation and baseline comparison, which is ideal for CI/CD regression checks. If you need deeper IDE integration, consider Psalm’s native plugins, but they lack the test assertion capabilities this package provides.
Weaver
How can I help you explore Laravel packages today?