CLAUDE.md

1# PHPStan - PHP Static Analysis Tool
2 
3## Project Overview
4 
5PHPStan 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](https://github.com/phpstan/phpstan-src).
6 
7- **Website:** https://phpstan.org/
8- **Documentation:** https://phpstan.org/user-guide/getting-started
9- **API Reference:** https://apiref.phpstan.org/
10 
11## Repository Structure
12 
13```
14├── phpstan                    # CLI entry point (shell script loading the PHAR)
15├── phpstan.phar               # Compiled PHAR archive (~26 MB)
16├── phpstan.phar.asc           # GPG signature for the PHAR
17├── bootstrap.php              # PHAR autoloader with PHP version polyfills
18├── composer.json              # Package definition (requires PHP ^7.4|^8.0)
19├── .phar-checksum             # MD5 + SHA1 checksums for reproducible builds
20├── conf/
21│   └── bleedingEdge.neon      # Bleeding edge configuration profile
22├── e2e/                       # End-to-end tests (~67 test scenarios)
23├── docker/                    # Dockerfiles for PHP 8.0–8.4
24├── identifier-extractor/      # Tool to extract error identifiers from rule source code
25├── playground-api/            # AWS Lambda API for the online playground (TypeScript)
26├── playground-runner/         # AWS Lambda runner for the playground (PHP/Bref)
27├── website/                   # phpstan.org static site (Eleventy + Vite + TailwindCSS)
28└── .github/workflows/         # CI/CD workflows
29```
30 
31## Key Concepts
32 
33### Distribution Model
34 
35This repository distributes a pre-built PHAR archive. The source code is in [phpstan/phpstan-src](https://github.com/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.
36 
37### PHP Version Support
38 
39- **This distribution package:** PHP ^7.4|^8.0 (defined in composer.json)
40- **phpstan-src internally:** PHP 8.1+ (downgraded during PHAR build)
41- **Other extension repositories** (phpstan-strict-rules, phpstan-doctrine, phpstan-symfony, etc.): still support PHP 7.4+
42- **E2E tests run on:** PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5 (Linux + Windows)
43 
44### Bleeding Edge
45 
46The `conf/bleedingEdge.neon` configuration enables experimental/strict checks before they become defaults. Users opt in by including this config.
47 
48### Error Identifiers
49 
50Every 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.
51 
52## Development
53 
54 
55### CI Workflows
56 
57Key workflows in `.github/workflows/`:
58 
59- **`tests.yml`** — Runs e2e tests on PHP 7.4–8.5, Linux + Windows. Triggered on changes to `e2e/**`, `phpstan`, `.phar-checksum`, `bootstrap.php`.
60- **`other-tests.yml`** — Additional integration tests (PHP-Parser, React Promise, etc.)
61- **`integration-tests.yml`** — Tests against major projects (Rector, Larastan, Carbon, etc.)
62- **`extension-tests.yml`** — Tests 1st-party PHPStan extensions (PHPUnit, Doctrine, Symfony, etc.)
63- **`release.yml`** — Creates GitHub release on tag push, uploads `phpstan.phar` and signature
64- **`docker-stable.yml`** / **`docker-nightly.yml`** — Builds multi-arch Docker images (arm64 + amd64) pushed to ghcr.io
65- **`extract-identifiers.yml`** — Extracts error identifiers from all PHPStan repos
66- **`website.yml`** — Builds and deploys phpstan.org
67- **`generate-error-docs.lock.yml`** — Generates error documentation using Claude
68 
69### Current Branch
70 
71The main development branch for this repository is `2.2.x`.
72 
73## Website
74 
75The website (phpstan.org) lives in `website/` and has its own `website/CLAUDE.md` with detailed instructions. Key points:
76 
77- Built with Eleventy (11ty) + Vite + TailwindCSS
78- Two-stage build: `npm run build:11ty` then `npm run build:vite`
79- Deployed to AWS S3 + CloudFront
80- Error documentation in `website/errors/` is auto-generated (see `website/errors/CLAUDE.md`)
81 
82## Playground
83 
84The online playground at https://phpstan.org/try consists of two AWS Lambda services:
85 
86- **playground-api/** — TypeScript API that orchestrates analysis across multiple PHP versions
87- **playground-runner/** — PHP Lambda (via Bref) that executes PHPStan against submitted code
88 
89Both are deployed via the Serverless Framework to eu-west-1.
90 
91## Docker
92 
93Dockerfiles 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.
94 
95## Related Repositories
96 
97- [phpstan/phpstan-src](https://github.com/phpstan/phpstan-src) — Main source code (PHP 8.1+, downgraded for PHAR)
98- [phpstan/phpstan-strict-rules](https://github.com/phpstan/phpstan-strict-rules) — Additional strict rules
99- [phpstan/phpstan-deprecation-rules](https://github.com/phpstan/phpstan-deprecation-rules) — Deprecation detection
100- [phpstan/phpstan-doctrine](https://github.com/phpstan/phpstan-doctrine) — Doctrine integration
101- [phpstan/phpstan-symfony](https://github.com/phpstan/phpstan-symfony) — Symfony integration
102- [phpstan/phpstan-phpunit](https://github.com/phpstan/phpstan-phpunit) — PHPUnit integration
103- [phpstan/phpstan-nette](https://github.com/phpstan/phpstan-nette) — Nette integration
104- [phpstan/phpstan-webmozart-assert](https://github.com/phpstan/phpstan-webmozart-assert) — Webmozart Assert integration
105- [phpstan/phpdoc-parser](https://github.com/phpstan/phpdoc-parser) — PHPDoc parser library
106 
107Extension repositories support PHP 7.4+ and some support multiple versions of the libraries they analyse.
108 
109## Making Changes
110 
111- **Source code changes** belong in [phpstan/phpstan-src](https://github.com/phpstan/phpstan-src), not here
112- **E2E tests** can be added or modified in `e2e/`
113- **Website content** is in `website/src/` (see `website/CLAUDE.md`)
114- **Error documentation** is in `website/errors/` (see `website/errors/CLAUDE.md`)
115- Configuration uses NEON format (Nette Object Notation), similar to YAML
116