agentleFS
peterfoxpeterfox/agent-skills/phpstan-developer/SKILL.md

phpstan-developer

Skill25 starsChanged 9 months agoMITView on GitHub

Build PHPStan rules, collectors, and extensions that analyze PHP code for custom errors. Use when asked to create, modify, or explain PHPStan rules, collectors, or type extensions. Triggers on requests like "write a PHPStan rule to...", "create a PHPStan rule that...", "add a PHPStan rule for...", "write a collector for...", or when working on a phpstan extension package.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write the Rule class extending nothing — implement Rule interface directly

    line 14
  2. Very specific:

    Write the test class extending RuleTestCase with fixture PHP files

    line 15
  3. Very specific:

    Never use instanceof on PHPStan types — always use the is*() methods:

    line 121
  4. Distinctive:

    Every rule needs a test class and at least one fixture file.

    line 137
  5. Very specific:

    If a rule has constructor dependencies, create them manually in getRule()

    line 197

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PHPStan Extension Builder

PHPStan finds bugs by traversing the PHP-Parser AST, resolving types via PHPStan's type system, and reporting errors from processNode().

Workflow

  1. Identify the PHP-Parser node type to target — use var_dump(get_class($node)) with Node::class as a temporary getNodeType() to discover node types, or check the php-parser docs
  2. For cross-file analysis (e.g. "find unused things", "check all calls to X"), use a Collector to gather data and a CollectedDataNode rule to report — see references/collectors.md
  3. Write the Rule class extending nothing — implement Rule interface directly
  4. Write the test class extending RuleTestCase with fixture PHP files
  5. Register the rule in a neon config file

Rule Skeleton

<?php

declare(strict_types=1);

namespace App\PHPStan\Rules;

use PhpParser\Node;
use PhpParser\Node\Expr\MethodCall;
use PHPStan\Analyser\Scope;
use PHPStan\Rules\Rule;
use PHPStan\Rules\RuleErrorBuilder;
use PHPStan\Rules\IdentifierRuleError;

/**
 * @implements Rule<MethodCall>
 */
final class MyRule implements Rule
{
    public function getNodeType(): string
    {
        return MethodCall::class;
    }

    /**
     * @param MethodCall $node
     * @return list<IdentifierRuleError>
     */
    public function processNode(Node $node, Scope $scope): array
    {
        // Return [] for no error, or build errors:
        return [
            RuleErrorBuilder::message('Something is wrong.')
                ->identifier('myRule.something')  // required: camelCase.dotSeparated
                ->build(),
        ];
    }
}

processNode() Return Values

ReturnEffect
[]No errors — node is fine
[RuleErrorBuilder::...->build()]Report one or more errors

Return type is always list<IdentifierRuleError>. Never return a single object — always wrap in an array.

RuleErrorBuilder API

RuleErrorBuilder::message('Error message text.')   // required
    ->identifier('category.specific')              // required; pattern: /[a-z][a-z0-9]*(\.[a-z0-9]+)*/
    ->line($node->getStartLine())                  // override line number
    ->tip('Suggestion to fix this.')               // optional tip shown to user
    ->addTip('Additional tip.')                    // add more tips
    ->discoveringSymbolsTip()                      // standard "class not found" tip
    ->nonIgnorable()                               // cannot be suppressed with @phpstan-ignore
    ->fixNode($node, fn (Node $n) => $modified)   // experimental: provide an automatic fix
    ->build()                                      // returns IdentifierRuleError

