Superpowers Sage:wp Phpstan

Static Analysis for Sage/Acorn with PHPStan

When to use

• Setting up static analysis on a Sage theme for the first time
• Adding PHPStan to an existing project and managing the baseline
• Fixing type errors reported by PHPStan in Sage/Acorn code
• Configuring CI pipelines to enforce static analysis
• Incrementally raising the PHPStan analysis level

Inputs required

• Current PHPStan level (if already configured), or confirmation this is a fresh setup
• Whether Larastan and WordPress stubs are already installed
• Target analysis level (or follow the recommended progression)
• CI platform in use (GitHub Actions, GitLab CI, etc.) if configuring CI integration

Procedure

1. Install dependencies

lando theme-composer require --dev phpstan/phpstan larastan/larastan szepeviktor/phpstan-wordpress

This installs:

• phpstan/phpstan — the core static analysis engine
• larastan/larastan — Laravel-specific extensions (facades, models, service container, Eloquent)
• szepeviktor/phpstan-wordpress — WordPress function stubs and type definitions

2. Configure phpstan.neon

Create or update phpstan.neon in the theme root:

includes:
    - vendor/larastan/larastan/extension.neon
    - vendor/szepeviktor/phpstan-wordpress/extension.neon

parameters:
    paths:
        - app/

    level: 0

    # WordPress dynamic functions that PHPStan cannot resolve
    ignoreErrors:
        - '#Function apply_filters invoked with#'
        - '#Function do_action invoked with#'
        - '#Function add_filter expects#'
        - '#Function add_action expects#'

    # Scan files for WordPress global function definitions
    scanDirectories:
        - vendor/szepeviktor/phpstan-wordpress/bootstrap.php

    # Treat Acorn facades correctly via Larastan
    checkGenericClassInNonGenericObjectType: false

3. Run the initial analysis

lando theme-composer exec phpstan -- analyse

At level 0, this should produce few or no errors. If errors exist, fix them or generate a baseline.

4. Generate a baseline

A baseline captures all existing errors so they can be addressed incrementally without blocking development.

lando theme-composer exec phpstan -- analyse --generate-baseline

This creates phpstan-baseline.neon. Include it in the main config:

includes:
    - vendor/larastan/larastan/extension.neon
    - vendor/szepeviktor/phpstan-wordpress/extension.neon
    - phpstan-baseline.neon

New code must pass analysis; baseline errors are addressed over time.

5. Common fixes for Sage/Acorn/WordPress patterns

WordPress hook callbacks

// PHPStan complains about callable types
// Fix: use explicit Closure or typed callable
add_filter('the_content', function (string $content): string {
    return $content . '<p>Appended</p>';
});

ACF field return types

// get_field() returns mixed — PHPStan cannot infer the type
// Fix: assert or cast the return value
/** @var string|null $subtitle */
$subtitle = get_field('subtitle');

// Or use a wrapper with PHPDoc
/**
 * @return array<string, mixed>
 */
function get_hero_fields(): array
{
    return (array) get_field('hero_section') ?: [];
}

Mixed return from get_field

// Bad — PHPStan reports "Cannot access property on mixed"
$image = get_field('image');
echo $image['url']; // Error

// Good — type-narrow first
$image = get_field('image');
if (is_array($image) && isset($image['url'])) {
    echo $image['url'];
}

Eloquent model properties

Larastan handles most Eloquent patterns automatically. For custom model attributes, add PHPDoc:

/**
 * @property int $id
 * @property string $title
 * @property \Carbon\Carbon $created_at
 */
class Event extends Model
{
    // ...
}

6. Level progression strategy

Recommended progression:

• 0 to 3: Move quickly. These levels catch real bugs with minimal effort. Fix issues as you go.
• 3 to 5: Requires adding return types and parameter types. Use the baseline to manage existing code while enforcing types on new code.
• 5+: Only pursue if the team commits to strict typing throughout the codebase.

After raising the level, regenerate the baseline:

lando theme-composer exec phpstan -- analyse --generate-baseline

7. CI integration

Run PHPStan in CI without progress output:

lando theme-composer exec phpstan -- analyse --no-progress --error-format=github

GitHub Actions example

- name: Run PHPStan
  run: |
    cd web/app/themes/<theme-name>
    composer exec phpstan -- analyse --no-progress --error-format=github

The --error-format=github flag produces annotations that appear inline on pull requests.

Preventing baseline growth

In CI, verify the baseline has not grown:

# Regenerate baseline and check for changes
lando theme-composer exec phpstan -- analyse --generate-baseline
git diff --exit-code phpstan-baseline.neon

If the diff is non-empty, the PR introduces new errors that must be fixed.

8. Integration with Acorn

Larastan provides analysis support for Laravel patterns used in Acorn:

• Facades: Larastan resolves facade accessors to their underlying classes
• Service container: app()->make() and dependency injection are type-aware
• Eloquent models: relationships, scopes, and attributes are analyzed
• Collections: return types through collection chains are tracked
• Config/View: config() and view() calls are understood

No additional configuration is needed beyond including larastan/extension.neon.

Verification

• lando theme-composer exec phpstan -- analyse runs without errors (or only baseline errors)
• phpstan.neon includes both Larastan and WordPress stubs extensions
• Baseline file exists and is included in the config
• Analysis level matches the project's target level
• CI pipeline runs PHPStan and fails on new errors
• No new errors added to the baseline without justification

Failure modes

Escalation

• If PHPStan reports errors that appear to be false positives in WordPress or Acorn code, check the GitHub issues for szepeviktor/phpstan-wordpress and larastan/larastan before suppressing
• For complex type issues involving WordPress hooks or ACF, consider writing custom PHPStan extensions or type stubs
• If the baseline grows uncontrollably, schedule a dedicated refactoring session to reduce it rather than ignoring it
• For questions about level progression strategy, discuss with the team lead to set a realistic target level