Skip to content

Commit 5c2fcda

Browse files
author
苏青安
committed
README调整
1 parent 7379abd commit 5c2fcda

File tree

3 files changed

+283
-78
lines changed

3 files changed

+283
-78
lines changed

‎README.md

Lines changed: 85 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,110 @@
11
# hejunjie/simple-rule-engine
22

3-
一个轻量、易用的 PHP 规则引擎，支持多条件组合与动态规则执行，适用于业务规则判断、数据校验等场景。
3+
<div align="center">
4+
<a href="./README.md">English</a>｜<a href="./README.zh-CN.md">简体中文</a>
5+
<hr width="50%"/>
6+
</div>
7+
8+
A lightweight and flexible PHP rule engine supporting complex conditions and dynamic rule execution—ideal for business logic evaluation and data validation.
49

510
---
611

7-
## 🧠 用途 & 初衷
12+
## 🧠 Purpose & Intent
813

9-
日常写 PHP 的时候，我们经常会遇到一类“判断性”的业务逻辑，比如：
14+
When writing PHP on a daily basis, we often encounter "conditional" business logic, such as:
1015

11-
- 某个用户是否符合某个条件？
12-
- 当前订单是否满足参加活动的资格？
13-
- 某条数据是否需要做进一步处理？
16+
- Does a certain user meet a specific condition?
17+
- Does the current order qualify for a promotional event?
18+
- Does a particular piece of data require further processing?
1419

15-
这些逻辑写起来很简单，就是一个又一个的 if、and、or，但当你遇到 5 条、10 条甚至几十条判断条件混在一起逐渐变得越来越多....
20+
These types of logic are simple at first, just a series of if, and, or statements. But when you start dealing with 5, 10, or even dozens of conditions all tangled together, things can quickly get messy.
1621

17-
一开始还能接受，后来每次加条件、改条件、删条件都像拆炸弹，别说别人接手了，连你自己两周后回来看都要皱眉。
22+
At first, it’s manageable, but after a while, adding, changing, or removing conditions starts to feel like defusing a bomb. Forget about handing it off to someone else – even you, two weeks later, will look at it and cringe.
1823

19-
于是我花了一些时间，写了这个 PHP Composer 包，它的目标是：用更清晰、更灵活的方式去组织这些判断条件，让判断逻辑更结构化，也更容易复用。
24+
So, I spent some time developing this PHP Composer package with the goal of organizing these conditional checks in a clearer, more flexible way. The idea is to make the logic more structured and easier to reuse.
2025

2126
---
2227

23-
## ✨ 特点
28+
## ✨ Features
2429

25-
- **简单易用**：通过直观的 API 快速构建规则，支持 AND / OR 组合逻辑。
26-
- **高度可扩展**：内置常用操作符，支持自定义操作符注册机制，满足多样化业务需求。
27-
- **灵活的数据结构**：规则与数据解耦，支持数组、对象等多种数据形式。
28-
- **详细的规则评估**：可获取每条规则的评估结果，便于调试与日志记录。
30+
- **Easy to Use**: Quickly build rules with an intuitive API, supporting AND/OR combination logic.
31+
- **Highly Extensible**: Includes common built-in operators and supports a custom operator registration mechanism to meet diverse business needs.
32+
- **Flexible Data Structures**: Decouples rules from data, supporting multiple data formats such as arrays and objects.
33+
- **Detailed Rule Evaluation**: Allows access to the evaluation results of each rule, making debugging and logging easier.
2934

3035
---
3136

32-
## 📦 安装
37+
## 📦 Installation
3338

34-
使用 Composer 安装：
39+
Install via Composer:
3540

3641
```bash
3742
composer require hejunjie/simple-rule-engine
3843
```
3944

4045
---
4146

42-
## 🛠️ 用法示例
47+
## 🛠️ Usage Examples
4348

