valkyrja/psalm

Psalm for the Valkyrja Project.

v26.1.4 2026-04-17 02:41 UTC

Requires

• php: >=8.4
• vimeo/psalm: ^6.16.1

MIT

• Melech Mizrachi

• ci
• valkyrja
• psalm

README

Valkyrja Psalm

Shared Psalm configuration for Valkyrja PHP projects — a reference configuration and reusable workflow that enforce consistent static analysis across consuming repositories.

Usage

Place a psalm.xml in your CI directory pointing to the project source. Run via the root Composer scripts:

# Check only (no shepherd, no cache cleared)
composer psalm

# Check with no cache
composer psalm-no-cache

# Post results to Psalm Shepherd
composer psalm-shepherd

# Post results with stats to Psalm Shepherd
composer psalm-shepherd-with-stats

# Show type coverage stats
composer psalm-stats

# Update the baseline file
composer psalm-update-baseline

Configuration

The CI directory ships with a psalm.xml that serves as the reference configuration. Key settings:

Setting	Value	Effect
errorLevel	1	Strictest level — all issues reported
totallyTyped	true	Every expression must be typed
findUnusedBaselineEntry	true	Warns when a baseline suppression is no longer needed
findUnusedCode	false	Dead-code detection disabled
errorBaseline	psalm-baseline.xml	Known issues tracked in baseline; update with composer psalm-update-baseline

Scanned Paths

Path	Included
src/	Yes
vendor/	No

Suppressed Issue Types

These issue types are suppressed globally via <issueHandlers>:

Issue	Reason
PropertyNotSetInConstructor	Properties initialised outside constructors are common in the framework
DeprecatedClass	Suppressed temporarily while the Env class deprecation is in progress
ClassMustBeFinal	Framework classes are intentionally left non-final for extensibility
RedundantPropertyInitializationCheck	False positives triggered by ??= assignments
UnsafeInstantiation	Child class constructor parameter matching is left to the developer

Notes

• PSALM_ALLOW_XDEBUG=1 is set in CI as a workaround for a JIT interaction with the #[Override] attribute. See vimeo/psalm#11723.
• An autoload.php is required in the CI directory to bootstrap the project autoloader before Psalm analyses the source.

Workflows

The _workflow-call.yml reusable workflow runs Psalm against the calling repository's source. It is designed to be called from other repositories via workflow_call.

Inputs

Input	Type	Default	Description
paths	string	—	Required. YAML filter spec with two keys: ci (CI config files that trigger a base-branch fetch) and files (all files that trigger the check).
post-pr-comment	boolean	true	Post a PR comment on failure and remove it on success. Disable when the calling workflow handles its own reporting.
composer-options	string	''	Extra flags passed to every composer install step (e.g. --ignore-platform-req=ext-openswoole).
php-version	string	'8.4'	PHP version to use.
ci-directory	string	'.github/ci/psalm'	Path to the CI directory containing composer.json and the tool config.
extensions	string	'mbstring, intl'	PHP extensions to install via shivammathur/setup-php.
additional-directory	string	''	Path to an additional Composer dependencies directory to install before running Psalm. Leave empty to skip.
run-script	string	'psalm'	Composer script to run (e.g. psalm, psalm-shepherd, psalm-shepherd-with-stats).

Usage

jobs:
  psalm:
    uses: valkyrjaio/ci-psalm-php/.github/workflows/_workflow-call.yml@26.x
    permissions:
      pull-requests: write
      contents: read
    with:
      php-version: '8.4'
      run-script: 'psalm-shepherd-with-stats'
      paths: |
        ci:
          - '.github/ci/psalm/**'
          - '.github/workflows/psalm.yml'
        files:
          - '.github/ci/psalm/**'
          - '.github/workflows/psalm.yml'
          - 'src/**/*.php'
          - 'composer.json'
    secrets: inherit

secrets: inherit is required to pass the VALKYRJA_GHA_APP_ID and VALKYRJA_GHA_PRIVATE_KEY org secrets used for PR comments.

Contributing

See CONTRIBUTING.md for the submission process and VOCABULARY.md for the terminology used across Valkyrja.

Security Issues

If you discover a security vulnerability, please follow our disclosure procedure.

License

Licensed under the MIT license. See LICENSE.md.