Math Eval Laravel Package

Technical Evaluation

Architecture Fit

• Core Use Cases: Ideal for Laravel applications requiring dynamic, safe mathematical expression evaluation (e.g., financial calculators, rule engines, or data transformation pipelines). The package’s focus on arithmetic operations, functions (e.g., sin(), log()), and variable substitution aligns with Laravel’s need for flexible yet controlled logic in business applications.
• Laravel Synergy:
  • Service Layer: Can be injected into Laravel’s service container for reusable math logic.
  • Request Handling: Integrates seamlessly with Laravel’s request pipeline for dynamic calculations (e.g., API responses, form processing).
  • Validation: Complements Laravel’s validator for sanitizing user-provided expressions.
• Anti-Patterns:
  • Not for: High-performance numerical computing (e.g., scientific simulations), symbolic math, or recursive functions.
  • Avoid in: Systems requiring real-time processing or HHVM compatibility (though HHVM is obsolete).

Integration Feasibility

• Core Functionality:
  • Supports basic arithmetic, parentheses, functions, and variables—sufficient for 80% of Laravel use cases (e.g., pricing formulas, analytics).
  • Sandboxed evaluation mitigates risks of eval()-style vulnerabilities.
• Laravel-Specific:
  • Service Provider: Can be registered as a singleton for global access.
  • Facade Pattern: Encapsulate usage behind a clean interface (e.g., Math::evaluate()).
  • Request Validation: Laravel’s Validator can restrict input to whitelisted operators/functions.
• Dependencies:
  • No external dependencies (relies on mossadal/math-parser internally, but no composer conflicts).
  • PHP 7.1+ required; Laravel’s LTS versions (5.8+) are compatible.
  • HHVM removal eliminates compatibility concerns with an obsolete runtime.

Technical Risk

Key Questions

1. Why not alternatives?

   • Compare with:
     • symfony/math: More features (e.g., matrices) but heavier.
     • league/math: Better for financial calculations.
     • php-ai/php-math: Supports symbolic math but complex.
   • Trade-off: math_eval is simpler and lighter, but lacks advanced features.

2. Input Validation Strategy

   • How will user-provided expressions be sanitized?
     • Options:
       • Regex whitelisting (e.g., /^[0-9+\-*\/().\s]+$/).
       • Allowed functions list (e.g., ['sin', 'log', 'sqrt']).
       • Laravel Policy to validate expressions before evaluation.

3. Performance Requirements

   • Expected throughput (e.g., 1,000 evaluations/sec)?
     • If high, consider:
       • Caching (Redis) for repeated expressions.
       • Offloading to a microservice (e.g., Node.js + math.js).
       • Alternative libraries (e.g., php-math-parser if maintained).

4. Long-Term Maintenance

   • Fork the repo to ensure updates (e.g., security patches).
   • Assign a maintainer to monitor for vulnerabilities.
   • Deprecation plan: If abandoned, migrate to symfony/math or league/math.

5. Error Handling

   • Define fallback behavior for malformed expressions:
     • Return null or throw a custom exception (e.g., InvalidMathExpression).
     • Log failed expressions for auditing.

6. Laravel-Specific Edge Cases

   • How will expressions interact with Laravel’s request lifecycle?
     • Example: Evaluate a formula from a form submission or API payload.
   • Will expressions be stored in the database? If so, ensure sanitization on retrieval.

Integration Approach

Stack Fit

• PHP/Laravel: Native integration with minimal overhead.
  • Service Container: Register as a singleton for global access.
  • Request Pipeline: Use in controllers, commands, or observers.
• Frontend/API:
  • API Responses: Return calculated values in JSON.
  • Blade Templates: Embed in views (e.g., dynamic pricing displays).
• Microservices:
  • Deploy as a separate service if performance is critical (e.g., high-throughput APIs).
• Anti-Fit:
  • Python/JS-heavy stacks: Consider native libraries instead.
  • Real-time systems: May introduce latency.

Migration Path

1. Proof of Concept (PoC)

   • Test basic expressions in Laravel Tinker:

     use MathEval\Evaluator;
     $evaluator = new Evaluator();
     $result = $evaluator->evaluate('2 + 2 * (3 - 1)'); // Should return 8
     

   • Validate safety with malicious input (e.g., "__destruct()").

2. Package Setup

   • Update composer.json:

     "require": {
         "langleyfoxall/math_eval": "^2.0"
     }
     

   • Run composer update.

3. Service Provider

   • Register in config/app.php or a custom provider:

     // app/Providers/MathServiceProvider.php
     public function register()
     {
         $this->app->singleton('math', function () {
             return new \MathEval\Evaluator();
         });
     }
     

4. Facade (Optional)

   • Create a facade for cleaner syntax:

     // app/Facades/Math.php
     namespace App\Facades;
     use Illuminate\Support\Facades\Facade;
     class Math extends Facade { protected static function getFacadeAccessor() { return 'math'; } }
     

   • Usage:

     $result = Math::evaluate('2 + 2'); // Returns 4
     

5. Request Integration

   • Use in controllers or form requests:

     public function calculate(Request $request)
     {
         $expression = $request->input('expression');
         $result = Math::evaluate($expression);
         return response()->json(['result' => $result]);
     }
     

   • Validate input in a Form Request:

     public function rules()
     {
         return ['expression' => 'required|safe_math_expression'];
     }
     

Compatibility

• Laravel Versions:
  • Tested on Laravel 5.8+ (PHP 7.1+). HHVM removal aligns with modern Laravel stacks.
• PHP Extensions:
  • No hard dependencies, but bcmath/gmp improve performance for large numbers.
• Database:
  • Store expressions as strings (e.g., price_formula column in a product table).
  • Sanitize on retrieval to prevent injection.

Sequencing

1. Phase 1: Core Integration
   • Implement basic evaluation in a non-critical feature (e.g., admin panel).
   • Add logging for expressions and results (e.g., Math::evaluate($expr) logs $expr and $result).

2