Moneyphp Percentage Laravel Package

Technical Evaluation

Architecture Fit

• Complementary to MoneyPHP: The package extends the moneyphp/money library by adding percentage-based calculations (e.g., VAT, discounts, or fees), which aligns well with financial applications requiring precise arithmetic on monetary values.
• Value Object Pattern: Leverages the same immutable, type-safe design as moneyphp/money, ensuring consistency in domain modeling for financial operations.
• Use Case Specificity: Ideal for e-commerce, tax calculation, or billing systems where percentages of monetary amounts are critical (e.g., dynamic pricing, tax tiers, or surcharges).
• Limitation: Niche focus—only relevant if the application already uses moneyphp/money or requires percentage-based monetary logic.

Integration Feasibility

• Low Coupling: Designed as a standalone value object; integrates seamlessly with existing moneyphp/money workflows without invasive changes.
• Dependency Graph: Requires moneyphp/money (≥v3.0) and PHP ≥8.0. Compatibility with other libraries (e.g., ramsey/uuid, symfony/options-resolver) is indirect but manageable.
• Type Safety: Leverages PHP 8+ features (e.g., named arguments, union types) for robust integration with modern Laravel (v10+) or PHP applications.
• Testing: Minimal test coverage (2 stars, low activity) suggests validation of edge cases (e.g., floating-point precision, negative percentages) may be required.

Technical Risk

• Precision Handling: Floating-point arithmetic for percentages (e.g., 19.9% VAT) may introduce rounding errors. Mitigation: Use Money::ofExact() or custom rounding strategies.
• Thread Safety: Stateless value objects are inherently thread-safe, but concurrent modifications to shared Money instances could require synchronization.
• Backward Compatibility: Last release in 2023; no breaking changes expected, but long-term support is unproven.
• Documentation Gaps: Lack of examples or API docs may slow adoption. Workaround: Reverse-engineer from tests or moneyphp/money patterns.

Key Questions

1. Does the application use moneyphp/money?
   • If not, evaluate whether the overhead of adopting two libraries (Money + Percentage) justifies the use case.
2. How are percentages currently handled?
   • Compare existing solutions (e.g., raw floats, bcmath) to assess value-add.
3. What precision requirements exist?
   • For tax calculations, legal compliance may demand exact arithmetic (e.g., Money::ofExact()).
4. Is the team familiar with MoneyPHP?
   • Steep learning curve if the library is new; consider internal abstractions or wrappers.
5. Are there alternative packages?
   • Evaluate moneyphp/money-percentage (if it exists) or league/math for broader functionality.

Integration Approach

Stack Fit

• Laravel/Eloquent: Works well with Laravel’s dependency injection and service containers. Register the package via Composer and bind interfaces (if any) in config/app.php.
• Symfony Components: Compatible with Symfony’s PropertyAccess, OptionsResolver, or Validator if used for form handling or validation.
• APIs/CLI: Lightweight enough for microservices or CLI tools where monetary percentages are calculated (e.g., invoicing scripts).
• Non-Laravel PHP: Direct integration possible, but Laravel-specific features (e.g., service providers) won’t apply.

Migration Path

1. Adopt moneyphp/money First:
   • Replace primitive floats/strings with Money objects for all monetary values.
   • Example: float $price → Money::USD(100).
2. Introduce Percentage Calculations:
   • Replace ad-hoc percentage logic (e.g., $tax = $price * 0.19) with Percentage::of(19)->applyTo($money).
   • Example:

     $subtotal = Money::of(1000, 'USD');
     $vat = Percentage::of(19)->applyTo($subtotal); // Money::of(190, 'USD')
     

3. Incremental Replacement:
   • Start with non-critical paths (e.g., reporting) before core transactions.
   • Use feature flags to toggle between old/new logic during migration.

Compatibility

• PHP Version: Requires PHP ≥8.0 (Laravel 9+). For older stacks, consider polyfills or forks.
• MoneyPHP Version: Tested with moneyphp/money v3.0+. Downgrade may be needed for legacy apps.
• Database: No direct ORM impact, but ensure Money objects are serialized/deserialized correctly (e.g., via JSON or custom accessors).
• Caching: Immutable objects are cache-friendly, but avoid caching intermediate percentage calculations if inputs vary.

Sequencing

1. Setup:
   • Install via Composer: composer require mesilov/moneyphp-percentage.
   • Configure autoloading (if not using PSR-4).
2. Core Integration:
   • Replace percentage calculations in domain services (e.g., TaxCalculator, DiscountService).
3. Validation:
   • Test edge cases: zero percentages, negative values, fractional cents.
4. Performance:
   • Benchmark against existing logic; percentages add minimal overhead (~1–5% per operation).
5. Documentation:
   • Create internal docs for team onboarding, including examples for common use cases (e.g., tiered taxes).

Operational Impact

Maintenance

• Low Overhead: Minimal moving parts; updates align with moneyphp/money releases.
• Dependency Management:
  • Monitor moneyphp/money for breaking changes (e.g., PHP 8.2+ features).
  • Consider forking if the package stagnates (MIT license permits).
• Testing:
  • Add unit tests for percentage calculations, especially for:
    • Floating-point edge cases (e.g., 0.1 + 0.2 !== 0.3).
    • Currency conversion interactions (if applicable).

Support

• Community: Limited activity (2 stars); rely on issue trackers or MoneyPHP’s community.
• Debugging:
  • Use Money::getAmount() and Percentage::getValue() for logging/debugging.
  • Leverage moneyphp/money’s built-in assertions (e.g., assertEquals()).
• Fallbacks:
  • Implement a decorator pattern to wrap Percentage with retry logic for transient failures (unlikely, but possible in high-throughput systems).

Scaling

• Stateless Design: Scales horizontally without modification; no shared state.
• Performance:
  • Operations are O(1); suitable for high-frequency transactions (e.g., payment processing).
  • Avoid recalculating percentages in loops—cache results if inputs are repeatable.
• Database:
  • Store percentages as integers (e.g., 19 for 19%) to avoid floating-point storage issues.
  • Use Money’s getAmount() for persistence (e.g., JSON fields).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1–2 hours: Review moneyphp/money and Percentage APIs.
  • 1 day: Implement a proof-of-concept (e.g., VAT calculation for a product).
• Team Training:
  • Highlight differences from raw floats (e.g., immutability, precision).
  • Provide cheat sheets for common operations (e.g., adding percentages, chaining).
• Adoption Barriers:
  • Resistance to Change: Demonstrate bugs fixed (e.g., rounding errors) or features enabled (e.g., audit trails via immutable objects).
  • Legacy Code: Use adapter classes to wrap existing percentage logic gradually.