How mewebstudio/pos works
Main Components of the System
• Client / Application Layer: Represents the consumer code that calls the library to “create” a POS gateway, send payment requests, receive and process responses.
• Factory & Configuration: The factories (e.g., PosFactory, AccountFactory, CryptFactory, Request/Response DataMapper Factories) together with the configuration files (pos_production.php, pos_test.php) encapsulate the instantiation of bank-specific gateway implementations.
• Data Mapping: Divided into RequestDataMapper and ResponseDataMapper – these components transform the request/response data between the standardized format used by the library and the proprietary formats expected or returned by each bank.
• Cryptography: Located in “src/Crypt”, this subsystem provides hashing and encryption mechanisms using various algorithms. It implements interfaces (like CryptInterface) and concrete classes (e.g., EstPosCrypt, GarantiPosCrypt) to correctly sign or verify transaction data.
• Entity: Classes under “src/Entity” (for Account and Card) are used to encapsulate the information needed to perform operations and store payment related data.
• HTTP Client: Although the library does not mandate a specific one, it makes use of PSR-18 implementations (with a Client under “src/Client/HttpClient.php”) to submit HTTP requests to the bank gateways.
• Event Dispatching and Logging: The library supports PSR-3 for logging and PSR-14 for event dispatching (see “src/Event” and the README’s discussion of event-driven hooks, such as the “Before3DFormHashCalculatedEvent”). This allows additional functionality or debugging across the transaction lifecycle.
• Exception Handling: “src/Exceptions” captures a variety of custom exceptions ensuring robust error handling throughout the payment process.
• Test & Examples: The “tests” directory confirms the unit and functional testing approach, while the “examples” folder shows practical implementations and how to integrate the library with different bank endpoints in real-world scenarios.
Relationships and Interactions
• The Client (or consuming application) first loads the configuration, then uses the Factory (PosFactory) to create a specific Gateway instance by injecting the appropriate Account (from “src/Entity/Account”) and configuration data.
• Once a Gateway is instantiated (e.g., GarantiPos, EstV3Pos), it processes a payment request. Here, the Gateway calls upon the appropriate Request Data Mapper to format the request properly and uses the Crypt module to generate any necessary signatures or hash values.
• After building the request, the library uses an HTTP Client (via PSR-18) to communicate with the bank’s API endpoints (which might be defined in the configuration).
• When a response is received, it flows back through a Response Data Mapper for normalization before being passed back (or converted) into a common format that the client application understands.
• During these processes, events may be dispatched (for example, to log or modify requests/responses), and exceptions may be thrown if something goes wrong. Factories and abstract base classes help ensure that any bank-specific differences are encapsulated in their respective components.
Architectural Patterns and Design Principles
• Use of the Factory Design Pattern to instantiate bank-specific gateway classes through one common interface.
• Strategy/Polymorphism: The implementation of multiple Crypt classes, DataMappers, and Gateways follows a polymorphic design allowing one to easily switch strategies (or payment models) without changing the client code.
• Separation of Concerns: The project cleanly separates concerns among configuration, HTTP communication, data mapping, cryptography, and error handling.
• Compliance with PSR Standards (PSR-3, PSR-14, PSR-18) demonstrates adherence to common PHP best practices for interoperability and extensibility.
Additional Notes Specific to This Project
• That the “examples” and “tests” directories serve as practical verification points and confirm that the implementations follow the unified API.
• That the system encapsulates both request and response normalization so that client code remains the same regardless of which bank is being used.