# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Swoole-Compiler is an AOT (Ahead-of-Time) compiler that translates PHP source code to C++, then compiles it with GCC/Clang/MSVC into native binaries. It supports Linux (primary), macOS, and Windows.

**Prerequisites**: PHP 8.2+, GCC 9+ (C++17), CMake 3.24+. The `swoole/phpx` extension must be compiled (see README.md).

## Build & Test Commands

```bash
# Install PHP dependencies
composer install

# Compile a PHP project to a native binary
php bin/compiler.php <path-to-project-or-file>

# Run all PHPUnit tests
./vendor/bin/phpunit

# Run a single PHPUnit test class
./vendor/bin/phpunit phpunit/src/AstNodeTypeTest.php

# Run PHPT integration tests (all)
php run-tests.php tests/aot/

# Run a single PHPT test
php run-tests.php tests/aot/arrays.phpt
```

## Architecture

### Translation Pipeline

The compiler follows a 4-stage pipeline, orchestrated by `src/Php/Translator.php` (the main entry point):

1. **prepare()** — Scan PHP files, collect symbol declarations and dependencies, topological-sort for compilation order
2. **convert()** — Parse PHP AST via `nikic/php-parser`, translate each node to C++ source code
3. **compile()** — Invoke the platform C++ compiler (GCC/Clang/MSVC) on generated `.cc` files
4. **build()** — Link object files into a native binary executable

### Class Hierarchy

```
src/Core/Translator (abstract base — indent/output/mode helpers)
 └─ src/Php/CompilerBase (core PHP→C++ translation logic)
     ├─ uses traits: AstNodeType, FuncCallOptimizer, ClosureGenerator,
     │    PlaceHolderGenerator, PropertyPromotion, MagicMethodDetector
     └─ src/Php/Preprocessor (scanning, symbol tables, dependency sort, YAML config)
         └─ src/Php/Translator (full pipeline: prepare→convert→compile→build)
             └─ src/Php/CompilerTest (test-only subclass, used by PHPUnit tests)
```

### Key Components

| Directory | Purpose |
|-----------|---------|
| `src/Php/Entity/` | Data classes: `ClassDef`, `FunctionDef`, `MethodDef`, `PropertyDef`, `ConstantDef`, `InterfaceDef` |
| `src/Php/Generator/` | Codegen helpers: `ClosureGenerator`, `PlaceHolderGenerator`, `PropertyPromotion`, `Utils` |
| `src/Php/Backend/` | Compiler abstraction: `CompilerBackend` (abstract) → `Gcc`, `Clang`, `Msvc`. Factory pattern via `CompilerFactory` |
| `src/Php/Platform/` | OS abstraction: `PlatformBase` → `Linux`, `Macos`, `Windows`. Factory via `PlatformFactory` |
| `src/Php/Context/` | `ScopeContext` and `FunctionContext` for variable scoping and type tracking |
| `src/Php/Exception/` | `SyntaxError`, `Unsupported`, `DynamicCall`, `PlaceHolder`, `Skip`, `Redo`, `TestError` |
| `src/Php/Parser/` | Special-purpose parsers like `StdContainerParser` (C++ std container foreach support) |
| `src/Php/Reflection.php` | Static helpers wrapping PHP reflection (internal class/function detection) |
| `src/Php/Symbol.php` | Maps PHP operations to `phpx` C++ API symbol names |
| `src/Php/FileScanner.php` | Recursive file discovery with extension filtering (supports `.php`, `.cpp`, `.c`, `.s`, `.m`, `.mm`) |
| `src/Php/ArgInfo.php` | Generates C function argument info structures for internal function registration |
| `src/Php/Extractor.php` | Extracts interfaces from PHP classes |
| `src/Php/Visitor.php` | Base `NodeVisitorAbstract` extension (skeleton for custom AST visitors) |
| `src/Python/Translator.php` | Python-to-C++ translator (separate from the PHP pipeline) |

### Configuration

- `project.yml` — per-project build config (name, build-mode, C++ standard, compiler flags, sources, resources/icon)
- Command-line arguments and YAML config are merged in `Preprocessor`, with CLI taking highest priority

### Generated Output

Generated `.cc` and `.o` files land in `build/` directory. The compiled binary is named from `project.yml`'s `name` field (default: `app`).

### Test Infrastructure

- **PHPUnit tests** (`phpunit/src/`) — unit/integration tests for compiler internals. Bootstrap at `phpunit/bootstrap.php` defines a `BaseTest` class with an `exec()` helper that runs the compiler and expects a `TestError` exception containing a given string
- **PHPT tests** (`tests/aot/`) — end-to-end tests using the standard PHPT format (`run-tests.php`). Each `.phpt` contains PHP source and expected output sections

When writing new compiler tests, use `CompilerTest::create(ROOT_PATH)` (in `src/Php/CompilerTest.php`) which sets `forTest = true` to enable test-specific behavior without writing files to disk.