Skip to content

CLAUDE.md

Latest commit

 

History

History
91 lines (65 loc) · 4.27 KB

CLAUDE.md

File metadata and controls

91 lines (65 loc) · 4.27 KB
Raw

CLAUDE.md

Project Overview

This is phpstan/php-8-stubs — a repository of PHP stub files automatically extracted from php-src. PHPStan uses these stubs to understand the signatures of built-in PHP classes and functions when analysing codebases running PHP 8.0 and later.

The stubs are not hand-written. They are generated by the extractor tool in this repository and should not be edited manually.

Repository Structure

Php8StubsMap.php       # Auto-generated class mapping symbols to stub file paths (version-aware)
composer.json          # Package metadata (phpstan/php-8-stubs)
stubs/                 # Auto-generated stub files
  Zend/                # Core language stubs (Error, Exception, Closure, Fiber, etc.)
  ext/                 # Extension stubs (date, dom, curl, spl, intl, etc.)
  sapi/                # SAPI stubs (cli, fpm, phpdbg, etc.)
  LICENSE              # PHP License for the stubs
extractor/             # Tool that extracts stubs from php-src
  extract.php          # Main extraction script
  composer.json        # Extractor dependencies (PHP 8.3+, nikic/php-parser, etc.)
  phpstan.neon.dist    # PHPStan config for analysing the extractor itself

How Stub Extraction Works

The extraction is fully automated via the extractor/extract.php script and the GitHub Actions workflow in .github/workflows/update.yml.

Extraction process

  1. The script checks out php/php-src at the PHP-8.0 branch and runs extract.php to produce the base stubs.
  2. It then iterates through each subsequent PHP version branch (8.1, 8.2, 8.3, 8.4, 8.5) and runs the extractor in --update mode: 
    ./extractor/extract.php --update -- <from-version> <to-version>
  3. In update mode, the extractor compares the new stubs against the previous version and annotates differences with #[\Since('x.y')] and #[\Until('x.y')] attributes. This allows PHPStan to understand which symbols and signatures exist in which PHP version.

Version-aware attributes

  • #[\Since('8.x')] — symbol or signature variant was introduced in PHP 8.x
  • #[\Until('8.x')] — symbol or signature variant was removed/replaced in PHP 8.x

When a function signature changes between versions, both the old and new variants are kept in the stub file with appropriate attributes. Example from stubs/ext/zlib/gzopen.php:

#[\Until('8.5')]
function gzopen(string $filename, string $mode, int $use_include_path = 0) {}

#[\Since('8.5')]
function gzopen(string $filename, string $mode, bool $use_include_path = false) {}

Php8StubsMap.php

This auto-generated file maps lowercase class and function names to their stub file paths. It accepts a $phpVersionId (format: major * 10000 + minor * 100 + patch) and conditionally merges version-specific entries using if ($phpVersionId >= XXXXX) blocks.

CI/CD Workflows

  • Update stubs (update.yml): Runs daily on cron and on pushes to main. Extracts stubs from all PHP 8.x branches, commits changes, and tags a new patch release.
  • PHPStan (phpstan.yml): Runs PHPStan on the extractor code itself on PRs and pushes that touch extractor/.
  • Create release (release.yml): Creates a GitHub release when a tag is pushed.
  • Send pull request (send-pr.yml): On release, automatically opens a PR in phpstan/phpstan-src to update the php-8-stubs dependency.
  • Lock closed issues (lock-closed-issues.yml): Locks stale closed issues after 31 days.

Development

Working on the extractor

cd extractor
composer install

The extractor requires PHP 8.3+ and uses:

  • nikic/php-parser for parsing PHP stub files from php-src
  • phpstan/phpdoc-parser for parsing and manipulating PHPDoc comments
  • symfony/console and symfony/finder for CLI and file discovery

Running PHPStan on the extractor

cd extractor
vendor/bin/phpstan

Important notes

  • Do not manually edit files in stubs/ or Php8StubsMap.php — they are auto-generated and will be overwritten by the next extraction run.
  • Changes to extraction logic go in extractor/extract.php.
  • The stubs are dual-licensed under MIT and PHP-3.01.
  • This package is consumed by PHPStan as a Composer dependency. Releases are automatically tagged and propagated to phpstan/phpstan-src via the send-pr workflow.