Fixable errors — ->fixNode() attaches an AST transformation callable to the error. When the user runs phpstan analyse --fix (or their editor's PHPStan integration applies fixes), PHPStan replaces the original node with the result of the callable. The callable receives the original node and must return a replacement node of the same type. This is marked @internal Experimental in the source but is used throughout PHPStan core. See references/testing.md for how to test fixes.

When the fix is complex, use Rector instead. fixNode() is limited to replacing a single node in-place. If the fix needs to add imports, restructure multiple nodes, move code, or make changes across more than one location in the file, write a Rector rule instead. Rector is purpose-built for multi-step AST transformations and handles pretty-printing, import resolution, and edge cases that fixNode() cannot. PHPStan finds the problem; Rector fixes it.

For CollectedDataNode rules (cross-file), you must set file and line explicitly:

RuleErrorBuilder::message('...')
    ->file('/path/to/file.php')
    ->line(42)
    ->identifier('myRule.something')
    ->build()

Common Scope Methods

$scope->getType($node)                    // Type of any Expr node
$scope->isInClass()                       // Currently inside a class?
$scope->getClassReflection()              // ClassReflection|null
$scope->getFunction()                     // FunctionReflection|null
$scope->isInAnonymousFunction()           // Inside a closure?
$scope->hasVariableType('varName')        // TrinaryLogic: yes/maybe/no
$scope->getVariableType('varName')        // Type of $varName
$scope->filterByTruthyValue($expr)        // Narrowed scope when $expr is true
$scope->isDeclareStrictTypes()            // strict_types=1 active?
$scope->resolveName($nameNode)            // Resolve self/parent/static to FQCN

TrinaryLogic — the result of all is*() and has*() checks. Has three states:

  • ->yes() — definitely true; use when you want zero false positives
  • ->no() — definitely false; use as an early-return guard to skip inapplicable nodes
  • ->maybe() — uncertain (mixed/union); use for softer warnings or combined checks

See references/trinary-logic.md for the full decision guide, logical operations, and patterns.

Common Type Methods

Never use instanceof on PHPStan types — always use the is*() methods:

$type = $scope->getType($node);

$type->isString()->yes()         // Is definitely a string?
$type->isObject()->yes()         // Is definitely an object?
$type->isNull()->yes()           // Is always null?
$type->isArray()->yes()          // Is always an array?
$type->getObjectClassNames()     // list<string> of class names
$type->getConstantStrings()      // list<ConstantStringType>
$type->describe(VerbosityLevel::typeOnly())  // Human-readable type description

Writing Tests

Every rule needs a test class and at least one fixture file. Use one fixture file per scenario.

Test class (tests/Rules/MyRuleTest.php):

<?php

declare(strict_types=1);

namespace App\Tests\PHPStan\Rules;

use App\PHPStan\Rules\MyRule;
use PHPStan\Rules\Rule;
use PHPStan\Testing\RuleTestCase;

/**
 * @extends RuleTestCase<MyRule>
 */
final class MyRuleTest extends RuleTestCase
{
    protected function getRule(): Rule
    {
        return new MyRule();
    }

    public function testRule(): void
    {
        $this->analyse(
            [__DIR__ . '/data/my-rule.php'],
            [
                ['Error message text.', 10],       // [message, line]
                ['Another error.', 25, 'A tip.'],  // [message, line, tip] (optional)
            ]
        );
    }

    public function testNoErrors(): void
    {
        $this->analyse([__DIR__ . '/data/my-rule-clean.php'], []);
    }
}

Fixture file (tests/Rules/data/my-rule.php) — plain PHP file with code that triggers the rule:

<?php

declare(strict_types=1);

namespace App\Tests\PHPStan\Rules\Data;

// This call should trigger the rule on line 10:
$obj->forbiddenMethod();

Key rules:

  • One scenario per fixture file — do not mix multiple unrelated scenarios in one file
  • Fixture files live in a data/ subdirectory relative to the test class
  • The analyse() assertion fails if any unexpected errors appear, or expected errors are missing
  • If a rule has constructor dependencies, create them manually in getRule()

See references/testing.md for: additional config files, injecting services, TypeInferenceTestCase.

Registration (phpstan.neon / extension.neon)

Shorthand (simple rules with no constructor dependencies):

rules:
    - App\PHPStan\Rules\MyRule

Full service registration (for rules with dependencies):

services:
    -
        class: App\PHPStan\Rules\MyRule
        tags:
            - phpstan.rules.rule

    -
        class: App\PHPStan\Collectors\MyCollector
        tags:
            - phpstan.collector

Reference Files

  • references/trinary-logic.md — TrinaryLogic in depth: when to use yes/no/maybe, and/or/negate, patterns
  • references/collectors.md — Collector interface, cross-file analysis, CollectedDataNode pattern
  • references/testing.md — Full test structure, injecting services, additional config files, TypeInferenceTestCase
  • references/scope-api.md — Full Scope API, ReflectionProvider, ClassReflection methods
  • references/virtual-nodes.md — PHPStan virtual nodes (InClassNode, InClassMethodNode, FileNode, etc.)
  • references/extensions.md — Dynamic return type extensions, type specifying extensions, reflection extensions, neon service tags

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.