Skip to content

Add documentation for Psalm #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jcostaventureoak merged 2 commits into from
May 20, 2026
Merged

Add documentation for Psalm #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e7d7973
Update README files
jcostaventureoak May 20, 2026
21f2a80
Update order
jcostaventureoak May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@
- Though the usage of this tool is not mandatory, it is highly recommended to use it to ensure the quality of the codebase.
- Learn more about PHP_CodeSniffer at official page [here](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki).

### `Psalm`
- Psalm is a static analysis tool for PHP that helps identify bugs, type errors, and other issues in your codebase before runtime. It provides advanced type inference and can detect complex issues that other tools might miss.
- Learn more about Psalm at the official page [here](https://psalm.dev/).

### `Rector`
- Rector is a tool that automatically upgrades and refactors your PHP code. It is a tool that helps you to keep your code up-to-date and clean.
- Learn more about Rector at official page [here](https://getrector.com/documentation).
Expand Down Expand Up @@ -72,6 +76,7 @@ composer require --dev kununu/code-tools --no-plugins
- [.editorconfig](docs/EditorConfig/README.md) instructions.
- [PHP-CS-Fixer](docs/CsFixer/README.md) instructions.
- [PHP_CodeSniffer](docs/CodeSniffer/README.md) instructions.
- [Psalm](docs/Psalm/README.md) instructions.
- [Rector](docs/Rector/README.md) instructions.
- [bin/code-tools](docs/CodeTools/README.md) instructions.
- [bin/php-in-k8s](docs/PhpInK8s/README.md) instructions.
Expand Down
170 changes: 170 additions & 0 deletions docs/Psalm/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
# `Psalm` usage

## Table of Contents
- [Out of the box usage](#out-of-the-box-usage)
- [Customized usage](#customized-usage)
- [Adding stubs for external libraries](#adding-stubs-for-external-libraries)
- [Adding issue handlers](#adding-issue-handlers)
- [Using a baseline](#using-a-baseline)
- [Configuration options](#configuration-options)
- [Baseline management](#baseline-management)
- [Further resources](#further-resources)

## Out of the box usage
- The default configuration analyzes the `src` directory with error level 2 (strict).
- The `--config` flag is used to specify the configuration to be used.

### Run Psalm analysis
```console
vendor/bin/psalm --config=vendor/kununu/code-tools/dist/psalm.xml.dist
```

### Run Psalm with no cache
```console
vendor/bin/psalm --config=vendor/kununu/code-tools/dist/psalm.xml.dist --no-cache
```

## Customized usage
- You can customize the `psalm.xml` file to include/exclude directories, add stubs, configure issue handlers, or use a baseline.
- The easiest way to customize the configuration is to copy the `psalm.xml.dist` file to your project and modify it, for this we provide the following command:

```console
vendor/bin/code-tools publish:config psalm
```

- The `psalm.xml` file will be copied to your project root, and you can modify it to suit your needs.

<details>
<summary>See some customization examples</summary>

### Adding stubs for external libraries
Stubs help Psalm understand types from external libraries that lack proper type declarations:
```xml
<?xml version="1.0"?>
<psalm
errorLevel="2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="https://getpsalm.org/schema/config"
xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
>
<projectFiles>
<directory name="src"/>
<ignoreFiles>
<directory name="vendor"/>
</ignoreFiles>
</projectFiles>

<plugins>
<pluginClass class="Psalm\SymfonyPsalmPlugin\Plugin"/>
</plugins>

<stubs>
<file name="vendor/squizlabs/php_codesniffer/src/Sniffs/Sniff.php"/>
<file name="vendor/squizlabs/php_codesniffer/src/Files/File.php"/>
</stubs>
</psalm>
```

### Adding issue handlers
Suppress specific issues for certain directories or files:
```xml
<?xml version="1.0"?>
<psalm
errorLevel="2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="https://getpsalm.org/schema/config"
xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
>
<projectFiles>
<directory name="src"/>
<ignoreFiles>
<directory name="vendor"/>
</ignoreFiles>
</projectFiles>

<plugins>
<pluginClass class="Psalm\SymfonyPsalmPlugin\Plugin"/>
</plugins>

<issueHandlers>
<ClassMustBeFinal>
<errorLevel type="suppress">
<directory name="src/Sniffs"/>
</errorLevel>
</ClassMustBeFinal>
<PropertyNotSetInConstructor>
<errorLevel type="suppress">
<directory name="src/Entity"/>
</errorLevel>
</PropertyNotSetInConstructor>
</issueHandlers>
</psalm>
```

### Using a baseline
Baselines allow you to suppress existing issues while enforcing strict analysis on new code:
```xml
<?xml version="1.0"?>
<psalm
errorLevel="2"
errorBaseline="psalm-baseline.xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="https://getpsalm.org/schema/config"
xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
>
<projectFiles>
<directory name="src"/>
<ignoreFiles>
<directory name="vendor"/>
</ignoreFiles>
</projectFiles>

<plugins>
<pluginClass class="Psalm\SymfonyPsalmPlugin\Plugin"/>
</plugins>
</psalm>
```

</details>

### Run Psalm with custom config
```console
vendor/bin/psalm --config=psalm.xml
```

## Configuration options

| Option | Default | Description |
|--------|---------|-------------|
| `errorLevel` | `2` | Strictness level (1=strictest, 8=most lenient) |
| `findUnusedCode` | `false` | Detect unused classes, methods, and variables |
| `ensureOverrideAttribute` | `false` | Require `#[Override]` attribute on overridden methods |
| `errorBaseline` | - | Path to baseline file for suppressing existing issues |

## Baseline management

Baselines allow you to suppress existing issues while enforcing strict analysis on new code.

### Generate a baseline
```console
vendor/bin/psalm --config=psalm.xml --set-baseline=psalm-baseline.xml
```

### Update the baseline
After fixing issues, regenerate to remove resolved entries:
```console
vendor/bin/psalm --config=psalm.xml --update-baseline
```

### Ignore the baseline temporarily
Run analysis without baseline to see all issues:
```console
vendor/bin/psalm --config=psalm.xml --ignore-baseline
```

## Further resources

- [Psalm Documentation](https://psalm.dev/docs/)
- [Psalm Configuration Reference](https://psalm.dev/docs/running_psalm/configuration/)
- [Psalm Plugins](https://psalm.dev/plugins)
- [Psalm Issue Types](https://psalm.dev/docs/running_psalm/issues/)
Loading