4449
```php
4550
use Hejunjie\SimpleRuleEngine\Rule;
4651
use Hejunjie\SimpleRuleEngine\Engine;
4752

48-
// 定义规则
53+
// Define Rules
4954
$rules = [
50-
new Rule('age', '>=', 18, '年龄必须大于等于18岁'),
51-
new Rule('country', '==', 'SG', '国家必须是新加坡'),
55+
new Rule('age', '>=', 18, 'Age must be greater than or equal to 18'),
56+
new Rule('country', '==', 'SG', 'Country must be Singapore'),
5257
];
5358

54-
// 待评估的数据
59+
// Data to be evaluated
5560
$data = [
5661
'age' => 20,
5762
'country' => 'SG',
5863
];
5964

60-
// 评估结果
61-
$result = Engine::evaluate($rules, $data, 'AND'); // 返回 true 或 false
65+
// Evaluation Result
66+
$result = Engine::evaluate($rules, $data, 'AND'); // Return true or false
6267

63-
// 获取详细评估信息
68+
// Get Detailed Evaluation Information
6469
$details = Engine::evaluateWithDetails($rules, $data);
6570
/*
66-
返回示例：
71+
Return Example:
6772
[
68-
['description' => '年龄必须大于等于18岁', 'passed' => true],
69-
['description' => '国家必须是新加坡', 'passed' => true],
73+
['description' => 'Age must be greater than or equal to 18', 'passed' => true],
74+
['description' => 'Country must be Singapore', 'passed' => true],
7075
]
7176
*/
7277
```
7378

7479
---
7580

76-
## 🧩 内置操作符
77-
78-
| 操作符 | 描述 | 额外说明 |
79-
| ---------------- | ---------------- | -------------------------------- |
80-
| ​`==`​ | 等于 | 无 |
81-
| ​`!=`​ | 不等于 | 无 |
82-
| ​`>`​ | 大于 | 无 |
83-
| ​`>=`​ | 大于等于 | 无 |
84-
| ​`<`​ | 小于 | 无 |
85-
| ​`<=`​ | 小于等于 | 无 |
86-
| ​`in`​ | 包含于集合中 | 数组：[内容 1,内容 2,...] |
87-
| ​`not_in`​ | 不包含于集合中 | 数组：[内容 1,内容 2,...] |
88-
| ​`contains`​ | 包含字符串 | 无 |
89-
| ​`not_contains`​ | 不包含字符串 | 无 |
90-
| ​`start_swith`​ | 以指定字符串开头 | 无 |
91-
| ​`end_swith`​ | 以指定字符串结尾 | 无 |
92-
| ​`between`​ | 在指定范围内 | 数组：[最大值,最小值] |
93-
| ​`not_between`​ | 不在指定范围内 | 数组：[最大值,最小值] |
94-
| ​`before_date`​ | 日期早于 | 任意常规日期格式，包括时间戳均可 |
95-
| ​`after_date`​ | 日期晚于 | 任意常规日期格式，包括时间戳均可 |
96-
| ​`date_equal`​ | 日期相等 | 任意常规日期格式，包括时间戳均可 |
97-
98-
你也可以通过注册机制添加自定义操作符。
81+
## 🧩 Built-in Operators
82+
83+
| Operator | Description | Additional Notes |
84+
| ---------------- | -------------------------- | ----------------------------------------------------- |
85+
| ​`==`​ | Equal to | None |
86+
| ​`!=`​ | Not equal to | None |
87+
| ​`>`​ | Greater than | None |
88+
| ​`>=`​ | Greater than or equal to | None |
89+
| ​`<`​ | Less than | None |
90+
| ​`<=`​ | Less than or equal to | None |
91+
| ​`in`​ | In a set | Array: [item1, item2, ...] |
92+
| ​`not_in`​ | Not in a set | Array: [item1, item2, ...] |
93+
| ​`contains`​ | Contains substring | None |
94+
| ​`not_contains`​ | Does not contain substring | None |
95+
| ​`start_swith`​ | Starts with | None |
96+
| ​`end_swith`​ | Ends with | None |
97+
| ​`between`​ | Within range | Array: [min, max] |
98+
| ​`not_between`​ | Outside range | Array: [min, max] |
99+
| ​`before_date`​ | Date is before | Supports any common date format, including timestamps |
100+
| ​`after_date`​ | Date is after | Supports any common date format, including timestamps |
101+
| ​`date_equal`​ | Date is equal to | Supports any common date format, including timestamps |
102+
103+
You can also add custom operators through the registration mechanism.
99104

