Rule::clearResult() - Code Metrics - rolfvreijdenberger/izzum-statemachine - Measure and Improve Code Quality continuously with Scrutinizer

Rule::clearResult() A
last analyzed 2017-08-22 19:17 UTC

↳ Parent: Rule

Complexity

Conditions	1
Paths	1

Size

Total Lines	4
Code Lines	2

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	3
CRAP Score	1

Importance

Changes

Metric	Value
dl	0
loc	4
ccs	3
cts	3
cp	1
rs	10
c	0
b	0
f	0
cc	1
eloc	2
nc	1
nop	0
crap	1

<?php
namespace izzum\rules;
use izzum\rules\Exception;

/**
 * Rules are used to encapsulate business rules/logic of the type where you ask
 * a
 * question: 'does this piece of code conform to a specific business rule?'
 *
 * Rules should never have side effects and should only return true or false.
 *
 * This Rule serves as a base class for all your business logic, encapsulating
 * and centralizing the logic in a class and making it reusable through it's
 * interface.
 *
 * This is a way of seperating mechanism and policy of code.
 * In other words: how it is done versus what should be done. The mechanism is a
 * rule
 * library, the policy is what is defined in the rule.
 * https://en.wikipedia.org/wiki/Separation_of_mechanism_and_policy
 *
 * The rules package aims to prevent code like this:
 * if ($name == 'blabla' && $password == 'lala') {
 * //do something here. the statement above might be duplicated in a lot of
 * places
 * }
 * and substitute it by this:
 * $rule = new AccesRule($name, $password);
 * if($rule->applies()) {
 * //do something
 * }
 *
 * or:
 * $rule = new IsOrderTaggedForDelivery($order);
 * $rule->applies();
 *
 * usage:
 * Clients should subclass this Rule and implement the
 * protected '_applies' method and let that return a boolean value.
 *
 * A concrete Rule (a subclass) can (and should be) injected with contextual
 * data via
 * dependency injection in the constructor
 *
 *
 * @author Rolf Vreijdenberger
 * @author Richard Ruiter
 * @link https://en.wikipedia.org/wiki/Separation_of_mechanism_and_policy
 */
abstract class Rule implements IRule {
    /**
     * contains results that a concrete Rule can set.
     * This allows clients of the Rule to check if certain conditions in
     * a rule have been met. The subclassed rule should add a result itself.
     * This will happen in case of multiple conditions being checked for a rule
     * to evaluate to true. If one of the conditions is not met, you can set a
     * result there.
     * 
     * @var RuleResult[]
     */
    private $result = array();
    
    /**
     * should we cache the result or not?
     * TRICKY: this might be very dangerous for non-deterministic rules but a
     * great speed optimizer for rules that are evaluated multiple times and are
     * deterministic
     * 
     * @var boolean
     */
    private $use_caching = false;
    
    /**
     * if the result is cached, it will be put in this variable
     * after the applies method has run
     * 
     * @var boolean
     */
    private $cache;

    /**
     * A concrete rule should at least implement the _applies method and return
     * a
     * boolean.
     * When the rule logic cannot determine if it applies then an exception
     * should
     * be thrown instead of a boolean value
     *
     * @return boolean
     * @throws \Exception
     */
    abstract protected function _applies();

    /**
     * The applies method is the only point where the rule can be validated.
     *
     * Internally each rule implements the _applies() method to do the actual
     * validation.
     *
     * There are only two types of outcome for each rule.
     * Either the rule applies (true) or doesn't (false).
     * Any other outcome should always be thrown as an exception so no false
     * assumptions can be made by the caller. For example when a rule returns a
     * NULL value the caller may asume that false is meant. The rule cannot
     * trust that the caller checks the boolean type so we will.
     *
     * @return boolean
     * @throws Exception https://en.wikipedia.org/wiki/Template_method_pattern
     */
    final public function applies()
    {
        try {
            if ($this->shouldReturnCache()) {
                return $this->getCache();
            }
            $this->clearResult();
            $this->clearCache();
            $result = $this->_applies();
            if (is_bool($result)) {
                $this->setCache($result);
                return $result;
            } else {
                throw new Exception('A rule must return a boolean.', Exception::CODE_NONBOOLEAN);
            }
        } catch(Exception $e) {
            $this->handleException($e);
            throw $e;
        } catch(\Exception $e) {
            $e = new Exception($e->getMessage(), $e->getCode(), $e);
            $this->handleException($e);
            throw $e;
        }
    }

