How flutterwave/php-v3 works
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.