# flutterwave/php-v3 architecture

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

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

## Overview

This project is an SDK for a PHP-based payment integration library now branded as “xpaywave” (previously referenced as Flutterwave). It is designed to provide a simplified way for PHP applications to interact with the xpaywave for Business v3 APIs, offering an abstraction layer that encapsulates various payment methods (card, bank transfer, mobile money, USSD, etc.) and related operations like payouts, subscriptions, refunds, and more.

##### Main Components
- Entry Points & Presentation Layer: Include files such as paymentForm.php and processPayment.php. These serve as front-facing endpoints for user interactions or web requests.
- Controller: The PaymentController (located in src/Controller) directs incoming requests to the appropriate services.
- Service Layer: Comprises multiple services (found in src/Service) that handle the distinct payment operations (e.g., CardPayment, BankTransfer, MobileMoney, etc.). Each of these components encapsulates the business logic for a specific payment method.
- Event Handlers: Under src/EventHandlers, these components (like CardEventHandler, BankTransferEventHandler, etc.) process callbacks and events following payment transactions.
- Domain Entities & Contracts: Located in directories such as src/Entities and src/Contract, these components define the structure and interactions between data models (Customer, Payload, etc.), interfaces, and factories to ensure consistency in handling payment data.
- Config and Initialization: The src/Config and helper classes (e.g., Config.php, EnvVariables.php) provide dynamic configuration settings loaded either from a .env file or passed directly as parameters.
- HTTP Adapter: The src/HttpAdapter (with classes like CurlClient) abstracts external HTTP communication for sending API requests.
- Utilities and Traits: Components in src/Util and src/Traits supply reusable functionalities and common methods (such as authentication mode management, grouping operations, and payload operations).
- Testing Infrastructure: The tests directory houses unit tests and resource files that validate different payment channels and operations.

##### Relationships and Data Flow
- How a request flows from the web entry points (paymentForm.php, processPayment.php) into the PaymentController.
- The Controller then invokes one or more service methods based on the payment channel/operation.
- Service methods utilize factories, event handlers, and underlying HTTP adapters to perform API calls.
- Configuration and utility classes drive the initial setup and parameter handling.
- Event handlers capture asynchronous callbacks and notifications, linking back to the payment flow.

##### Architectural Patterns & Principles
- Layered Architecture: Distinguish between the presentation layer (entry scripts), business logic (controller and service classes), and external integration layers (HTTP adapter and event handlers).
- Abstraction & Separation of Concerns: Interfaces and abstract classes (in src/Contract and src/AbstractPayment) neatly encapsulate common functionalities, ensuring modularity.
- Dependency Injection: The construction of the PaymentController with its dependencies (like event handlers and the xpaywave client) is a clear example of DI.
- Extensibility: The presence of a rich set of event handlers and factory classes shows the emphasis on making the SDK flexible and extendable.

##### Specific Technologies and Libraries
- PHP (version >= 7.4)
- Composer for dependency management (as evidenced by composer.json)
- PHPUnit for testing (see phpunit.xml.dist and tests folder)
- Docker (provided Docker configurations in the .docker directory) for containerized environments
- External HTTP interactions powered by the CurlClient (in src/HttpAdapter)

- Remember to replace all instances of “flutterwave” with “xpaywave” to stay consistent with the new branding.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        PF["Payment Entry Point (paymentForm.php)"]:::presentation
        PP["Payment Entry Point (processPayment.php)"]:::presentation
    end

    %% Controller Layer
    subgraph "Controller Layer"
        PC["PaymentController"]:::controller
    end

    %% Service Layer
    subgraph "Service Layer"
        SP["Service Layer (src/Service/)"]:::service
        CP["CardPayment Service"]:::service
        BP["BankTransfer Service"]:::service
        MP["MobileMoney Service"]:::service
        UP["USSD Payment Service"]:::service
    end

    %% Event Handlers
    subgraph "Event Handlers"
        EH["Event Handlers (src/EventHandlers/)"]:::event
        CEP["CardEventHandler"]:::event
        BEH["BankTransferEventHandler"]:::event
    end

    %% Domain Layer
    subgraph "Domain Layer"
        ENT["Entities (src/Entities/)"]:::domain
        CON["Contracts (src/Contract/)"]:::domain
    end

    %% Configuration
    subgraph "Configuration"
        CFG["Config (src/Config/)"]:::config
        HC["Helper: Config (src/Helper/Config.php)"]:::config
        HE["Helper: EnvVariables (src/Helper/EnvVariables.php)"]:::config
    end

    %% HTTP Adapter
    subgraph "HTTP Adapter"
        HA["HTTP Adapter (CurlClient)"]:::adapter
    end

    %% Utilities and Traits
    subgraph "Utilities"
        UT["Utilities (src/Util/)"]:::utils
        TR["Traits (src/Traits/)"]:::utils
    end

    %% Testing Infrastructure
    subgraph "Testing"
        T["Testing Infrastructure (tests/)"]:::testing
    end

    %% Connections - Flow of Payment Request
    PF -->|"routes"| PC
    PP -->|"routes"| PC

    PC -->|"invokes"| SP
    PC -->|"uses"| CFG

    SP -->|"performs API call via"| HA
    SP -->|"triggers"| EH
    SP -->|"utilizes"| ENT
    SP -->|"utilizes"| CON
    CFG -->|"configures"| SP

    %% Optional dependencies highlighting shared utilities
    UT -->|"assists"| SP
    TR -->|"assists"| SP

    %% Testing connections
    T -->|"validates"| PC
    T -->|"validates"| SP

    %% Additional event handler specifics
    EH -->|"handles events for"| CP
    EH -->|"handles events for"| BP

    %% Click Events
    click PF "https://github.com/flutterwave/php-v3/blob/master/paymentForm.php"
    click PP "https://github.com/flutterwave/php-v3/blob/master/processPayment.php"
    click PC "https://github.com/flutterwave/php-v3/blob/master/src/Controller/PaymentController.php"
    click SP "https://github.com/flutterwave/php-v3/tree/master/src/Service/"
    click EH "https://github.com/flutterwave/php-v3/tree/master/src/EventHandlers/"
    click ENT "https://github.com/flutterwave/php-v3/tree/master/src/Entities/"
    click CON "https://github.com/flutterwave/php-v3/tree/master/src/Contract/"
    click CFG "https://github.com/flutterwave/php-v3/tree/master/src/Config/"
    click HC "https://github.com/flutterwave/php-v3/blob/master/src/Helper/Config.php"
    click HE "https://github.com/flutterwave/php-v3/blob/master/src/Helper/EnvVariables.php"
    click HA "https://github.com/flutterwave/php-v3/blob/master/src/HttpAdapter/CurlClient.php"
    click UT "https://github.com/flutterwave/php-v3/tree/master/src/Util/"
    click TR "https://github.com/flutterwave/php-v3/tree/master/src/Traits/"
    click T "https://github.com/flutterwave/php-v3/tree/master/tests/"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef controller fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef service fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef event fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef domain fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef config fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef adapter fill:#F08080,stroke:#000,stroke-width:2px;
    classDef utils fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