    /**
     * hook method for logging etc.
     * 
     * @param Exception $e            
     */
    protected function handleException($e)

    {
        // implement in subclass if needed
    }

    /**
     * Chain a 'OR' rule.
     * This means one of the rules should apply.
     *
     * @param Rule $other            
     * @return Rule
     */
    final public function orRule(Rule $other)
    {
        return new OrRule($this, $other);
    }

    /**
     * Chain a 'XOR' rule.
     * This means one of the rules should apply but not both.
     *
     * @param Rule $other            
     * @return Rule
     */
    final public function xorRule(Rule $other)
    {
        return new XorRule($this, $other);
    }

    /**
     * Chain a 'AND' rule.
     * This means both rules should apply.
     *
     * @param Rule $other            
     * @return Rule
     */
    final public function andRule(Rule $other)
    {
        return new AndRule($this, $other);
    }

    /**
     * Inverse current rule
     *
     * @return Rule
     */
    final public function not()
    {
        return new NotRule($this);
    }

    /**
     *
     * @return string
     */
    public function toString()
    {
        // includes the namespace
        return get_class($this);
    }

    /**
     * Gets an array of RuleResult to check if a rule has set a certain result
     * for the client of the rule.
     * This will mostly be useful to check what actually happened when a rule
     * has failed and if the _applies() method actually calls 'addResult()' to
     * state what has happened in a rule.
     *
     * @return RuleResult[]
     */
    public function getResults()
    {
        return $this->result;
    }

    /**
     * Add a result to this rule.
     *
     *
     * this might be useful if a client wants to check if a rule
     * has executed certain steps during the logic of rule execution.
     * 
     * @param string $result            
     */
    final protected function addResult($result)
    {
        $this->result [] = new RuleResult($this, $result);
    }

    /**
     * Check if this rule contains a certain expected result.
     * This is only matched on the string, not on the class that generated
     * the result. you can check this against constants in a class eg:
     * Rule::RESULT_<*>.
     * In case you want to also know the class or classname, use getResults()
     * 
     * @see Rule::getResults()
     * @param string $expected            
     */
    final public function containsResult($expected)
    {
        $output = false;
        $results = $this->getResults();
        foreach ($results as $result) {
            if ($result->getResult() === $expected) {
                $output = true;
            }
        }
        return $output;
    }

    /**
     * Clear the results
     */
    private function clearResult()
    {
        $this->result = array();
    }

    private function clearCache()
    {
        $this->cache = null;
    }

    private function setCache($result)
    {
        if ($this->getCacheEnabled()) {
            $this->cache = $result;
        }
    }

    /**
     * Has any result?
     *
     * @return boolean
     */
    final public function hasResult()
    {
        return count($this->getResults()) !== 0;
    }

    /**
     * should we cache the result if the rule is applied more than once?
     * 
     * @param boolean $cached            
     */
    final public function setCacheEnabled($cached = true)
    {
        $cached = (bool) $cached;
        $this->use_caching = $cached;
        $this->clearCache();
    }

    /**
     * return the cached value
     * 
     * @return boolean
     */
    final protected function getCache()
    {
        return $this->cache;
    }

    /**
     * should we return a cached value?
     * 
     * @return boolean
     */
    private function shouldReturnCache()
    {
        if ($this->getCacheEnabled()) {
            if ($this->cache !== null) {
                return true;
            }
        }
        return false;
    }

    /**
     *
     * @return boolean
     */
    final public function getCacheEnabled()
    {
        return $this->use_caching;
    }

    public function __toString()
    {
        return $this->toString();
    }
}


