TypePHP Compilation Pipeline Phases Explained: Idle, Prepare, and Convert

The TypePHP compilation pipeline consists of three discrete phases—idle, prepare, and convert—defined as string constants in src/CompilerBase.php. These phases gate every major operation, from initial AST construction to final target code generation.

The TypePHP compiler implements a deterministic state machine that tracks compilation progress through explicit phase constants stored in the CompilerBase class. Unlike compilers that implicitly transition between stages, TypePHP exposes these boundaries through public constants and validation methods, allowing internal components to assert they operate only during valid windows.

The Three Core Phases

The primary TypePHP compilation pipeline runs through a strict progression of three states declared at lines 273-275 of src/CompilerBase.php.

The Idle Phase

The idle phase represents the compiler’s initial state before any work begins. During this phase, no source files have been parsed and the compiler holds no allocated resources for the current compilation unit. The constant PHASE_IDLE marks this standby state, serving as both the entry point and the restoration target after compilation completes.

The Prepare Phase

Transitioning to prepare initiates the pre-processing stage. According to the source code, this phase handles parsing input PHP files, building the abstract syntax tree (AST), and performing early-stage analyses such as name resolution and declaration collection. The prepare phase also establishes the environment required for subsequent transformations, setting up symbol tables and scope contexts that the conversion stage depends upon.

The Convert Phase

The convert phase serves as the primary transformation and generation stage. Here the compiler walks the AST to perform type checking, constructs SSA (Static Single Assignment) form, and applies optimizations including loop-variable and property-access optimizations. All transformations dependent on fully-resolved types execute during this phase, culminating in target code generation for C++ or WebAssembly. Files like src/Resolver/DeclarationSymbolTrait.php explicitly verify $this->compilerPhase === self::PHASE_CONVERT before finalizing constants and values, while components such as PropertyAccessResolver assert this phase to ensure type information is complete.

Managing Phase Transitions

The CompilerBase class provides explicit state management through methods defined at lines 1006-1022 of src/CompilerBase.php.

enterCompilerPhase($phase) transitions the compiler to a new state while returning the previous phase identifier for stack-based restoration. restoreCompilerPhase($prevPhase) returns the compiler to its prior state using the value returned by the enter method. For validation, assertCompilerPhase($phase) enforces that the current phase matches expectations, throwing if the compiler is in the wrong state.

These controls enable nested compilation workflows where the compiler might temporarily switch contexts:

<?php
use TypePhp\CompilerBase;

// Instantiate compiler
$compiler = new class extends CompilerBase {};

// Default state
echo $compiler->compilerPhase; // "idle"

// Transition to preprocessing
$previous = $compiler->enterCompilerPhase(CompilerBase::PHASE_PREPARE);
// ... AST construction and name resolution ...
$compiler->restoreCompilerPhase($previous); // Return to idle

// Transition to conversion
$previous = $compiler->enterCompilerPhase(CompilerBase::PHASE_CONVERT);
// ... type checking, SSA building, optimizations ...
$compiler->restoreCompilerPhase($previous); // Return to idle

Compile-Time Attribute Phases vs. Core Pipeline

Separate from the main TypePHP compilation pipeline, the system defines logical phases for compile-time attribute validation. Located in src/Transform/CompileTimeAttributeRegistry.php at lines 30-33, these include preprocess, enter, function_leave, and class_leave. These secondary phases control attribute placement validation timing but operate independently from the core idle→prepare→convert progression managed by CompilerBase. The distinction is strict: attribute phases validate metadata placement, while the pipeline phases manage actual code transformation.

Summary

• TypePHP tracks compilation progress through three explicit string constants—idle, prepare, and convert—defined in src/CompilerBase.php at lines 273-275.
• The prepare phase handles AST construction and early analysis, while the convert phase performs type checking, SSA construction, optimizations, and target code generation.
• Phase transitions are managed through enterCompilerPhase(), restoreCompilerPhase(), and assertCompilerPhase() methods implemented at lines 1006-1022 of src/CompilerBase.php.
• Compile-time attribute phases declared in src/Transform/CompileTimeAttributeRegistry.php exist independently for validation purposes and are not part of the core compilation pipeline.
• Unit tests in phpunit/src/CompilerPhaseTest.php verify that components correctly enforce phase constraints.

Frequently Asked Questions

What are the three main phases in the TypePHP compilation pipeline?

The TypePHP compiler operates through three phases: idle (initial state), prepare (parsing and AST construction), and convert (type checking, optimization, and code generation). These are declared as string constants in src/CompilerBase.php at lines 273-275.

How does TypePHP enforce which operations run during specific compilation phases?

The CompilerBase class provides the assertCompilerPhase() method that internal components call to verify the current phase. For example, DeclarationSymbolTrait checks $this->compilerPhase === self::PHASE_CONVERT before finalizing values, while optimizer passes and PropertyAccessResolver assert they run only during the convert phase.

Are compile-time attribute phases part of the main TypePHP compilation pipeline?

No. The attribute phases (preprocess, enter, function_leave, class_leave) defined in src/Transform/CompileTimeAttributeRegistry.php at lines 30-33 serve only to validate attribute placement timing. They operate independently from the core idle, prepare, and convert phases managed by CompilerBase.

How can I programmatically transition between TypePHP compiler phases?

Use the enterCompilerPhase() method to move to a new phase, which returns the previous phase identifier for stack-based restoration. Call restoreCompilerPhase() with the returned value to revert to the prior state. This pattern allows nested phase transitions during complex compilation workflows and is utilized by src/Preprocessor.php when moving from preparation to conversion.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}