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

> Explore the TypePHP compilation pipeline's three phases: idle, prepare, and convert. Understand how these stages manage TypePHP's AST construction and code generation for efficient development.

- Repository: [Swoole Project/typephp](https://github.com/swoole/typephp)
- Tags: deep-dive
- Published: 2026-08-30

---

**The TypePHP compilation pipeline consists of three discrete phases—`idle`, `prepare`, and `convert`—defined as string constants in [`src/CompilerBase.php`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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
<?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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/src/CompilerBase.php).
- Compile-time attribute phases declared in [`src/Transform/CompileTimeAttributeRegistry.php`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/src/Preprocessor.php) when moving from preparation to conversion.