1		<?php
2		namespace izzum\rules;
3		use izzum\rules\Exception;
4
5		/**
6		* Rules are used to encapsulate business rules/logic of the type where you ask
7		* a
8		* question: 'does this piece of code conform to a specific business rule?'
9		*
10		* Rules should never have side effects and should only return true or false.
11		*
12		* This Rule serves as a base class for all your business logic, encapsulating
13		* and centralizing the logic in a class and making it reusable through it's
14		* interface.
15		*
16		* This is a way of seperating mechanism and policy of code.
17		* In other words: how it is done versus what should be done. The mechanism is a
18		* rule
19		* library, the policy is what is defined in the rule.
20		* https://en.wikipedia.org/wiki/Separation_of_mechanism_and_policy
21		*
22		* The rules package aims to prevent code like this:
23		* if ($name == 'blabla' && $password == 'lala') {
24		* //do something here. the statement above might be duplicated in a lot of
25		* places
26		* }
27		* and substitute it by this:
28		* $rule = new AccesRule($name, $password);
29		* if($rule->applies()) {
30		* //do something
31		* }
32		*
33		* or:
34		* $rule = new IsOrderTaggedForDelivery($order);
35		* $rule->applies();
36		*
37		* usage:
38		* Clients should subclass this Rule and implement the
39		* protected '_applies' method and let that return a boolean value.
40		*
41		* A concrete Rule (a subclass) can (and should be) injected with contextual
42		* data via
43		* dependency injection in the constructor
44		*
45		*
46		* @author Rolf Vreijdenberger
47		* @author Richard Ruiter
48		* @link https://en.wikipedia.org/wiki/Separation_of_mechanism_and_policy
49		*/
50		abstract class Rule implements IRule {
51		/**
52		* contains results that a concrete Rule can set.
53		* This allows clients of the Rule to check if certain conditions in
54		* a rule have been met. The subclassed rule should add a result itself.
55		* This will happen in case of multiple conditions being checked for a rule
56		* to evaluate to true. If one of the conditions is not met, you can set a
57		* result there.
58		*
59		* @var RuleResult[]
60		*/
61		private $result = array();
62
63		/**
64		* should we cache the result or not?
65		* TRICKY: this might be very dangerous for non-deterministic rules but a
66		* great speed optimizer for rules that are evaluated multiple times and are
67		* deterministic
68		*
69		* @var boolean
70		*/
71		private $use_caching = false;
72
73		/**
74		* if the result is cached, it will be put in this variable
75		* after the applies method has run
76		*
77		* @var boolean
78		*/
79		private $cache;
80
81		/**
82		* A concrete rule should at least implement the _applies method and return
83		* a
84		* boolean.
85		* When the rule logic cannot determine if it applies then an exception
86		* should
87		* be thrown instead of a boolean value
88		*
89		* @return boolean
90		* @throws \Exception
91		*/
92		abstract protected function _applies();
93
94		/**
95		* The applies method is the only point where the rule can be validated.
96		*
97		* Internally each rule implements the _applies() method to do the actual
98		* validation.
99		*
100		* There are only two types of outcome for each rule.
101		* Either the rule applies (true) or doesn't (false).
102		* Any other outcome should always be thrown as an exception so no false
103		* assumptions can be made by the caller. For example when a rule returns a
104		* NULL value the caller may asume that false is meant. The rule cannot
105		* trust that the caller checks the boolean type so we will.
106		*
107		* @return boolean
108		* @throws Exception https://en.wikipedia.org/wiki/Template_method_pattern
109		*/
110	52	final public function applies()
111		{
112		try {
113	52	if ($this->shouldReturnCache()) {
114	1	return $this->getCache();
115		}
116	52	$this->clearResult();
117	52	$this->clearCache();
118	52	$result = $this->_applies();
119	50	if (is_bool($result)) {
120	45	$this->setCache($result);
121	45	return $result;
122		} else {
123	5	throw new Exception('A rule must return a boolean.', Exception::CODE_NONBOOLEAN);
124		}
125	12	} catch(Exception $e) {
126	12	$this->handleException($e);
127	12	throw $e;
128	1	} catch(\Exception $e) {
129	1	$e = new Exception($e->getMessage(), $e->getCode(), $e);
130	1	$this->handleException($e);
131	1	throw $e;
132		}
133		}
134
135		/**
136		* hook method for logging etc.
137		*
138		* @param Exception $e
139		*/
140	12	protected function handleException($e)
		0 ignored issues – show Unused Code introduced 2017-08-22 19:17 UTC by Report Bug Copy Issue Report The parameter `$e` is not used and could be removed. This check looks from parameters that have been defined for a function or method, but which are not used in the method body. Loading history...
141		{
142		// implement in subclass if needed
143	12	}
144
145		/**
146		* Chain a 'OR' rule.
147		* This means one of the rules should apply.
148		*
149		* @param Rule $other
150		* @return Rule
151		*/
152	3	final public function orRule(Rule $other)
153		{
154	3	return new OrRule($this, $other);
155		}
156
157		/**
158		* Chain a 'XOR' rule.
159		* This means one of the rules should apply but not both.
160		*
161		* @param Rule $other
162		* @return Rule
163		*/
164	3	final public function xorRule(Rule $other)
165		{
166	3	return new XorRule($this, $other);
167		}
168
169		/**
170		* Chain a 'AND' rule.
171		* This means both rules should apply.
172		*
173		* @param Rule $other
174		* @return Rule
175		*/
176	3	final public function andRule(Rule $other)
177		{
178	3	return new AndRule($this, $other);
179		}
180
181		/**
182		* Inverse current rule
183		*
184		* @return Rule
185		*/
186	2	final public function not()
187		{
188	2	return new NotRule($this);
189		}
190
191		/**
192		*
193		* @return string
194		*/
195	5	public function toString()
196		{
197		// includes the namespace
198	5	return get_class($this);
199		}
200
201		/**
202		* Gets an array of RuleResult to check if a rule has set a certain result
203		* for the client of the rule.
204		* This will mostly be useful to check what actually happened when a rule
205		* has failed and if the _applies() method actually calls 'addResult()' to
206		* state what has happened in a rule.
207		*
208		* @return RuleResult[]
209		*/
210	5	public function getResults()
211		{
212	5	return $this->result;
213		}
214
215		/**
216		* Add a result to this rule.
217		*
218		*
219		* this might be useful if a client wants to check if a rule
220		* has executed certain steps during the logic of rule execution.
221		*
222		* @param string $result
223		*/
224	1	final protected function addResult($result)
225		{
226	1	$this->result [] = new RuleResult($this, $result);
227	1	}
228
229		/**
230		* Check if this rule contains a certain expected result.
231		* This is only matched on the string, not on the class that generated
232		* the result. you can check this against constants in a class eg:
233		* Rule::RESULT_<*>.
234		* In case you want to also know the class or classname, use getResults()
235		*
236		* @see Rule::getResults()
237		* @param string $expected
238		*/
239	1	final public function containsResult($expected)
240		{
241	1	$output = false;
242	1	$results = $this->getResults();
243	1	foreach ($results as $result) {
244	1	if ($result->getResult() === $expected) {
245	1	$output = true;
246	1	}
247	1	}
248	1	return $output;
249		}
250
251		/**
252		* Clear the results
253		*/
254	52	private function clearResult()
255		{
256	52	$this->result = array();
257	52	}
258
259	52	private function clearCache()
260		{
261	52	$this->cache = null;
262	52	}
263
264	45	private function setCache($result)
265		{
266	45	if ($this->getCacheEnabled()) {
267	1	$this->cache = $result;
268	1	}
269	45	}
270
271		/**
272		* Has any result?
273		*
274		* @return boolean
275		*/
276	1	final public function hasResult()
277		{
278	1	return count($this->getResults()) !== 0;
279		}
280
281		/**
282		* should we cache the result if the rule is applied more than once?
283		*
284		* @param boolean $cached
285		*/
286	1	final public function setCacheEnabled($cached = true)
287		{
288	1	$cached = (bool) $cached;
289	1	$this->use_caching = $cached;
290	1	$this->clearCache();
291	1	}
292
293		/**
294		* return the cached value
295		*
296		* @return boolean
297		*/
298	1	final protected function getCache()
299		{
300	1	return $this->cache;
301		}
302
303		/**
304		* should we return a cached value?
305		*
306		* @return boolean
307		*/
308	52	private function shouldReturnCache()
309		{
310	52	if ($this->getCacheEnabled()) {
311	1	if ($this->cache !== null) {
312	1	return true;
313		}
314	1	}
315	52	return false;
316		}
317
318		/**
319		*
320		* @return boolean
321		*/
322	52	final public function getCacheEnabled()
323		{
324	52	return $this->use_caching;
325		}
326
327	1	public function __toString()
328		{
329	1	return $this->toString();
330		}
331		}
332

rolfvreijdenberger / izzum-statemachine

GitHub Access Token became invalid

Rule::clearResult() A last analyzed 2017-08-22 19:17 UTC

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like

Rule::clearResult() A
last analyzed 2017-08-22 19:17 UTC