tklein / php-combine-conditions
Generic representation of conditional structure/tree library for PHP.
Fund package maintenance!
paypal.me/thomaskl1
Requires
- php: ^8.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.4
- pdepend/pdepend: ^2.1
- phpmd/phpmd: ^2.11
- phpstan/phpstan: ^1.3
- phpunit/phpunit: ^9.5
- sebastian/phpcpd: ^6.0
- squizlabs/php_codesniffer: ^3.6
This package is auto-updated.
Last update: 2024-12-06 18:38:38 UTC
README
Generic representation of conditional structure/tree library for PHP.
Installation
Composer (recommended)
This package is available through Composer/Packagist:
composer require tklein/php-combine-conditions
Getting Started
The combine conditions library for PHP is a tool which helps you to build dynamically structured (as tree or graph) conditions.
These conditions are able to be combined and customized operators can be provided.
This library can be used in many context, to execute advanced combination of conditions, to generate some complex SQL
conditions, or to be exported to multiple formats as JSON, XML, FULLTEXT...
An other case to use this library is to execute and process frontend conditional tree (Eg: a user build his conditional
tree and would like to process the result).
The library has been written in order to allows you to implement it to the right way you want. So, if you implement the interfaces from the public API, you can build your own combine conditions structure and continue to execute it via the public API services.
The library is written to follow the PSR12 coding standards.
Main Library Entrance
For a simply use, you'll only need to use the following class: \LogicTree\LogicTreeFacade
.
This class allows you to use the mainly features of the library, as to build a combined conditions, to execute some, and
exports them.
OperatorPool
What's an OperatorPool
? It's a class which regroup the whole operator instances used in the library.
You can register or retrieve OperatorInterface
from this class. The goal is to use them in your combination of conditions.
The operators are divided in two large groups:
- The comparator operator.
- The logical operator.
Comparator Operator
The comparator operator is used to determine the result of a boolean expression.
Eg:
Does 'A'
and 'B'
are the same thing? I can test with an equality operator: 'A' == 'B'
).
The default comparator operators are available in: src/Operator/Comparator
.
It's used in the ConditionInterface
definition, known as the Condition
object.
Logical Operator
The logical operator is used to commute many boolean expression (at least two).
Eg:
'A' != 'B'
result should be the same as 'C' != 'D'
.
I can check with the following expression 'A' != 'B' AND 'C' != 'D'
.
The default logical operators are available in: src/Operator/Logical
.
It's used in the CombineInterface
definition, known as the Combine
object.
Override/Add new Operators
The library allows you to override the default operators and/or to provide new ones:
- You should instantiate the
OperatorPool
class. - Create your operators. They must implement the interface
OperatorInterface
. - Add your operators (two available types:
logical
andcomparator
) to theOperatorPool
object. - Finally, pass the
OperatorPool
object in the construct of theConditionManager
class.
Eg: In the following example, we override the default comparators with ours and add a new one.
$operatorPool = new \LogicTree\Operator\OperatorPool(); $operatorPool->addOperator( \LogicTree\Operator\OperatorType::Logical, \LogicTree\Operator\Logical\LogicalOperatorConverter::CODE, new \My\Class\AndOperator() ); $operatorPool->addOperator( \LogicTree\Operator\OperatorType::Comparator, \LogicTree\Operator\Comparator\EqOperator::CODE, new \My\Class\EqOperator() ); $operatorPool->addOperator( \LogicTree\Operator\OperatorType::Comparator, 'my_custom_operator', new \My\Class\MyCustomOperator() ); $conditionManager = new \LogicTree\Service\ConditionManager($operatorPool);
Now we are able to use these operators in our code and are available everywhere in the library.
Condition and Combine
These class always implement the NodeInterface
. It represent the base model of the library.
Because of the composition pattern, you may want to know if the current object is the root or a node, you
should use the following methods:
hasParent()
: check if the current object has parent or not.getParent()
: retrieve the current object's parent.ConditionInterface
: is an instance of, represent the last/final node.CombineInterface
: is an instance of, represent the container node.
Condition
ConditionInterface
: it represents an expression with a comparator operator.
The interface is: \LogicTree\Model\ConditionInterface
.
The concrete default class is: \LogicTree\Model\Condition
.
It requires a mixed value to compared by an operator to a value from the data source.
The operator is a string
which is the code of the wanted operator.
The first value is a string
which is the identifier of the value from the DataSource
object.
The value to compare must be a mixed
value.
Combine
Combine
: it represents an expression with a logical operator.
The interface is: \LogicTree\Model\CombineInterface
.
The concrete default class is: \LogicTree\Model\Combine
.
It requires at least two conditions and/or combines to commute with a logical operator.
The operator is a string
which is the code of the wanted operator.
The conditions/combine must be an instance of ConditionInterface
.
You can add a NodeInterface
to the CombineInterface
with the following methods:
addChild(NodeInterface $node)
: add a new node child to the parent node object.setChildren(array $nodes)
: replace the children by the new ones.
If you want to invert the result of the combination of conditions, you can specify to the CombineInterface
object that the result should actually be inverted:
setIsInvert(bool $isInvert)
.
Execute the Combine Conditions
In order to execute the combined conditions, you must use the \LogicTree\Service\ConditionManager
class.
This service allows to perform many actions on your NodeInterface
object.
Actually only the execute
method is available from the public API.
Anyway, the execute
method allows you to determine the final result of your combination of conditions.
Export the Combine Conditions to Format
No documentation available yet!
Examples
Examples of code usage cases are available in this file.
Running the tests
The tests are placed in the tests
directory, at the root of the library.
No tests available yet!
Contributing
Any help is welcome, feel free to raise issues or to open pull requests. Further details in the CONTRIBUTING.md.
TODO List
Implement the following comparator operators:
- array("from" => $fromValue, "to" => $toValue)
- array("like" => $likeValue)
- array("moreq" => $moreOrEqualValue)
- array("finset" => $valueInSet)
- array("seq" => $stringValue)
- array("sneq" => $stringValue)
ToString methods, in order to render the combine conditions in full text / different formats.
Have to: AdapterPool (toFormat) - ConverterPool (getSymbol, getExpression, getFullExpression).
Possibility to add custom type node and process them in the services.
Study Namespace and Lib Name: trends
Todo Builders (setter... getter... then reset)
-> possibility of immutable implementation (do not break it!)
Add tests and examples: from scratch, with and without new operators, and execution (with expected results).
Authors
- Thomas Klein - Initial work - It's me!
See also the list of contributors who participated in this project.
License
This project is licensed under the MIT License - see the LICENSE file for details.