compiler/docs/en/QUICKSTART.md

PHP AOT Compiler Quick Start Guide

🚀 5-Minute Quick Start

This guide will help you get started with the PHP AOT compiler within 5 minutes.

---

📦 Prerequisites

System Requirements

• Operating System: Linux (Ubuntu 20.04+ recommended)
• PHP Version: PHP 8.0+
• Compiler: GCC 9.0+ or Clang 10.0+
• Memory: at least 2GB RAM
• Disk Space: at least 500MB

Installing Dependencies

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential php-cli php-dev clang-format

# CentOS/RHEL
sudo yum install -y gcc gcc-c++ php php-devel clang-tools-extra

---

🔧 Installation Steps

1. Clone the Project

git clone https://github.com/your-org/php-aot-compiler.git
cd php-aot-compiler

2. Install Composer Dependencies

composer install

3. Verify Installation

php bin/tpc.php --help

If you see the help information, the installation was successful!

---

🎯 Basic Usage

Example Project Structure

Suppose we have a simple PHP project:

my-project/
├── src/
│   ├── Calculator.php
│   └── main.php

Calculator.php:

<?php
class Calculator {
    public function add($a, $b) {
        return $a + $b;
    }
    
    public function multiply($a, $b) {
        return $a * $b;
    }
}

main.php:

<?php
require_once 'Calculator.php';

function main() {
    $calc = new Calculator();
    
    echo "5 + 3 = " . $calc->add(5, 3) . "\n";
    echo "4 * 7 = " . $calc->multiply(4, 7) . "\n";
}

---

📝 Compilation Modes

Mode One: Binary Executable (recommended for beginners)

Compilation Command

php bin/tpc.php my-project/src/ -o my-app

Running the Program

./my-app

Output

5 + 3 = 8
4 * 7 = 28

✅ Advantages:

• Runs standalone without a PHP environment
• Simple deployment
• Better performance

⚠️ Note: a main() function is required

---

Mode Two: PHP Extension

Compilation Command

php bin/tpc.php my-project/src/ --mode=ext -o calculator

Installing the Extension

# Copy the .so file to the PHP extension directory
sudo cp calculator.so $(php-config --extension-dir)/

# Add to php.ini
echo "extension=calculator" | sudo tee /etc/php/8.1/cli/conf.d/30-calculator.ini

Using the Extension

php -m | grep calculator  # verify the extension is loaded

✅ Advantages:

• Integrates with existing PHP projects
• Can be used in php-fpm
• Suitable for web applications

⚠️ Note: no main() function is needed

---

🎨 Code Conventions

✅ Correct Code Structure

<?php
// Class and function definitions (allowed at the global scope)
class MyClass {
    public function doSomething() {
        return "Something";
    }
}

function helperFunction() {
    return "Helper";
}

const MY_CONSTANT = 'value';

// Executable code must be inside the main() function
function main() {
    $obj = new MyClass();
    echo $obj->doSomething();
    echo helperFunction();
    echo MY_CONSTANT;
}

❌ Incorrect Code Structure

<?php
// ❌ Free-floating executable code (not allowed)
echo "Hello World";  // error!

some_function_call();  // error!

for ($i = 0; $i < 10; $i++) {  // error!
    echo $i;
}

---

🧪 Running Tests

Run a Single Test

PHPT=1 php run-tests.php tests/compiler/arrow_fn/001.phpt

Run All Tests

PHPT=1 php run-tests.php tests/compiler/

Viewing Test Results

PASS Arrow Functions - PHP 8.1+ short closure syntax
FAIL Some test
=====================================================================
Number of tests :   100                100
Tests passed    :    95 ( 95.0%)
Tests failed    :     5 (  5.0%)

---

💡 Best Practices

1. Project Organization

project/
├── src/              # source code
│   ├── Classes/      # class files
│   ├── Functions/    # function library
│   └── main.php      # entry file
├── tests/            # test files
└── build/            # compilation output

2. Naming Conventions

• File names use lowercase, with words separated by underscores: my_class.php
• Class names use PascalCase: MyClass
• Function names use camelCase: myFunction

3. Performance Tips

• Avoid unnecessary object creation
• Use scalar type declarations
• Reduce the use of global variables
• Prefer arrays over object collections

---

🔍 FAQ

Q: Compilation fails with "Not implemented"

A: First check the Compatibility Checklist to determine whether it is a TypePHP design rule, partially supported, or not yet implemented.

Q: How do I debug the compiled program?

A: Use --dry to generate only the intermediate code, and specify a directory with --build-dir.

php bin/tpc.php src/ --dry --build-dir /tmp/typephp-build

Q: What should I do if compilation is slow?

A: Use the parallel compilation option -j:

php bin/tpc.php src/ -o app -j4  # use 4 processes

---

📚 Next Steps

After completing the quick start, the following are recommended reads:

1. Compatibility Checklist - understand the current limitations
2. Compilation Modes Explained - learn the two compilation modes in depth
3. Build Speed Research - optimize the compilation flow

---

🆘 Getting Help

• 📖 View the full documentation: docs/
• 🐛 Report issues: [GitHub Issues]
• 💬 Community discussion: [forum/chat room link]

---

Enjoy! 🎉