# davidcole1340/ext-php-rs architecture

> Architecture diagram of the GitHub repository davidcole1340/ext-php-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davidcole1340/ext-php-rs
- Repository: https://github.com/davidcole1340/ext-php-rs

## Overview

##### Main Components

a) Core Components:
- Rust Extension Core (src/)
- PHP Zend Engine Interface
- Macro System (crates/macros/)
- CLI Tools (crates/cli/)
- Type System Bridge
- Embedding System

b) Integration Layer:
- FFI (Foreign Function Interface)
- Zend API Bindings
- Type Conversion System

**┌─────────────────────────────────────────────────────────┐**
- PHP Application Layer                   │
- ┬─────────────────────────────────┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- Extension Interface                     │
- ┌───────────────┐  ┌──────────────┐  ┌──────────────┐ │
- PHP Functions │  │PHP Classes   │  │Constants      │ │
- ┘  └──────────────┘  └──────────────┘ │
- ┬─────────────────────────────────┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- Macro System Layer                      │
- ┌───────────────┐  ┌──────────────┐  ┌──────────────┐ │
- Function Macros│  │Class Macros  │  │Module Macros  │ │
- ┘  └──────────────┘  └──────────────┘ │
- ┬─────────────────────────────────┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- Type System Bridge                      │
- ┌───────────────┐  ┌──────────────┐  ┌──────────────┐ │
- Type Convert. │  │Zval Handling │  │Error Handling │ │
- ┘  └──────────────┘  └──────────────┘ │
- ┬─────────────────────────────────┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- FFI/Binding Layer                       │
- ┌───────────────┐  ┌──────────────┐  ┌──────────────┐ │
- Zend API     │  │ PHP Embed    │  │Native Bridge │ │
- ┘  └──────────────┘  └──────────────┘ │
- ┘

##### Key Elements to Highlight

a) Core Features:
- Type conversion system (src/convert.rs)
- Macro processing (crates/macros/)
- Zend API integration (src/zend/)
- Embedding support (src/embed/)

b) Extension Points:
- Custom type conversion implementation points
- Macro customization options
- Error handling pathways

##### Implementation Details

- The separation between PHP and Rust layers
- How macros transform Rust code into PHP-compatible extensions
- The type conversion system's role
- Error propagation paths
- How the FFI layer interfaces with PHP's internals

- How their Rust code is transformed into PHP extensions
- Where to implement custom functionality
- How different components interact
- The flow of data through the system

