Smplang Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: smplang is a lightweight, expression-evaluation DSL (Domain-Specific Language) designed to replace eval() safely. It fits well in Laravel applications where:
  • Dynamic calculations (e.g., pricing rules, conditional logic) are needed without exposing raw PHP.
  • User-provided input must be sanitized (avoiding eval() security risks).
  • Simple scripting is required (e.g., template logic, rule engines).
• Laravel Synergy:
  • Can integrate with Laravel’s service container for dependency injection (e.g., resolving objects/methods dynamically).
  • Complements Laravel’s Blade or Livewire for client-side-like logic in server-side contexts.
  • Potential use in policy/authorization logic (e.g., evaluating complex permission rules).
• Anti-Patterns:
  • Not a full-fledged templating engine (e.g., no HTML/JS output). Avoid for view rendering.
  • Not a workflow engine (e.g., no state management or async tasks). Use Laravel Queues or Task Scheduling for complex flows.

Integration Feasibility

• PHP 8.0+ Requirement: Aligns with Laravel’s current LTS (10.x/11.x) but may block legacy projects (pre-8.0).
• Dependency-Free: Zero external dependencies (beyond PHP), reducing bloat.
• Magic Methods Support: Enables dynamic object/method calls via __call/__get, useful for:
  • Laravel Eloquent models (e.g., user->getAttribute('dynamic_property')).
  • Custom classes with proxy behavior.
• Exception Handling: Improved error messages (1.0.1+) help debugging, but custom exceptions may need wrapping for Laravel’s App\Exceptions\Handler.

Technical Risk

Key Questions

1. What is the scope of expressions?
   • Simple math (2 + 2) vs. complex object traversal (user->orders->sum('amount'))?
   • Need for custom functions (e.g., date_diff(), array_filter())?
2. How will expressions interact with Laravel services?
   • Will they access database models, API clients, or cached data?
   • Require dependency injection (e.g., new \App\Services\Calculator())?
3. Security Boundaries
   • Who writes expressions? Users? Admins? How to prevent code injection?
   • Need expression whitelisting (e.g., only allow +, -, user->*).
4. Error Handling
   • Should failures return null/false or throw Laravel-specific exceptions?
   • Need localization for error messages?
5. Performance
   • Will expressions be pre-compiled (e.g., cached in Redis)?
   • Impact on Laravel’s request lifecycle (e.g., memory usage during evaluation)?

Integration Approach

Stack Fit

• Laravel Core:
  • Service Provider: Register Smplang as a singleton/binder in AppServiceProvider.
  • Facade: Create Smplang::evaluate($expression) for clean syntax.
  • Service Container: Bind custom objects/functions for expression resolution.
• Eloquent Integration:
  • Accessors/Mutators: Use __get/__call to expose model attributes dynamically.
  • Query Builder: Evaluate expressions in whereRaw() or custom scopes.
• Livewire/Alpine: Evaluate client-like logic server-side (e.g., Smplang::evaluate($userInput)).
• Validation: Replace complex Validator::extend() rules with expressions (e.g., "age > 18 && hasLicense == true").

Migration Path

1. Pilot Phase:
   • Start with non-critical expressions (e.g., simple calculations in reports).
   • Use a wrapper class to log all evaluated expressions (audit trail).
2. Core Integration:
   • Replace eval() or create_function() in legacy code.
   • Migrate policy rules or authorization logic to smplang.
3. Security Hardening:
   • Implement a whitelist validator for allowed functions/objects.
   • Use Laravel’s tap() to sandbox expressions (e.g., restrict file_* functions).

Compatibility

• PHP 8.0+: Ensure Laravel project is upgraded (or use a polyfill for older features).
• PSR-4 Autoloading: Works natively with Laravel’s Composer setup.
• Magic Methods: Test with:
  • Eloquent models (ensure __call/__get don’t conflict).
  • Custom classes (e.g., new class { public function __call($name) { ... } }).
• Laravel Features:
  • Events: Trigger EvaluatingExpression events for observability.
  • Caching: Cache compiled expressions if deterministic (e.g., Smplang::compile($expr)).

Sequencing

1. Phase 1: Basic arithmetic/logic (e.g., if (user->tier == 'premium && balance > 0')).
2. Phase 2: Object traversal (e.g., order->items->sum('price')).
3. Phase 3: Custom functions (e.g., Smplang::addFunction('discount', fn($price) => $price * 0.9)).
4. Phase 4: Integration with Laravel services (e.g., Smplang::resolve('user->getFreshOrders()')).

Operational Impact

Maintenance

• Proactive:
  • Dependency Updates: Monitor leongrdic/smplang for PHP 8.1+ compatibility.
  • Testing: Add to Laravel’s test suite (e.g., phpunit tests for edge cases).
• Reactive:
  • Exception Handling: Extend Laravel’s Handler to log SmplangException details.
  • Deprecation: Plan for fork if upstream is abandoned (MIT license allows this).

Support

• Documentation:
  • Add Laravel-specific examples (e.g., evaluating Eloquent queries).
  • Document security best practices (whitelisting, sandboxing).
• Troubleshooting:
  • Debugging Tool: Create a Smplang::debug($expr) method to dump parsed AST.
  • Error Templates: Map smplang exceptions to user-friendly messages (e.g., "Invalid expression: user->nonexistent").
• Community:
  • Contribute Laravel integration tests to the upstream repo.
  • Share use cases (e.g., dynamic pricing rules) to encourage maintenance.

Scaling

• Performance:
  • Caching: Cache compiled expressions for repeated use (e.g., Smplang::cache($expr, 60)).
  • Batch Processing: Evaluate multiple expressions in a single pass (e.g., for bulk operations).
• Concurrency:
  • Stateless Evaluations: Ensure expressions don’t rely on request-specific data (e.g., session).
  • Queue Jobs: Offload complex evaluations to queue:work (e.g., SmplangJob::dispatch($expr)).
• Resource Usage:
  • Memory: Monitor for deep object traversals (e.g., user->orders->items->...).
  • CPU: Avoid recursive expressions (e.g., function foo() { foo() }).

Failure Modes

Ramp-Up

• Onboarding:
  • Developer Docs: Add to `lar