# paypay/paypayopa-sdk-php architecture

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

- Interactive diagram: https://gitdiagram.com/paypay/paypayopa-sdk-php
- Repository: https://github.com/paypay/paypayopa-sdk-php

## Overview

This project is a PHP SDK designed to offer a client library for interacting with PayPay’s Open Payment API (OPA). Its purpose is to allow merchants and developers to integrate PayPay payment services effortlessly into their applications by providing a set of classes to build, send, and handle various payment operations (such as dynamic QR code generation, payment capture, refunds, and more).

##### Main components of the SDK
- Client Component: Represented by the Client class (src/Client.php) that serves as the primary interface for external users.
- Controllers: Organized in src/Controllers (e.g., Payment.php, Refund.php, User.php, Wallet.php, etc.). These encapsulate different payment operations and API endpoints.
- Models: Found in src/Models; these define the data payloads for various actions such as creating payments, capturing payment authorization, refunds, etc.
- Core/Framework Elements: Include base classes and exception handling (e.g., src/core/Controller.php, src/core/Model.php, ClientControllerException.php) common across the SDK.
- Configuration: Managed by files in src/conf (e.g., apiMappings.php, endpoints.php, config.php variants) which control API endpoints, versioning, and environment-specific settings.
- Helpers: Utility functions such as HMAC signature computation (src/helpers/utility_hmac.php).
- Testing & Mocks: The tests directory and the mock mappings directory provide test cases and simulated responses for verifying API interactions through the SDK.

##### Relationships and interactions between these components
- The Client acts as an entry point that aggregates various controllers.
- Each controller (Payment, Code, Refund, User) uses respective models to construct requests and validate responses.
- The configuration files supply the controllers and models with endpoints, API versions, and other environment-specific details.
- The helper functions (like the HMAC utilities) support security aspects such as signature verification.
- Exception classes in the core directory capture error scenarios and maintain robustness.

##### Architectural patterns and design principles
- Modular design: Separation between controllers, models, core functionalities, and configuration files.
- Encapsulation: Each controller manages a distinct aspect (payments, refunds, etc.) ensuring clear separation of responsibilities.
- Extensibility: The use of payload (model) classes with fluent setters encourages chaining and ease of use, indicating a design focused on developer ergonomics.
- Testability: The presence of unit tests and mock configurations implies a focus on reliability and maintainable code.

##### On the technologies and libraries
- PHP 7.x is the runtime environment.
- Composer is used for dependency management.
- The integration and authentication mechanisms (including HMAC signature verification) are built within the SDK.
- The repository also includes CI configuration (GitHub workflows, Travis CI integration) to ensure quality and automated testing.