100105
---
101106

102-
## 🔌 自定义操作符
107+
## 🔌 Custom Operators
103108

104109
实现 `OperatorInterface`​ 接口，并通过 `OperatorFactory`​ 注册：
105110

@@ -110,20 +115,20 @@ use Hejunjie\SimpleRuleEngine\OperatorFactory;
110115
class CustomizeOperator implements OperatorInterface
111116
{
112117
/**
113-
* 评估方法
118+
* Evaluation Method
114119
*
115-
* @param mixed $fieldValue 用户输入数据
116-
* @param mixed $ruleValue 对比数据
120+
* @param mixed $fieldValue field Value
121+
* @param mixed $ruleValue rule Value
117122
*
118123
* @return bool
119124
*/
120125
public function evaluate(mixed $fieldValue, mixed $ruleValue): bool
121126
{
122-
// TODO: 实现判断逻辑
127+
// TODO: Implement the evaluation logic
123128
}
124129

125130
/**
126-
* 操作符名称
131+
* Operator Name
127132
*
128133
* @return string
129134
*/
@@ -133,13 +138,13 @@ class CustomizeOperator implements OperatorInterface
133138
}
134139
}
135140

136-
// 注册自定义操作符 customize
141+
// Register custom operator with customize
137142
$factory = OperatorFactory::getInstance();
138143
$factory->register(new CustomizeOperator());
139144

