diff --git a/README.md b/README.md index ae313ee..064b4c9 100644 --- a/README.md +++ b/README.md @@ -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). @@ -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. diff --git a/docs/Psalm/README.md b/docs/Psalm/README.md new file mode 100644 index 0000000..c827acd --- /dev/null +++ b/docs/Psalm/README.md @@ -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. + +
+ See some customization examples + +### Adding stubs for external libraries +Stubs help Psalm understand types from external libraries that lack proper type declarations: +```xml + + + + + + + + + + + + + + + + + + +``` + +### Adding issue handlers +Suppress specific issues for certain directories or files: +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Using a baseline +Baselines allow you to suppress existing issues while enforcing strict analysis on new code: +```xml + + + + + + + + + + + + + +``` + +
+ +### 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/)