Remember to maintain a balance between detail and clarity, focusing on the architectural aspects that are most relevant to developers working with the system.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph PHP ["PHP Application Layer"]
        PHPApp[PHP Application]
    end

    subgraph EXT ["Extension Interface"]
        Functions["PHP Functions"]:::interface
        Classes["PHP Classes"]:::interface
        Constants["Constants"]:::interface
    end

    subgraph MACRO ["Macro System Layer"]
        FuncMacros["Function Macros"]:::macro
        ClassMacros["Class Macros"]:::macro
        ModuleMacros["Module Macros"]:::macro
    end

    subgraph TYPE ["Type System Bridge"]
        TypeConv["Type Conversion"]:::type
        ZvalHandle["Zval Handling"]:::type
        ErrorHandle["Error Handling"]:::type
    end

    subgraph FFI ["FFI/Binding Layer"]
        ZendAPI["Zend API"]:::ffi
        PHPEmbed["PHP Embed"]:::ffi
        NativeBridge["Native Bridge"]:::ffi
    end

    subgraph BUILDERS ["Builder Components"]
        ClassBuilder["Class Builder"]:::builder
        FunctionBuilder["Function Builder"]:::builder
        ModuleBuilder["Module Builder"]:::builder
        SAPIBuilder["SAPI Builder"]:::builder
    end

    subgraph TYPES ["Type System Components"]
        ArrayHandler["Array Handling"]:::typecomp
        ObjectHandler["Object Handling"]:::typecomp
        StringHandler["String Handling"]:::typecomp
        IteratorSupport["Iterator Support"]:::typecomp
        CallableSupport["Callable Support"]:::typecomp
    end

    subgraph ZEND ["Zend Engine Integration"]
        ClassHandler["Class Handling"]:::zend
        FunctionHandler["Function Handling"]:::zend
        ModuleHandler["Module Handling"]:::zend
        ExceptionHandler["Exception Handling"]:::zend
    end

    %% Relationships
    PHPApp <--> Functions & Classes & Constants
    Functions & Classes & Constants <--> FuncMacros & ClassMacros & ModuleMacros
    FuncMacros & ClassMacros & ModuleMacros <--> TypeConv & ZvalHandle & ErrorHandle
    TypeConv & ZvalHandle & ErrorHandle <--> ZendAPI & PHPEmbed & NativeBridge
    
    BUILDERS <--> TYPE
    TYPES <--> TYPE
    ZEND <--> FFI

    %% Styling
    classDef interface fill:#2196F3,stroke:#1565C0,color:white
    classDef macro fill:#4CAF50,stroke:#2E7D32,color:white
    classDef type fill:#FFC107,stroke:#FFA000,color:black
    classDef ffi fill:#9E9E9E,stroke:#616161,color:white
    classDef builder fill:#3F51B5,stroke:#303F9F,color:white
    classDef typecomp fill:#FF9800,stroke:#F57C00,color:white
    classDef zend fill:#795548,stroke:#5D4037,color:white

    %% Click events
    click Functions "https://github.com/davidcole1340/ext-php-rs/blob/master/src/builders/function.rs"
    click Classes "https://github.com/davidcole1340/ext-php-rs/blob/master/src/builders/class.rs"
    click Constants "https://github.com/davidcole1340/ext-php-rs/blob/master/src/constant.rs"
    click FuncMacros "https://github.com/davidcole1340/ext-php-rs/blob/master/crates/macros/src/function.rs"
    click ClassMacros "https://github.com/davidcole1340/ext-php-rs/blob/master/crates/macros/src/class.rs"
    click ModuleMacros "https://github.com/davidcole1340/ext-php-rs/blob/master/crates/macros/src/module.rs"
    click TypeConv "https://github.com/davidcole1340/ext-php-rs/blob/master/src/convert.rs"
    click ZvalHandle "https://github.com/davidcole1340/ext-php-rs/blob/master/src/types/zval.rs"
    click ErrorHandle "https://github.com/davidcole1340/ext-php-rs/blob/master/src/error.rs"
    click ZendAPI "https://github.com/davidcole1340/ext-php-rs/blob/master/src/zend/mod.rs"
    click PHPEmbed "https://github.com/davidcole1340/ext-php-rs/blob/master/src/embed/mod.rs"
    click NativeBridge "https://github.com/davidcole1340/ext-php-rs/blob/master/src/ffi.rs"
    click ClassBuilder "https://github.com/davidcole1340/ext-php-rs/blob/master/src/builders/class.rs"
    click FunctionBuilder "https://github.com/davidcole1340/ext-php-rs/blob/master/src/builders/function.rs"
    click ModuleBuilder "https://github.com/davidcole1340/ext-php-rs/blob/master/src/builders/module.rs"
    click SAPIBuilder "https://github.com/davidcole1340/ext-php-rs/blob/master/src/builders/sapi.rs"
    click ArrayHandler "https://github.com/davidcole1340/ext-php-rs/blob/master/src/types/array.rs"
    click ObjectHandler "https://github.com/davidcole1340/ext-php-rs/blob/master/src/types/object.rs"
    click StringHandler "https://github.com/davidcole1340/ext-php-rs/blob/master/src/types/string.rs"
    click IteratorSupport "https://github.com/davidcole1340/ext-php-rs/blob/master/src/types/iterator.rs"
    click CallableSupport "https://github.com/davidcole1340/ext-php-rs/blob/master/src/types/callable.rs"
    click ClassHandler "https://github.com/davidcole1340/ext-php-rs/blob/master/src/zend/class.rs"
    click FunctionHandler "https://github.com/davidcole1340/ext-php-rs/blob/master/src/zend/function.rs"
    click ModuleHandler "https://github.com/davidcole1340/ext-php-rs/blob/master/src/zend/module.rs"
    click ExceptionHandler "https://github.com/davidcole1340/ext-php-rs/blob/master/src/zend/try_catch.rs"
```
