# 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

```bash
# 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

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

### 2. Install Composer Dependencies

```bash
composer install
```

### 3. Verify Installation

```bash
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
<?php
class Calculator {
    public function add($a, $b) {
        return $a + $b;
    }
    
    public function multiply($a, $b) {
        return $a * $b;
    }
}
```

**main.php**:
```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

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

#### Running the Program

```bash
./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

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

#### Installing the Extension

```bash
# 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

```bash
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
<?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
<?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

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

### Run All Tests

```bash
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](INCOMPATIBLE_PHP_FEATURES.md) 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`.

```bash
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`:

```bash
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](INCOMPATIBLE_PHP_FEATURES.md)** - understand the current limitations
2. **[Compilation Modes Explained](COMPILATION_MODES.md)** - learn the two compilation modes in depth
3. **[Build Speed Research](AOT_BUILD_SPEED_RESEARCH.md)** - optimize the compilation flow

---

## 🆘 Getting Help

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

---

**Enjoy!** 🎉