# xenira/ext-php-rs architecture

> Architecture diagram of the GitHub repository xenira/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/xenira/ext-php-rs
- Repository: https://github.com/xenira/ext-php-rs

## Overview

##### Main Components

a) Core Framework Components:
- Rust Extension API Layer
- Zend API Bridge
- Type System Converter
- Macro System
- Embedding System

b) Build System:
- Cargo Build Pipeline
- PHP Extension Compiler
- Stub Generator

##### Component Relationships and Architecture

**[PHP Application Layer]**
- ↕
**[PHP Extension Interface]**
- ↕
**[ext-php-rs Framework]**

- Macros    Types    Builders

**[Rust-Zend Bridge Layer]**
- ↕
**[Zend Engine API]**

##### Key Elements to Highlight

a) Framework Core (src/):
- Type System (/src/types/)
- Builder System (/src/builders/)
- Embedding System (/src/embed/)
- Zend API Interface (/src/zend/)

b) Macro System (crates/macros/):
- Function Macros
- Class Macros
- Module Macros
- Implementation Macros

c) CLI Tools (crates/cli/):
- Stub Generation
- Installation Tools
- Build Management

##### Data Flow Indicators

- Bidirectional communication between PHP and Rust layers
- Type conversion flows
- Macro expansion paths
- Build pipeline flow

##### Implementation Details

- FFI boundary between Rust and PHP
- Macro processing pipeline
- Type conversion system
- Extension loading mechanism

- Safety boundaries
- Type conversion mechanisms
- Memory management
- Error handling paths

Remember to indicate the optional features (closure support, anyhow error handling) as modular components that can be enabled or disabled.

This system design should help developers understand both how to use the framework and how it works internally, while maintaining a clear separation of concerns between the various components.

## Diagram (Mermaid)

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

    subgraph "PHP Extension Interface"
        ExtInterface["Extension Interface"]:::interface
    end

    subgraph "ext-php-rs Framework"
        subgraph "Core Components"
            TypeSystem["Type System"]:::core
            BuilderSystem["Builder System"]:::core
            EmbedSystem["Embedding System"]:::core
        end

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

        subgraph "Build Tools"
            StubGen["Stub Generator"]:::build
            BuildScript["Build Script"]:::build
            CLITools["CLI Tools"]:::build
        end
    end

    subgraph "Rust-Zend Bridge Layer"
        ZendBridge["Zend API Bridge"]:::bridge
        FFILayer["FFI Interface"]:::bridge
    end

    subgraph "Zend Engine API"
        ZendAPI["Zend Engine"]:::zend
    end

    %% Relationships
    PHPApp <--> ExtInterface
    ExtInterface <--> ZendBridge
    ZendBridge <--> FFILayer
    FFILayer <--> ZendAPI

    TypeSystem <--> ZendBridge
    BuilderSystem <--> ZendBridge
    EmbedSystem <--> FFILayer

    ClassMacros --> BuilderSystem
    FuncMacros --> BuilderSystem
    ModuleMacros --> BuilderSystem
    ImplMacros --> BuilderSystem

    StubGen --> ExtInterface
    BuildScript --> ZendBridge
    CLITools --> BuildScript

    %% Styling
    classDef php fill:#FFF4CC,stroke:#FFD700
    classDef interface fill:#D4F4FA,stroke:#00CED1
    classDef core fill:#E6E6FA,stroke:#9370DB
    classDef macro fill:#98FB98,stroke:#32CD32
    classDef build fill:#F0E68C,stroke:#DAA520
    classDef bridge fill:#B0C4DE,stroke:#4682B4
    classDef zend fill:#FFB6C1,stroke:#DC143C

    %% Click events
    click TypeSystem "https://github.com/Xenira/ext-php-rs/blob/master/src/types/mod.rs"
    click BuilderSystem "https://github.com/Xenira/ext-php-rs/tree/master/src/builders"
    click EmbedSystem "https://github.com/Xenira/ext-php-rs/blob/master/src/embed/mod.rs"
    click ClassMacros "https://github.com/Xenira/ext-php-rs/blob/master/crates/macros/src/class.rs"
    click FuncMacros "https://github.com/Xenira/ext-php-rs/blob/master/crates/macros/src/function.rs"
    click ModuleMacros "https://github.com/Xenira/ext-php-rs/blob/master/crates/macros/src/module.rs"
    click ImplMacros "https://github.com/Xenira/ext-php-rs/blob/master/crates/macros/src/impl_.rs"
    click StubGen "https://github.com/Xenira/ext-php-rs/blob/master/src/describe/stub.rs"
    click BuildScript "https://github.com/Xenira/ext-php-rs/blob/master/build.rs"
    click CLITools "https://github.com/Xenira/ext-php-rs/blob/master/crates/cli/src/main.rs"
    click ZendBridge "https://github.com/Xenira/ext-php-rs/tree/master/src/zend"
    click FFILayer "https://github.com/Xenira/ext-php-rs/blob/master/src/embed/ffi.rs"
```
