Skip to content

CLAUDE.md

Latest commit

 

History

History
115 lines (80 loc) · 6.22 KB

CLAUDE.md

File metadata and controls

115 lines (80 loc) · 6.22 KB

PHPStan - PHP Static Analysis Tool

Project Overview

PHPStan finds errors in PHP code without running it. It catches bugs before tests are written, moving PHP closer to compiled languages. This is the distribution repository — the compiled PHAR and supporting infrastructure. The actual source code lives at phpstan/phpstan-src.

Repository Structure

├── phpstan                    # CLI entry point (shell script loading the PHAR)
├── phpstan.phar               # Compiled PHAR archive (~26 MB)
├── phpstan.phar.asc           # GPG signature for the PHAR
├── bootstrap.php              # PHAR autoloader with PHP version polyfills
├── composer.json              # Package definition (requires PHP ^7.4|^8.0)
├── .phar-checksum             # MD5 + SHA1 checksums for reproducible builds
├── conf/
│   └── bleedingEdge.neon      # Bleeding edge configuration profile
├── e2e/                       # End-to-end tests (~67 test scenarios)
├── docker/                    # Dockerfiles for PHP 8.0–8.4
├── identifier-extractor/      # Tool to extract error identifiers from rule source code
├── playground-api/            # AWS Lambda API for the online playground (TypeScript)
├── playground-runner/         # AWS Lambda runner for the playground (PHP/Bref)
├── website/                   # phpstan.org static site (Eleventy + Vite + TailwindCSS)
└── .github/workflows/         # CI/CD workflows

Key Concepts

Distribution Model

This repository distributes a pre-built PHAR archive. The source code is in phpstan/phpstan-src, which is on PHP 8.1+ internally but the PHAR build is downgraded to support PHP 7.4+. The phpstan script loads the PHAR and delegates to the bundled binary.

PHP Version Support

  • This distribution package: PHP ^7.4|^8.0 (defined in composer.json)
  • phpstan-src internally: PHP 8.1+ (downgraded during PHAR build)
  • Other extension repositories (phpstan-strict-rules, phpstan-doctrine, phpstan-symfony, etc.): still support PHP 7.4+
  • E2E tests run on: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5 (Linux + Windows)

Bleeding Edge

The conf/bleedingEdge.neon configuration enables experimental/strict checks before they become defaults. Users opt in by including this config.

Error Identifiers

Every PHPStan error has a unique identifier (e.g., argument.type, deadCode.unreachable). The identifier-extractor/ tool scans all PHPStan repositories to extract these identifiers, producing JSON used to generate documentation on the website.

Development

CI Workflows

Key workflows in .github/workflows/:

  • tests.yml — Runs e2e tests on PHP 7.4–8.5, Linux + Windows. Triggered on changes to e2e/**, phpstan, .phar-checksum, bootstrap.php.
  • other-tests.yml — Additional integration tests (PHP-Parser, React Promise, etc.)
  • integration-tests.yml — Tests against major projects (Rector, Larastan, Carbon, etc.)
  • extension-tests.yml — Tests 1st-party PHPStan extensions (PHPUnit, Doctrine, Symfony, etc.)
  • release.yml — Creates GitHub release on tag push, uploads phpstan.phar and signature
  • docker-stable.yml / docker-nightly.yml — Builds multi-arch Docker images (arm64 + amd64) pushed to ghcr.io
  • extract-identifiers.yml — Extracts error identifiers from all PHPStan repos
  • website.yml — Builds and deploys phpstan.org
  • generate-error-docs.lock.yml — Generates error documentation using Claude

Current Branch

The main development branch for this repository is 2.2.x.

Website

The website (phpstan.org) lives in website/ and has its own website/CLAUDE.md with detailed instructions. Key points:

  • Built with Eleventy (11ty) + Vite + TailwindCSS
  • Two-stage build: npm run build:11ty then npm run build:vite
  • Deployed to AWS S3 + CloudFront
  • Error documentation in website/errors/ is auto-generated (see website/errors/CLAUDE.md)

Playground

The online playground at https://phpstan.org/try consists of two AWS Lambda services:

  • playground-api/ — TypeScript API that orchestrates analysis across multiple PHP versions
  • playground-runner/ — PHP Lambda (via Bref) that executes PHPStan against submitted code

Both are deployed via the Serverless Framework to eu-west-1.

Docker

Dockerfiles in docker/ build images for PHP 8.0–8.4, based on php:*-cli-alpine. Images are published to ghcr.io as multi-architecture (arm64 + amd64). The images install PHPStan via Composer and use phpstan as the entrypoint.

Related Repositories

Extension repositories support PHP 7.4+ and some support multiple versions of the libraries they analyse.

Making Changes

  • Source code changes belong in phpstan/phpstan-src, not here
  • E2E tests can be added or modified in e2e/
  • Website content is in website/src/ (see website/CLAUDE.md)
  • Error documentation is in website/errors/ (see website/errors/CLAUDE.md)
  • Configuration uses NEON format (Nette Object Notation), similar to YAML