- A clearly labeled “Client” component that acts as the main entry point.
- Separate nodes for:
- Controllers (Payment, Refund, Code, User, Wallet)
- Models (Payload classes such as CreateQrCodePayload, RefundPaymentPayload, etc.)
- Core components (Base classes and exception handling)
- Configuration (environment-specific files: apiMappings, endpoints, config)
- Helpers (utility functions for HMAC and other operations)
- Client calling Controllers.
- Controllers utilizing Models to build requests.
- Models interfacing with configuration details.
- Error paths routed to the Exception/ Core modules.
- Optionally, include the testing infrastructure (tests and mock responses) as part of quality assurance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry
    subgraph "Main Entry"
        Client["Client"]:::client
    end

    %% Controllers
    subgraph "Controllers"
        Payment["Payment"]:::controller
        Refund["Refund"]:::controller
        Code["Code"]:::controller
        User["User"]:::controller
        Wallet["Wallet"]:::controller
        CashBack["CashBack"]:::controller
    end

    %% Models
    subgraph "Models"
        CreateQrCodePayload["CreateQrCodePayload"]:::model
        RefundPaymentPayload["RefundPaymentPayload"]:::model
    end

    %% Core/Framework Elements
    subgraph "Core/Framework"
        ControllerCore["Controller (Base)"]:::core
        ModelCore["Model (Base)"]:::core
        ModelException["ModelException"]:::core
        ClientControllerException["ClientControllerException"]:::core
    end

    %% Configuration
    subgraph "Configuration"
        APIMappings["apiMappings"]:::conf
        Endpoints["endpoints"]:::conf
        Config["config"]:::conf
    end

    %% Helpers
    subgraph "Helpers"
        UtilityHMAC["utility_hmac"]:::helper
    end

    %% Testing & Mocks
    subgraph "Testing & Mocks"
        Tests["tests"]:::test
        Mocks["mock/mappings"]:::test
    end

    %% Connections from Client to Controllers
    Client -->|"calls"| Payment
    Client -->|"calls"| Refund
    Client -->|"calls"| Code
    Client -->|"calls"| User
    Client -->|"calls"| Wallet
    Client -->|"calls"| CashBack

    %% Controllers using Models
    Payment -->|"uses"| CreateQrCodePayload
    Refund -->|"uses"| RefundPaymentPayload
    Code -->|"may use"| CreateQrCodePayload
    User -->|"may use"| RefundPaymentPayload
    Wallet -->|"may use"| CreateQrCodePayload
    CashBack -->|"may use"| RefundPaymentPayload

    %% Models interfacing with Configuration
    CreateQrCodePayload -->|"configured_by"| APIMappings
    RefundPaymentPayload -->|"configured_by"| Endpoints
    APIMappings -->|"defined_in"| Config

    %% Error handling via Core components
    Payment -->|"errors_handled_by"| ClientControllerException
    Refund -->|"errors_handled_by"| ModelException

    %% Controllers and Models using Helpers
    Payment -->|"security_via"| UtilityHMAC
    Refund -->|"security_via"| UtilityHMAC
    Code -->|"security_via"| UtilityHMAC

    %% Testing & Mocks for quality assurance
    Tests -->|"validates"| Client
    Tests -->|"validates"| Payment
    Tests -->|"validates"| Refund
    Tests -->|"validates"| Code
    Tests -->|"validates"| User
    Tests -->|"validates"| Wallet
    Tests -->|"validates"| CashBack
    Tests -->|"validates"| CreateQrCodePayload
    Tests -->|"validates"| RefundPaymentPayload
    Mocks -->|"simulate_for"| Payment
    Mocks -->|"simulate_for"| Refund
    Mocks -->|"simulate_for"| Code
    Mocks -->|"simulate_for"| User
    Mocks -->|"simulate_for"| Wallet
    Mocks -->|"simulate_for"| CashBack

    %% Styles
    classDef client fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef controller fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef model fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef core fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef conf fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef helper fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef test fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;

    %% Click Events
    click Client "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Client.php"
    click Payment "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Controllers/Payment.php"
    click Refund "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Controllers/Refund.php"
    click Code "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Controllers/Code.php"
    click User "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Controllers/User.php"
    click Wallet "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Controllers/Wallet.php"
    click CashBack "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Controllers/CashBack.php"
    click CreateQrCodePayload "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Models/CreateQrCodePayload.php"
    click RefundPaymentPayload "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/Models/RefundPaymentPayload.php"
    click ControllerCore "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/core/Controller.php"
    click ModelCore "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/core/Model.php"
    click ModelException "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/core/ModelException.php"
    click ClientControllerException "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/core/ClientControllerException.php"
    click APIMappings "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/conf/apiMappings.php"
    click Endpoints "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/conf/endpoints.php"
    click Config "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/conf/config.php"
    click UtilityHMAC "https://github.com/paypay/paypayopa-sdk-php/blob/master/src/helpers/utility_hmac.php"
    click Tests "https://github.com/paypay/paypayopa-sdk-php/tree/master/tests"
    click Mocks "https://github.com/paypay/paypayopa-sdk-php/tree/master/mock/mappings"
```
