Download the PHP package diversified-design/php-blueprint without Composer

PHP Blueprint

A reflection-based tool that generates a JSON blueprint of a PHP library's class signatures, optimised for use as LLM context.

Purpose

When providing library context to coding agents (like Claude Code), you want the class signatures (methods, types, docblocks) without the implementation noise. This tool gives you the equivalent of TypeScript .d.ts files or C/C++ headers — the public contract without implementation details.

Installation

Usage

Options

Configuration

Create a .blueprint.config.php in your project root:

All keys are optional. When a config file is present, you can run Blueprint with no arguments:

CLI arguments always override config values. Use --no-config to ignore the config file, or --config path/to/config.php to use a different one.

Composer Scripts

Add to your project's composer.json:

Then run with composer blueprint.

CI/CD

Output Format

The extractor generates pretty-printed JSON:

Only non-empty fields are included. The type field is omitted for plain classes (only shown for interfaces, traits, and enums).

Output Modes

Public-Only (Default)

Extracts only public methods and properties — the true public API surface.

Use for: LLM context (most token-efficient), API documentation, public interface contracts.

Full Mode (--include-private)

Includes private and protected members.

Use for: Internal refactoring analysis, understanding implementation details, migration planning.

Writing Code That Blueprints Well

Blueprint extracts what's in your source — it can't invent context that isn't there. The more information your code carries in its signatures and docblocks, the more useful the blueprint is to an LLM agent. Here's what matters most:

Type everything

Blueprint captures parameter types, return types, and property types. When a PHPStan/Psalm @param, @return, or @var docblock type is present, Blueprint uses it instead of the native type hint — giving agents the full picture.

Write summary docblocks

Blueprint extracts the first paragraph of each class and method docblock (everything before the first @tag or blank line). This becomes the — description in the output. One or two sentences that explain what the method does and when you'd use it:

Document parameters with @param

Blueprint extracts @param descriptions and appends them as inline comments next to each parameter. This is especially valuable for parameters whose purpose isn't obvious from the type alone:

In the blueprint, this becomes:

Declare @throws

Blueprint appends @throws types to method signatures. This tells agents which exceptions to handle:

Use meaningful names

Parameter names appear directly in the blueprint. $baseDirectory communicates more than $dir. $overwriteNewerFiles communicates more than $force. Since the blueprint may be the only context an agent has, every name carries weight.

Use constants and enums

Blueprint extracts constant names and values, and enum cases with their backing values. Well-named constants tell an agent what valid states and options exist:

Define clear interfaces

Blueprint captures the full class hierarchy — extends, implements, and uses. Well-defined interfaces and abstract classes give agents the contract to code against without needing to read implementations.

How It Works

Blueprint uses static analysis via BetterReflection (which builds on nikic/php-parser) to extract class signatures. No code is executed — source files are parsed, not loaded. This means:

• No side effects from target code
• No dependency resolution failures
• No PHP version coupling between Blueprint and the target package
• Works on any valid PHP source, even if dependencies aren't installed

Token Efficiency

For LLM context, token efficiency matters:

Requirements

• PHP 8.2+
• Composer

Limitations

• Doesn't extract standalone function signatures (only classes/interfaces/traits/enums)
• Docblocks are cleaned but not fully parsed (no structured @param extraction beyond inline hints)
• Complex constant expressions (runtime-evaluated) are shown as <expr> rather than resolved values

License

MIT