README

English | 中文

This bundle provides an enhanced Expression Language experience for Symfony applications with additional functions, values, and Chinese syntax support.

Table of Contents

• Features
• Installation
• Requirements
• Configuration
• Quick Start
• Available Function Providers
• Available Value Providers
• Chinese Syntax Support
• Advanced Usage
• Contributing
• License

Features

• Enhanced Symfony Expression Language engine with Chinese syntax support
• Date and math function providers for expressions
• Automatic expression validation via Doctrine event subscribers
• Value providers for common date operations (today, current timestamp, etc.)
• Support for custom expression functions and value providers
• Attribute for expression validation on entity properties

Installation

To install the bundle, require it using Composer:

composer require tourze/symfony-ecol-bundle

Register the bundle in your config/bundles.php:

return [
    // ...
    Tourze\EcolBundle\EcolBundle::class => ['all' => true],
    // ...
];

Requirements

• PHP 8.2 or higher
• Symfony 7.3 or higher
• Doctrine ORM

Configuration

The bundle works out of the box without additional configuration. However, you can customize it by creating custom function providers and value providers.

Custom Function Providers

Create a service that implements function provider interface and tag it:

# config/services.yaml
services:
    App\Expression\MyFunctionProvider:
        tags: ['ecol.function.provider']

Custom Value Providers

Create a service that implements value provider interface and tag it:

# config/services.yaml
services:
    App\Expression\MyValueProvider:
        tags: ['ecol.value.provider']

Quick Start

Basic Usage

Use the engine service directly in your code:

use Symfony\Component\ExpressionLanguage\Expression;
use Tourze\EcolBundle\Service\Engine;

class YourService
{
    public function __construct(
        private readonly Engine $engine
    ) {
    }
    
    public function evaluateExpression(): mixed
    {
        // Basic expression
        $result = $this->engine->evaluate('1 + 1');
        
        // Expression with variables
        $result = $this->engine->evaluate('a + b', ['a' => 5, 'b' => 10]);
        
        // Expression with Chinese syntax
        $result = $this->engine->evaluate('a 大于 b 并且 c 等于 d', [
            'a' => 10, 
            'b' => 5, 
            'c' => 'test', 
            'd' => 'test'
        ]);
        
        return $result;
    }
}

Validate Entity Properties

Use the Expression attribute to validate expressions in entity properties:

use Tourze\EcolBundle\Attribute\Expression;

class YourEntity
{
    #[Expression]
    private string $conditionExpression = 'a > b && c == 1';
    
    // ...
}

Available Function Providers

• DateFunctionProvider: Date manipulation functions
• MathFunctionProvider: Mathematical operations
• ExceptionFunctionProvider: Exception handling in expressions
• ServiceFunctionProvider: Service access in expressions

Available Value Providers

• Today: Provides today's date (variable name: 当天日期)
• TodayRange: Provides today's start and end timestamps (variable name: 当天日期范围)
• CurrentTimestamp: Provides current timestamp (variable name: 当前时间戳)
• CurrentYear: Provides current year
• CurrentMonth: Provides current month
• CurrentWeekday0 - CurrentWeekday6: Provides weekday dates (variable name: 本周周日日期 etc.)

Chinese Syntax Support

The engine automatically converts Chinese operators to their programming equivalents:

Advanced Usage

Working with Complex Expressions

For complex business logic, you can combine multiple operators and functions:

$expression = '(age >= 18 并且 country == "CN") 或者 (vip_level > 3 且 balance >= 1000)';
$result = $engine->evaluate($expression, [
    'age' => 25,
    'country' => 'CN', 
    'vip_level' => 2,
    'balance' => 500
]);

Custom Expression Functions

Implement the ExpressionFunctionProviderInterface to add custom functions:

use Symfony\Component\ExpressionLanguage\ExpressionFunction;
use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;

class CustomFunctionProvider implements ExpressionFunctionProviderInterface
{
    public function getFunctions(): array
    {
        return [
            new ExpressionFunction('custom_function', 
                function ($arg) { return sprintf('custom_function(%s)', $arg); },
                function ($arguments, $arg) { return $arg * 2; }
            ),
        ];
    }
}

Entity Validation with Complex Rules

Use expressions for complex entity validation rules:

#[Expression]
private string $businessRule = 'status == "active" && (priority > 5 || urgent == true)';

Contributing

Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.