Download the PHP package zitec/rule-engine-bundle without Composer

Introduction

Rule engine is a symfony bundle that allows you to build complex condition sets using parameters and evaluators that you define to match your objects and needs. It offers a friendly front end interface and simple integration with Doctrine entities and their corresponding Sonata admins. A demo site?

Installation

You can install it through composer.

Usage

How to use

Context object

Write a class implementing RuleContextInterface, and add some methods that will return the parameters you wish to include in your rules. To make things super-easy, a basic context class already exists: ContextBase. It already offers getters for 3 parameters: current_date, current_day, and current_time. Your custom context can extend this.

Conditions

For each parameter (method) in the context object, create a Condition object. The condition services for the three date.time parameters supported by the ContextBase class are already defined in the rule engine bundle. We'll add another one in our new bundle for the added parameter (my_parameter). We can write a condition from scratch, but it's much easier to extend one of the two Abstract condition classes that offer support for basic operators for single-value and array parameters. If "my_parameter" is in fact an array, we can do somthing like this:

Rule manager service

Now that we have our context object and the matching definitions, let's create a service using RuleConditionsManager. We need to give it your context object as argument and the conditions as ‘addSupportedCondition’ calls. Since we extended the ContextBase class, we can use the datetime conditions defined by rule engine too. Below is an example of services defined using the classes above.

Form building

Now we need to use the context and conditions to render the front end conditions builder. This can be done by adding a RuleEngineType form type to a form and setting the rule manager service on the 'rule_manager' key in the field options.

But in most probability, the actions you want to associate with the rules need some data of their own. For instance, we could decide to send emails to various addresses based on the parameters in our object. In that case, we can define a doctrine entity with an email field, to define the addresses, and set it as a rule entity. Doing that is very simple: just add "implements RuleInterface" to your class, and add a "use RuleTrait" statement to actually implement the interface.

Update the doctrine schema and notice the brand new relation with the Rule entity that will hold the expressions for your EmailAddress entity.

Your rule-integrated entity will need to be associated with a context and conditions set, i.e. a rule conditions manager. To do that, you have to add a tag to the conditions manager service declaration. The service above becomes:

Onwards to the admin section.

I will assume that you are using SonataAdmin to manage your doctrine entity. If so, this is what you need to do:

In the Admin class, add a "use RuleAdminTrait" statement, and use the relevant methods:

Congratulations! You can now see it in action and set addresses for various cases, using complex rules!

Rule evaluation

Somewhere in your business flow you will need to extract the email address(es) that match your object. The code for that will use the RuleEvaluator service and could look something like this:

That's it! Done!

Additional documentation:

Operator definition

An operator is an array with these keys:

• name (mandatory): the machine name, used to identify the selected operator in a condition
• label (mandatory): the text that the user sees in the admin pages
• fieldType (mandatory): see possible values below
• fieldOptions (optional): see details below
• value_transform (optional): a callback to apply to the value received from the rule builder before generating the expression
• value_view_transform (optional): a callback to apply to the value received from the rule builder before generating the rule admin view

Field types and options

• text: basic text input, useful for single-value parameters with free-form values.
• datetime: datepicker input; add your datepicker options to the fieldOptions array on the datetimepicker key.
• interval: basic interval definition, with a text input for the "from" and "to" values.
• datetime_interval: combine the two types above and voila: interval with datetime picker.
• select: a select2 augmented select; you can see an implementation in the MyParameter condition declaration.
• autocomplete: a select2 input with autocomplete using RuleEngine's autocomplete functionality.

Autocomplete support:

In order to use an autocomplete field, you need to define a data source by implementing the Zitec\RuleEngineBundle\Autocomplete\AutocompleteInterface. If you want to have an autocomplete of doctrine entities, you can extend the AbstractAutocompleteEntity class:

and declare the service using a "rule_engine.autocomplete.data_source" tag:

The value for the key is what you have to use in the fieldOptions for the autocomplete type.

Don't forget to add the routing info in the routing.yml file of your app: