{"id":13593267,"url":"https://github.com/bobthecow/Ruler","last_synced_at":"2025-04-09T02:33:00.054Z","repository":{"id":39380216,"uuid":"1906921","full_name":"bobthecow/Ruler","owner":"bobthecow","description":"A simple stateless production rules engine for modern PHP","archived":false,"fork":false,"pushed_at":"2022-06-27T14:53:05.000Z","size":285,"stargazers_count":1064,"open_issues_count":10,"forks_count":140,"subscribers_count":65,"default_branch":"main","last_synced_at":"2025-03-30T10:04:56.997Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bobthecow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-06-16T17:34:13.000Z","updated_at":"2025-03-24T06:58:11.000Z","dependencies_parsed_at":"2022-09-15T19:42:09.349Z","dependency_job_id":null,"html_url":"https://github.com/bobthecow/Ruler","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobthecow%2FRuler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobthecow%2FRuler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobthecow%2FRuler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobthecow%2FRuler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bobthecow","download_url":"https://codeload.github.com/bobthecow/Ruler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247471518,"owners_count":20944158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T16:01:18.582Z","updated_at":"2025-04-09T02:32:55.046Z","avatar_url":"https://github.com/bobthecow.png","language":"PHP","funding_links":[],"categories":["Table of Contents","杂项","PHP","目录","Miscellaneous","结构( Architectural )","Architectural Architectural"],"sub_categories":["Architectural","建筑 Architectural"],"readme":"Ruler\n=====\n\nRuler is a simple stateless production rules engine for PHP 5.3+.\n\n[![Package version](http://img.shields.io/packagist/v/ruler/ruler.svg?style=flat-square)](https://packagist.org/packages/ruler/ruler)\n[![Build status](https://img.shields.io/github/workflow/status/bobthecow/Ruler/Unit%20Tests/main.svg?style=flat-square)](https://github.com/bobthecow/Ruler/actions?query=branch:main)\n[![StyleCI](https://styleci.io/repos/1906921/shield)](https://styleci.io/repos/1906921)\n\nRuler has an easy, straightforward DSL\n--------------------------------------\n\n... provided by the RuleBuilder:\n\n```php\n$rb = new RuleBuilder;\n$rule = $rb-\u003ecreate(\n    $rb-\u003elogicalAnd(\n        $rb['minNumPeople']-\u003elessThanOrEqualTo($rb['actualNumPeople']),\n        $rb['maxNumPeople']-\u003egreaterThanOrEqualTo($rb['actualNumPeople'])\n    ),\n    function() {\n        echo 'YAY!';\n    }\n);\n\n$context = new Context([\n    'minNumPeople' =\u003e 5,\n    'maxNumPeople' =\u003e 25,\n    'actualNumPeople' =\u003e fn() =\u003e 6,\n]);\n\n$rule-\u003eexecute($context); // \"Yay!\"\n```\n\n\n### Of course, if you're not into the whole brevity thing\n\n... you can use it without a RuleBuilder:\n\n```php\n$actualNumPeople = new Variable('actualNumPeople');\n$rule = new Rule(\n    new Operator\\LogicalAnd([\n        new Operator\\LessThanOrEqualTo(new Variable('minNumPeople'), $actualNumPeople),\n        new Operator\\GreaterThanOrEqualTo(new Variable('maxNumPeople'), $actualNumPeople)\n    ]),\n    function() {\n        echo 'YAY!';\n    }\n);\n\n$context = new Context([\n    'minNumPeople' =\u003e 5,\n    'maxNumPeople' =\u003e 25,\n    'actualNumPeople' =\u003e fn() =\u003e 6,\n]);\n\n$rule-\u003eexecute($context); // \"Yay!\"\n```\n\nBut that doesn't sound too fun, does it?\n\n\nThings you can do with your Ruler\n---------------------------------\n\n### Compare things\n\n```php\n// These are Variables. They'll be replaced by terminal values during Rule evaluation.\n\n$a = $rb['a'];\n$b = $rb['b'];\n\n// Here are bunch of Propositions. They're not too useful by themselves, but they\n// are the building blocks of Rules, so you'll need 'em in a bit.\n\n$a-\u003egreaterThan($b);                      // true if $a \u003e $b\n$a-\u003egreaterThanOrEqualTo($b);             // true if $a \u003e= $b\n$a-\u003elessThan($b);                         // true if $a \u003c $b\n$a-\u003elessThanOrEqualTo($b);                // true if $a \u003c= $b\n$a-\u003eequalTo($b);                          // true if $a == $b\n$a-\u003enotEqualTo($b);                       // true if $a != $b\n$a-\u003estringContains($b);                   // true if strpos($b, $a) !== false\n$a-\u003estringDoesNotContain($b);             // true if strpos($b, $a) === false\n$a-\u003estringContainsInsensitive($b);        // true if stripos($b, $a) !== false\n$a-\u003estringDoesNotContainInsensitive($b);  // true if stripos($b, $a) === false\n$a-\u003estartsWith($b);                       // true if strpos($b, $a) === 0\n$a-\u003estartsWithInsensitive($b);            // true if stripos($b, $a) === 0\n$a-\u003eendsWith($b);                         // true if strpos($b, $a) === len($a) - len($b)\n$a-\u003eendsWithInsensitive($b);              // true if stripos($b, $a) === len($a) - len($b)\n$a-\u003esameAs($b);                           // true if $a === $b\n$a-\u003enotSameAs($b);                        // true if $a !== $b\n```\n\n\n### Math even more things\n\n```php\n$c = $rb['c'];\n$d = $rb['d'];\n\n// Mathematical operators are a bit different. They're not Propositions, so\n// they don't belong in rules all by themselves, but they can be combined\n// with Propositions for great justice.\n\n$rb['price']\n  -\u003eadd($rb['shipping'])\n  -\u003egreaterThanOrEqualTo(50)\n\n// Of course, there are more.\n\n$c-\u003eadd($d);          // $c + $d\n$c-\u003esubtract($d);     // $c - $d\n$c-\u003emultiply($d);     // $c * $d\n$c-\u003edivide($d);       // $c / $d\n$c-\u003emodulo($d);       // $c % $d\n$c-\u003eexponentiate($d); // $c ** $d\n$c-\u003enegate();         // -$c\n$c-\u003eceil();           // ceil($c)\n$c-\u003efloor();          // floor($c)\n```\n\n\n### Reason about sets\n\n```php\n$e = $rb['e']; // These should both be arrays\n$f = $rb['f'];\n\n// Manipulate sets with set operators\n\n$e-\u003eunion($f);\n$e-\u003eintersect($f);\n$e-\u003ecomplement($f);\n$e-\u003esymmetricDifference($f);\n$e-\u003emin();\n$e-\u003emax();\n\n// And use set Propositions to include them in Rules.\n\n$e-\u003econtainsSubset($f);\n$e-\u003edoesNotContainSubset($f);\n$e-\u003esetContains($a);\n$e-\u003esetDoesNotContain($a);\n```\n\n\n### Combine Rules\n\n```php\n// Create a Rule with an $a == $b condition\n$aEqualsB = $rb-\u003ecreate($a-\u003eequalTo($b));\n\n// Create another Rule with an $a != $b condition\n$aDoesNotEqualB = $rb-\u003ecreate($a-\u003enotEqualTo($b));\n\n// Now combine them for a tautology!\n// (Because Rules are also Propositions, they can be combined to make MEGARULES)\n$eitherOne = $rb-\u003ecreate($rb-\u003elogicalOr($aEqualsB, $aDoesNotEqualB));\n\n// Just to mix things up, we'll populate our evaluation context with completely\n// random values...\n$context = new Context([\n    'a' =\u003e rand(),\n    'b' =\u003e rand(),\n]);\n\n// Hint: this is always true!\n$eitherOne-\u003eevaluate($context);\n```\n\n\n### Combine more Rules\n\n```php\n$rb-\u003elogicalNot($aEqualsB);                  // The same as $aDoesNotEqualB :)\n$rb-\u003elogicalAnd($aEqualsB, $aDoesNotEqualB); // True if both conditions are true\n$rb-\u003elogicalOr($aEqualsB, $aDoesNotEqualB);  // True if either condition is true\n$rb-\u003elogicalXor($aEqualsB, $aDoesNotEqualB); // True if only one condition is true\n```\n\n\n### `evaluate` and `execute` Rules\n\n`evaluate()` a Rule with Context to figure out whether it is true.\n\n```php\n$context = new Context([\n    'userName' =\u003e fn() =\u003e $_SESSION['userName'] ?? null,\n]);\n\n$userIsLoggedIn = $rb-\u003ecreate($rb['userName']-\u003enotEqualTo(null));\n\nif ($userIsLoggedIn-\u003eevaluate($context)) {\n    // Do something special for logged in users!\n}\n```\n\nIf a Rule has an action, you can `execute()` it directly and save yourself a\ncouple of lines of code.\n\n```php\n$hiJustin = $rb-\u003ecreate(\n    $rb['userName']-\u003eequalTo('bobthecow'),\n    function() {\n        echo \"Hi, Justin!\";\n    }\n);\n\n$hiJustin-\u003eexecute($context);  // \"Hi, Justin!\"\n```\n\n\n### Even `execute` a whole grip of Rules at once\n\n```php\n$hiJon = $rb-\u003ecreate(\n    $rb['userName']-\u003eequalTo('jwage'),\n    function() {\n        echo \"Hey there Jon!\";\n    }\n);\n\n$hiEveryoneElse = $rb-\u003ecreate(\n    $rb-\u003elogicalAnd(\n        $rb-\u003elogicalNot($rb-\u003elogicalOr($hiJustin, $hiJon)), // The user is neither Justin nor Jon\n        $userIsLoggedIn                                     // ... but a user nonetheless\n    ),\n    function() use ($context) {\n        echo sprintf(\"Hello, %s\", $context['userName']);\n    }\n);\n\n$rules = new RuleSet([$hiJustin, $hiJon, $hiEveryoneElse]);\n\n// Let's add one more Rule, so non-authenticated users have a chance to log in\n$redirectForAuthentication = $rb-\u003ecreate($rb-\u003elogicalNot($userIsLoggedIn), function() {\n    header('Location: /login');\n    exit;\n});\n\n$rules-\u003eaddRule($redirectForAuthentication);\n\n// Now execute() all true Rules.\n//\n// Astute readers will note that the Rules we defined are mutually exclusive, so\n// at most one of them will evaluate to true and execute an action...\n$rules-\u003eexecuteRules($context);\n```\n\n\nDynamically populate your evaluation Context\n--------------------------------------------\n\nSeveral of our examples above use static values for the context Variables. While\nthat's good for examples, it's not as useful in the Real World. You'll probably\nwant to evaluate Rules based on all sorts of things...\n\nYou can think of the Context as a ViewModel for Rule evaluation. You provide the\nstatic values, or even code for lazily evaluating the Variables needed by your\nRules.\n\n```php\n$context = new Context;\n\n// Some static values...\n$context['reallyAnnoyingUsers'] = ['bobthecow', 'jwage'];\n\n// You'll remember this one from before\n$context['userName'] = fn() =\u003e $_SESSION['userName'] ?? null;\n\n// Let's pretend you have an EntityManager named `$em`...\n$context['user'] = function() use ($em, $context) {\n    if ($userName = $context['userName']) {\n        return $em-\u003egetRepository('Users')-\u003efindByUserName($userName);\n    }\n};\n\n$context['orderCount'] = function() use ($em, $context) {\n    if ($user = $context['user']) {\n        return $em-\u003egetRepository('Orders')-\u003efindByUser($user)-\u003ecount();\n    }\n\n    return 0;\n};\n```\n\nNow you have all the information you need to make Rules based on Order count or\nthe current User, or any number of other crazy things. I dunno, maybe this is\nfor a shipping price calculator?\n\n\u003e If the current User has placed 5 or more orders, but isn't \"really annoying\",\n\u003e give 'em free shipping.\n\n```php\n$rb-\u003ecreate(\n    $rb-\u003elogicalAnd(\n        $rb['orderCount']-\u003egreaterThanOrEqualTo(5),\n        $rb['reallyAnnoyingUsers']-\u003edoesNotContain($rb['userName'])\n    ),\n    function() use ($shipManager, $context) {\n        $shipManager-\u003egiveFreeShippingTo($context['user']);\n    }\n);\n```\n\n\nAccess variable properties\n--------------------------\n\nAs an added bonus, Ruler lets you access properties, methods and offsets on your\nContext Variable values. This can come in really handy.\n\nSay we wanted to log the current user's name if they are an administrator:\n\n```php\n// Reusing our $context from the last example...\n\n// We'll define a few context variables for determining what roles a user has,\n// and their full name:\n\n$context['userRoles'] = function() use ($em, $context) {\n    if ($user = $context['user']) {\n        return $user-\u003eroles();\n    } else {\n        // return a default \"anonymous\" role if there is no current user\n        return ['anonymous'];\n    }\n};\n\n$context['userFullName'] = function() use ($em, $context) {\n    if ($user = $context['user']) {\n        return $user-\u003efullName;\n    }\n};\n\n\n// Now we'll create a rule to write the log message\n\n$rb-\u003ecreate(\n    $rb-\u003elogicalAnd(\n        $userIsLoggedIn,\n        $rb['userRoles']-\u003econtains('admin')\n    ),\n    function() use ($context, $logger) {\n        $logger-\u003einfo(sprintf(\"Admin user %s did a thing!\", $context['userFullName']));\n    }\n);\n```\n\nThat was a bit of a mouthful. Instead of creating context Variables for\neverything we might need to access in a rule, we can use VariableProperties, and\ntheir convenient RuleBuilder interface:\n\n```php\n// We can skip over the Context Variable building above. We'll simply set our,\n// default roles on the VariableProperty itself, then go right to writing rules:\n\n$rb['user']['roles'] = ['anonymous'];\n\n$rb-\u003ecreate(\n    $rb-\u003elogicalAnd(\n        $userIsLoggedIn,\n        $rb['user']['roles']-\u003econtains('admin')\n    ),\n    function() use ($context, $logger) {\n        $logger-\u003einfo(sprintf(\"Admin user %s did a thing!\", $context['user']['fullName']);\n    }\n);\n```\n\nIf the parent Variable resolves to an object, and this VariableProperty name is\n\"bar\", it will do a prioritized lookup for:\n\n  1. A method named `bar`\n  2. A public property named `bar`\n  3. ArrayAccess + offsetExists named `bar`\n\nIf the Variable resolves to an array it will return:\n\n  1. Array index `bar`\n\nIf none of the above are true, it will return the default value for this\nVariableProperty.\n\n\nAdd your own Operators\n----------------------\n\nIf none of the default Ruler Operators fit your needs, you can write your own! Just define\nadditional operators like this:\n\n```php\n\nnamespace My\\Ruler\\Operators;\n\nuse Ruler\\Context;\nuse Ruler\\Operator\\VariableOperator;\nuse Ruler\\Proposition;\nuse Ruler\\Value;\n\nclass ALotGreaterThan extends VariableOperator implements Proposition\n{\n    public function evaluate(Context $context): bool\n    {\n        list($left, $right) = $this-\u003egetOperands();\n        $value = $right-\u003eprepareValue($context)-\u003egetValue() * 10;\n\n        return $left-\u003eprepareValue($context)-\u003egreaterThan(new Value($value));\n    }\n\n    protected function getOperandCardinality()\n    {\n        return static::BINARY;\n    }\n}\n```\n\nThen you can use them with RuleBuilder like this:\n\n```php\n$rb-\u003eregisterOperatorNamespace('My\\Ruler\\Operators');\n$rb-\u003ecreate(\n    $rb['a']-\u003eaLotGreaterThan(10);\n);\n```\n\n\nBut that's not all...\n---------------------\n\nCheck out [the test suite](https://github.com/bobthecow/Ruler/blob/master/tests/Ruler/Test/Functional/RulerTest.php)\nfor more examples (and some hot CS 320 combinatorial logic action).\n\n\nRuler is plumbing. Bring your own porcelain.\n============================================\n\nRuler doesn't bother itself with where Rules come from. Maybe you have a RuleManager\nwrapped around an ORM or ODM. Perhaps you write a simple DSL and parse static files.\n\nWhatever your flavor, Ruler will handle the logic.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobthecow%2FRuler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbobthecow%2FRuler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobthecow%2FRuler/lists"}