Psalm Sandbox

work in progress

[!WARNING]

This project is not finished yet, work in progress.

Installation

You can install the package via composer:

composer require ghostwriter/psalm-sandbox --dev

Usage

You can create a test for your plugin by extending the AbstractPsalmSandboxTestCase class.

eg. tests/Unit/ExamplePluginTest.php

<?php

declare(strict_types=1);

namespace Vendor\PackageTests\Unit;

use Ghostwriter\PsalmSandbox\AbstractPsalmSandboxTestCase;
use Psalm\Issue\CodeIssue;
use Psalm\Issue\MissingReturnType;
use Psalm\Plugin\PluginEntryPointInterface;
use Vendor\Package\ExamplePlugin;

final class ExamplePluginTest extends AbstractPsalmSandboxTestCase
{
    /**
     * @var class-string<PluginEntryPointInterface>
     */
    public const PLUGINS = [ExamplePlugin::class];

    /**
     * @var array<class-string<CodeIssue>>
     */
    public const ISSUES = [MissingReturnType::class];
}

You can then run your tests using PHPUnit.

vendor/bin/phpunit

Plugin Development

Example Directory Structure

Your plugin should have the following directory structure:

composer.json
ExamplePlugin.php
src/
│   {PsalmIssueType}/
│   │   {FixIssue}.php
│   │   {ReportIssue}.php
│   │   {SuppressIssue}.php
│   MissingReturnType/
│   │   FixMissingReturnType.php
│   │   ReportMissingReturnType.php
│   │   SuppressMissingReturnType.php
tests/
│   Fixture/
│   │   {PsalmIssueType}/
│   │   │   fix-{PsalmIssueType}.php.inc
│   │   │   report-{PsalmIssueType}.php.inc
│   │   │   suppress-{PsalmIssueType}.php.inc
│   │   MissingReturnType/
│   │   │   fix-0001.php.inc
│   │   │   fix-missing-returntype.php.inc
│   │   │   report-0001.php.inc
│   │   │   report-missing-returntype.php.inc
│   │   │   suppress-0001.php.inc
│   │   │   suppress-missing-returntype.php.inc
│   Unit/
│   │   ExamplePluginTest.php

Example `Fix` Test

When you run vendor/bin/psalm --alter, it will automatically fix the code for you.

To create a Fix test, you need to create a file in the tests/Fixture/{PsalmIssueType} directory.

The file name should be prefixed with fix- and any unique identifier, e.g. fix-0001.php.inc.

The file MUST use --FIX-- to separate the before and after code.

The file should be structured as follows:

<?php

declare(strict_types=1);

namespace Vendor\PackageTests\Fixture\MissingReturnType;

final class FixMissingReturnType
{
    public function fixMissingReturnType()
    {
    }
}
?>
--FIX--
<?php

declare(strict_types=1);

namespace Vendor\PackageTests\Fixture\MissingReturnType;

final class FixMissingReturnType
{
    public function fixMissingReturnType(): void
    {
    }
}
?>

Example `Report` Test

When you run vendor/bin/psalm, it will report the issue in your code.

To create a Report test, you need to create a file in the tests/Fixture/{PsalmIssueType} directory.

The file name should be prefixed with report- and any unique identifier, e.g. report-0001.php.inc.

The file should be structured as follows:

<?php

declare(strict_types=1);

namespace Vendor\PackageTests\Fixture\MissingReturnType;

final class ReportMissingReturnType
{
    public function reportMissingReturnType()
    {
    }
}

Example `Suppress` Test

You can suppress the issue in your code by adding the @psalm-suppress annotation, adding suppressions to your psalm.xml file, or using a plugin.

To create a Suppress test, you need to create a file in the tests/Fixture/{PsalmIssueType} directory.

The file name should be prefixed with suppress- and any unique identifier, e.g. suppress-0001.php.inc.

The file should be structured as follows:

<?php

declare(strict_types=1);

namespace Vendor\PackageTests\Fixture\MissingReturnType;

final class SuppressMissingReturnType
{
    /**
     * @psalm-suppress MissingReturnType
     */
    public function suppressMissingReturnType()
    {
    }
}