Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
95.83% covered (success)
95.83%
23 / 24
85.71% covered (warning)
85.71%
6 / 7
 CRAP
0.00% covered (danger)
0.00%
0 / 1
TestCategoryRulesGenerator
95.83% covered (success)
95.83%
23 / 24
85.71% covered (warning)
85.71%
6 / 7
 12
0.00% covered (danger)
0.00%
0 / 1
 setScoreVariableIdentifier
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getScoreVariableIdentifier
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 setWeightIdentifier
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getWeightIdentifier
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 setCategoryExclusions
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getCategoryExclusions
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 apply
100.00% covered (success)
100.00%
18 / 18
100.00% covered (success)
100.00%
1 / 1
 6
1<?php
2
3/**
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License
6 * as published by the Free Software Foundation; under version 2
7 * of the License (non-upgradable).
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
17 *
18 * Copyright (c) 2016 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
19 *
20 */
21
22namespace oat\taoQtiTest\models;
23
24use qtism\data\AssessmentTest;
25use oat\taoQtiTest\models\TestCategoryRulesUtils;
26
27/**
28 * The TestCategoryRulesGenerator class makes possible to automatically apply various outcome processing rules on
29 * QTI-SDK AssessmentTest objects.
30 *
31 * This classes provide mechanisms enabling the client code to apply automatically some outcome processing rules
32 * on existing QTI Assessment Tests, provided as QTI-SDK AssessmentTest objects. It can be configured in multiple ways,
33 * in order to apply on tests:
34 *
35 * * Outcome Declarations aiming at counting the number of items related to a given category
36 *   (TestCategoryRulesGenerator::COUNT flag).
37 * * Outcome Declarations and their related Outcome Processing Rules to determine the number of correctly responded
38 *   items that belong to a given category (TestCategoryRulesGenerator::CORRECT flag).
39 * * Outcome Declarations and their related Outcome Processing Rules to determine the total score of items that belong
40 *   to a given category. (TestCategoryRulesGenerator::SCORE flag).
41 *
42 * The TestCategoryRulesGenerator::COUNT, TestCategoryRulesGenerator::CORRECT and TestCategoryRulesGenerator::SCORE
43 * flags can be provided to the TestCategoryRulesGenerator::apply() method, in order to select which kind of rules to
44 * be applied on processed AssessmentTest objects.
45 *
46 */
47class TestCategoryRulesGenerator
48{
49    public const COUNT = 1;
50    public const CORRECT = 2;
51    public const SCORE = 4;
52
53    private $scoreVariableIdentifier = 'SCORE';
54    private $weightIdentifier = '';
55    private $categoryExclusions = [];
56
57    /**
58     * Set the identifier of the item variables involved in total scoring.
59     *
60     * This method allows you to set the $identifier of the item variables involved
61     * in total scoring Outcome Processing Rules (by default "SCORE").
62     *
63     * @param string $identifier A QTI identifier.
64     */
65    public function setScoreVariableIdentifier($identifier)
66    {
67        $this->scoreVariableIdentifier = $identifier;
68    }
69
70    /**
71     * Get the identifier of the item variables involved in total scoring.
72     *
73     * This method allows you to get the $identifier of the item variables involved
74     * in total scoring Outcome Processing Rules (by default "SCORE").
75     *
76     * @return string A QTI identifier.
77     */
78    public function getScoreVariableIdentifier()
79    {
80        return $this->scoreVariableIdentifier;
81    }
82
83    /**
84     * Set the identifier of the item weights involved in total scoring.
85     *
86     * This method allows you to set the $identifier of the item weights
87     * to be involved in generated total scoring Outcome Processing Rules.
88     *
89     * By default, the $identifier is an empty string, meaning that no
90     * specific weights must be used when generating the Outcome Processing
91     * Rules.
92     *
93     * @param string $identifier (optional) A QTI identifier.
94     */
95    public function setWeightIdentifier($identifier = '')
96    {
97        $this->weightIdentifier = $identifier;
98    }
99
100    /**
101     * Get the identifier of the item weights involved in total scoring.
102     *
103     * This method allows you to get the $identifier of the item weights
104     * to be involved in generated total scoring Outcome Processing Rules.
105     *
106     * By default, the $identifier is an empty string, meaning that no
107     * specific weights must be used when generating the Outcome Processing
108     * Rules.
109     *
110     * @return string (optional) A QTI identifier.
111     */
112    public function getWeightIdentifier()
113    {
114        return $this->weightIdentifier;
115    }
116
117    /**
118     * Set the category patterns to be excluded.
119     *
120     * This method provides a way to define a set of Pearl Compatible Regular Expressions
121     * that will determine which categories will be excluded from processing when calling
122     * the TestCategoryRulesGenerator::apply() method.
123     *
124     * @param array $exclusions (optional) An array of string representing PCREs.
125     */
126    public function setCategoryExclusions(array $exclusions = [])
127    {
128        $this->categoryExclusions = $exclusions;
129    }
130
131    /**
132     * Set the category patterns to be excluded.
133     *
134     * Get the PCRE patterns defining what are the category identifiers to be excluded
135     * from the process.
136     *
137     * @retun array An array of string representing PCREs.
138     */
139    public function getCategoryExclusions()
140    {
141        return $this->categoryExclusions;
142    }
143
144    /**
145     * Apply Outcome Declaraton and Outcome Processing Rules.
146     *
147     * This method will trigger the process of applying Outcome Declarations and Outcome Processing Rules on a given
148     * $test, dependings on the assessmentItemRef categories found into it.
149     *
150     * This method can be configure with the following flags:
151     *
152     * TestCategoryRulesGenerator::COUNT:
153     *
154     * The COUNT flag will trigger the process of creating Outcome Declarations where default values represent the
155     * number of items involved in categories found in the $test. For instance, if $test contains two assessmentItemRef
156     * elements with a 'math' category are found in the $test, an Outcome Declaration 'MATH_CATEGORY_NUMBER_ITEMS' with
157     * single cardinality, integer base type, and a default value of 2 will be injected in the $test definition.
158     *
159     * TestCategoryRulesGenerator::CORRECT:
160     *
161     * The CORRECT flag will trigger the process of creating Outcome Declarations and their related Outcome Processing
162     * Rules that will take care of counting the number of items that were correctly responded, by category. As an
163     * example, if two assessmentItemRef elements with a 'math' category are found in the $test, an Outcome Declaration
164     * 'MATH_CATEGORY_NUMBER_CORRECT' with single cardinality and integer base type will be injected in the $test
165     * definition, in addition with the relevant Outcome Processing Rule in charge of computing the appropriate Outcome
166     * value at test runtime.
167     *
168     * TestCategoryRulesGenerator::SCORE:
169     *
170     * The SCORE flag will trigger the process of creating Outcome Declarations and their related Outcome Processing
171     * Rules that will take care of counting the total score of items, by category. As an example, if two
172     * assessmentItemRef elements with a 'math' category are found in the $test, an Outcome Declaration
173     * 'MATH_CATEGORY_TOTAL_SCORE' with single cardinality and float base type will be injected in the $test definition,
174     * in addition with the relevant Outcome Processing Rule in charge of computing the appropriate Outcome value at
175     * test runtime. When this flag is enabled, the generation process for the Outcome Processing Rules will take into
176     * account the values provided to the TestCategoryRulesGenerator::setScoreVariableIdentifier() and
177     * TestCategoryRulesGenerator::setWeightIdentifier() setters to respectively identify which item variable
178     * (by default 'SCORE'), and which item weights should be used to compute total scores.
179     *
180     * If no $flags are given, it is considered that all the flags above are enabled.
181     *
182     * @param qtism\data\AssessmentTest $test A QTI-SDK AssessmentTest object.
183     * @param integer $flags (optional) TestCategoryRulesGenerator::COUNT | TestCategoryRulesGenerator::CORRECT
184     *                       | TestCategoryRulesGenerator::SCORE
185     */
186    public function apply(AssessmentTest $test, $flags = 0)
187    {
188        if ($flags == 0) {
189            $flags = (self::COUNT | self::CORRECT | self::SCORE);
190        }
191
192        $categories = TestCategoryRulesUtils::extractCategories($test, $this->getCategoryExclusions());
193        foreach ($categories as $category) {
194            if ($flags & self::COUNT) {
195                TestCategoryRulesUtils::appendNumberOfItemsVariable($test, $category);
196            }
197
198            if ($flags & self::CORRECT) {
199                $numberCorrectVarName = TestCategoryRulesUtils::appendNumberCorrectVariable($test, $category);
200                TestCategoryRulesUtils::appendNumberCorrectOutcomeProcessing($test, $category, $numberCorrectVarName);
201            }
202
203            if ($flags & self::SCORE) {
204                $totalScoreVarName = TestCategoryRulesUtils::appendTotalScoreVariable($test, $category);
205                TestCategoryRulesUtils::appendTotalScoreOutcomeProcessing(
206                    $test,
207                    $category,
208                    $totalScoreVarName,
209                    $this->getScoreVariableIdentifier(),
210                    $this->getWeightIdentifier()
211                );
212            }
213        }
214    }
215}