140-
// 可以在定义规则时使用 customize
145+
// You can use customize when defining rules
141146
$rules = [
142-
new Rule('field', 'customize', 'value', '自定义规则描述'),
147+
new Rule('field', 'customize', 'value', 'Custom rule description'),
143148
...
144149
...
145150
];
@@ -148,43 +153,46 @@ $rules = [
148153

149154
---
150155

151-
## 🎯 应用场景
156+
## 🎯 Use Cases
152157

153-
- **表单数据验证**：根据用户输入动态验证字段值。
154-
- **业务规则判断**：如订单处理、权限控制等。
155-
- **数据过滤与筛选**：根据规则筛选符合条件的数据集。
156-
- **配置驱动的逻辑控制**：通过配置文件定义规则，实现灵活的业务逻辑。
158+
- **Form Data Validation**: Dynamically validate field values based on user input.
159+
- **Business Rule Evaluation**: Apply rules for scenarios like order processing, access control, etc.
160+
- **Data Filtering and Selection**: Filter datasets based on predefined rules.
161+
- **Config-Driven Logic Control**: Define rules via configuration files to enable flexible business logic.
157162

158163
---
159164

160-
## 🔧 更多工具包（可独立使用，也可统一安装）
165+
## 🔧 Additional Toolkits (Can be used independently or installed together)
161166

162-
本项目最初是从 [hejunjie/tools](https://github.com/zxc7563598/php-tools) 拆分而来，如果你想一次性安装所有功能组件，也可以使用统一包：
167+
This project was originally extracted from [hejunjie/tools](https://github.com/zxc7563598/php-tools).
168+
To install all features in one go, feel free to use the all-in-one package:
163169

164170
```bash
165171
composer require hejunjie/tools
166172
```
167173

168-
当然你也可以按需选择安装以下功能模块：
174+
Alternatively, feel free to install only the modules you need：
175+
176+
[hejunjie/utils](https://github.com/zxc7563598/php-utils) - A lightweight and practical PHP utility library that offers a collection of commonly used helper functions for files, strings, arrays, and HTTP requests—designed to streamline development and support everyday PHP projects.
169177

170-
[hejunjie/cache](https://github.com/zxc7563598/php-cache) - 多层缓存系统，基于装饰器模式。
178+
[hejunjie/cache](https://github.com/zxc7563598/php-cache) - A layered caching system built with the decorator pattern. Supports combining memory, file, local, and remote caches to improve hit rates and simplify cache logic.
171179

172-
[hejunjie/china-division](https://github.com/zxc7563598/php-china-division) - 中国省市区划分数据包。
180+
[hejunjie/china-division](https://github.com/zxc7563598/php-china-division) - Regularly updated dataset of China's administrative divisions with ID-card address parsing. Distributed via Composer and versioned for use in forms, validation, and address-related features
173181

174-
[hejunjie/error-log](https://github.com/zxc7563598/php-error-log) - 责任链日志上报系统。
182+
[hejunjie/error-log](https://github.com/zxc7563598/php-error-log) - An error logging component using the Chain of Responsibility pattern. Supports multiple output channels like local files, remote APIs, and console logs—ideal for flexible and scalable logging strategies.
175183

176-
[hejunjie/utils](https://github.com/zxc7563598/php-utils) - 常用工具方法集合。
184+
[hejunjie/mobile-locator](https://github.com/zxc7563598/php-mobile-locator) - A mobile number lookup library based on Chinese carrier rules. Identifies carriers and regions, suitable for registration checks, user profiling, and data archiving.
177185

178-
[hejunjie/address-parser](https://github.com/zxc7563598/php-address-parser) - 收货地址智能解析工具，支持从非结构化文本中提取用户/地址信息。
186+
[hejunjie/address-parser](https://github.com/zxc7563598/php-address-parser) - An intelligent address parser that extracts name, phone number, ID number, region, and detailed address from unstructured text—perfect for e-commerce, logistics, and CRM systems.
179187

180-
[hejunjie/mobile-locator](https://github.com/zxc7563598/php-mobile-locator) - 国内手机号归属地 & 运营商识别。
188+
[hejunjie/url-signer](https://github.com/zxc7563598/php-url-signer) - A PHP library for generating URLs with encryption and signature protection—useful for secure resource access and tamper-proof links.
181189

182-
[hejunjie/url-signer](https://github.com/zxc7563598/php-url-signer) - URL 签名工具，支持对 URL 进行签名和验证。
190+
[hejunjie/google-authenticator](https://github.com/zxc7563598/php-google-authenticator) - A PHP library for generating and verifying Time-Based One-Time Passwords (TOTP). Compatible with Google Authenticator and similar apps, with features like secret generation, QR code creation, and OTP verification.
183191

184-
[hejunjie/google-authenticator](https://github.com/zxc7563598/php-google-authenticator) - Google Authenticator 及类似应用的密钥生成、二维码创建和 OTP 验证。
192+
[hejunjie/simple-rule-engine](https://github.com/zxc7563598/php-simple-rule-engine) - A lightweight and flexible PHP rule engine supporting complex conditions and dynamic rule execution—ideal for business logic evaluation and data validation.
185193

186-
👀 所有包都遵循「轻量实用、解放双手」的原则，能单独用，也能组合用，自由度高，欢迎 star 🌟 或提 issue。
194+
👀 All packages follow the principles of being lightweight and practical — designed to save you time and effort. They can be used individually or combined flexibly. Feel free to ⭐ star the project or open an issue anytime!
187195

188196
---
189197

190-
该库后续将持续更新，添加更多实用功能。欢迎大家提供建议和反馈，我会根据大家的意见实现新的功能，共同提升开发效率。
198+
This library will continue to be updated with more practical features. Suggestions and feedback are always welcome — I’ll prioritize new functionality based on community input to help improve development efficiency together.

0 commit comments

Comments
 (0)