# libvirt/libvirt-php architecture

> Architecture diagram of the GitHub repository libvirt/libvirt-php, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/libvirt/libvirt-php
- Repository: https://github.com/libvirt/libvirt-php

## Overview

##### Main Components

a) Core Components:
- PHP Extension Interface Layer
- libvirt API Integration Layer
- Domain Management System
- Storage Management System
- Network Management System
- Stream Handling System

b) Supporting Components:
- Connection Management
- Resource Management
- Error Handling System
- Testing Framework

**PHP Application Layer**
- ↓
**PHP Extension Interface (libvirt-php)**
- ↓
**libvirt Core API**
- ↓
**Hypervisor Layer (KVM, QEMU, etc.)**

##### Component Relationships

- Connection Manager → All Other Components (as it's fundamental)
- Domain Manager ↔ Storage Manager (for VM disk operations)
- Domain Manager ↔ Network Manager (for VM network operations)
- Stream Handler ↔ Storage Manager (for I/O operations)

##### Specific Component Details

**Connection Management**
- libvirt-connection.c/h
- Connection pooling
- Authentication handling

**Domain Management**
- libvirt-domain.c/h
- VM lifecycle management
- Resource monitoring

**Storage Management**
- libvirt-storage.c/h
- Volume management
- Pool operations

**Network Management**
- libvirt-network.c/h
- Network configuration
- Interface management

##### Integration Points

Integration points with:
- PHP Runtime (top)
- libvirt API (bottom)
- Testing Framework (side)

##### Additional Elements

Include:
- Configuration Management (libvirt-php.ini)
- Error Handling System
- Logging System
- Test Suite Integration

##### Architectural Patterns

Highlight:
- Module-based architecture
- Resource pooling patterns
- Event-driven interactions

##### Notes for Implementation

- Clear separation between PHP and C layers
- Synchronous vs asynchronous operations
- Critical paths for resource management
- Version compatibility information

Keep the abstraction level focused on the architectural components while showing the key relationships between the PHP extension layer and the underlying libvirt system. This will help developers understand both the high-level structure and the specific integration points of the system.

Remember to include the recent bugfixes mentioned in the README as notes or annotations where relevant, particularly around the domain device updates and storage pool XML handling.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers
    subgraph PHP_App["PHP Application Layer"]
        App[PHP Applications]
    end

    subgraph Extension["PHP Extension Interface Layer"]
        PHPExt["PHP Extension Interface"]:::core
        ErrorHandler["Error Handling System"]:::utility
        Config["Configuration Management"]:::utility
    end

    subgraph Core["Core Components Layer"]
        ConnMgr["Connection Management"]:::core
        DomainMgr["Domain Management"]:::core
        StorageMgr["Storage Management"]:::core
        NetworkMgr["Network Management"]:::core
        StreamHandler["Stream Handling"]:::core
        NodeMgr["Node Management"]:::core
        SocketMgr["Socket Management"]:::core
    end

    subgraph LibVirt["libvirt Core API Layer"]
        LibVirtAPI["libvirt API"]:::api
    end

    subgraph Hypervisor["Hypervisor Layer"]
        KVM["KVM"]:::hypervisor
        QEMU["QEMU"]:::hypervisor
    end

    %% Testing and Documentation
    subgraph Support["Support Components"]
        TestFrame["Testing Framework"]:::testing
        APIDoc["API Documentation"]:::docs
        Examples["Example Implementation"]:::docs
    end

    %% Connections
    App --> PHPExt
    PHPExt --> ConnMgr
    ConnMgr --> |Resource Management| DomainMgr
    ConnMgr --> |Resource Management| StorageMgr
    ConnMgr --> |Resource Management| NetworkMgr
    ConnMgr --> |Resource Management| StreamHandler
    ConnMgr --> |Resource Management| NodeMgr
    ConnMgr --> |Resource Management| SocketMgr
    
    DomainMgr <--> StorageMgr
    DomainMgr <--> NetworkMgr
    StreamHandler <--> StorageMgr
    
    DomainMgr --> LibVirtAPI
    StorageMgr --> LibVirtAPI
    NetworkMgr --> LibVirtAPI
    NodeMgr --> LibVirtAPI
    
    LibVirtAPI --> KVM
    LibVirtAPI --> QEMU
    
    ErrorHandler -.-> PHPExt
    Config -.-> PHPExt
    TestFrame -.-> PHPExt

    %% Click Events
    click PHPExt "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-php.c"
    click ConnMgr "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-connection.c"
    click DomainMgr "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-domain.c"
    click StorageMgr "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-storage.c"
    click NetworkMgr "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-network.c"
    click StreamHandler "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-stream.c"
    click NodeMgr "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-node.c"
    click Config "https://github.com/libvirt/libvirt-php/blob/master/src/libvirt-php.ini"
    click TestFrame "https://github.com/libvirt/libvirt-php/tree/master/tests"
    click APIDoc "https://github.com/libvirt/libvirt-php/tree/master/doc/html"
    click ErrorHandler "https://github.com/libvirt/libvirt-php/blob/master/src/util.c"
    click SocketMgr "https://github.com/libvirt/libvirt-php/blob/master/src/sockets.c"
    click Examples "https://github.com/libvirt/libvirt-php/tree/master/examples"

    %% Styles
    classDef core fill:#2374f7,stroke:#000,stroke-width:2px,color:#fff
    classDef utility fill:#ffd700,stroke:#000,stroke-width:2px
    classDef api fill:#1abc9c,stroke:#000,stroke-width:2px,color:#fff
    classDef hypervisor fill:#e74c3c,stroke:#000,stroke-width:2px,color:#fff
    classDef testing fill:#9b59b6,stroke:#000,stroke-width:2px,color:#fff
    classDef docs fill:#95a5a6,stroke:#000,stroke-width:2px

    %% Legend
    subgraph Legend
        CoreComp["Core Component"]:::core
        UtilComp["Utility Component"]:::utility
        APIComp["API Component"]:::api
        HyperComp["Hypervisor Component"]:::hypervisor
        TestComp["Testing Component"]:::testing
        DocComp["Documentation"]:::docs
    end
```
