How vaened/php-price-engine works
Main Components
• Price Engine Core – The library’s entry point and configuration elements (e.g., PriceEngineConfig, helper classes).
• Cashier Abstraction – The core interface with two concrete implementations:
• SimpleCashier (operating on a gross price concept)
• RegularCashier (operating on unit-price + taxes)
• Adjustments and Handlers – All the classes inside the “Adjustments” directory form the “adjustment” layer. These include:
• Adjustment base classes and various specific adjustments (Charge, Discount).
• Taxation adjustments, split into Inclusive and Exclusive (with related error handling, e.g., InvalidTaxEncoding).
• The “Handlers” folder holds classes (ExclusiveAdjustmentHandler, InclusiveAdjustmentHandler) responsible for applying these adjustments.
• Monetary Types – Classes that encapsulate money and amount details:
• Money (e.g., Amount, Price, NonTaxableItem, Taxable, etc.)
• Additional Supporting Classes – Such as Modifier, Helper, Cacheable concerns, and utility classes in tests to represent codes and summaries.
Relationships and Interactions
• An external client creates an Amount (using either taxable or taxexempt approaches) that wraps a monetary value (via the Brick\Money library).
• The client then creates a Cashier (either Simple or Regular) using that Amount along with configuration of taxes (inclusive or exclusive), discounts, and charges.
• The Cashier coordinates between:
• Its internal adjustment mechanism (using adjusted classes from “Adjustments” and “Handlers”) to apply calculations.
• The Money components that represent prices.
• Adjustments (taxes, discounts, charges) are applied to the financial value based on the structure defined in the adjustment layers.
• After operations (like updating quantity, applying discounts, adding charges), the Cashier produces a Summary with subtotal, total, and possibly individual tax/charge/discount computations.
Architectural Patterns and Design Principles
• Modularity and Separation of Concerns – The project is organized into clearly defined layers (domain logic in “src” with separate namespaces for Money, Cashiers, Adjustments, and Handlers).
• Extensibility – The design offers extension points. For instance, new “cashier” implementations can extend the base Cashier, and new types of adjustments can be integrated.
• Domain-Driven Design – The use of clear domain concepts (such as Amount, TaxCodes, Discounts, Charges) aids in encapsulating business rules.
Relevant Technologies/Frameworks
• PHP – The main programming language.
• Composer – For dependency management (as indicated in composer.json).
• Brick\Money – An external library used to handle precise monetary calculations.
• PHPUnit – For running tests (supported by the phpunit.xml and tests directory).
• Docker – A Dockerfile is provided, to help containerize or run the library in controlled environments.
• GitHub Actions – Workflow configuration (.github/workflows/tests.yml) to automate builds and tests.