Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00% covered (success)
100.00%
38 / 38
100.00% covered (success)
100.00%
16 / 16
 CRAP
100.00% covered (success)
100.00%
1 / 1
CirrusDebugOptions
100.00% covered (success)
100.00%
38 / 38
100.00% covered (success)
100.00%
16 / 16
 27
100.00% covered (success)
100.00%
1 / 1
 __construct
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 fromRequest
100.00% covered (success)
100.00%
9 / 9
100.00% covered (success)
100.00%
1 / 1
 3
 defaultOptions
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 forDumpingQueriesInUnitTests
100.00% covered (success)
100.00%
4 / 4
100.00% covered (success)
100.00%
1 / 1
 1
 forRelevanceTesting
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 1
 debugOption
100.00% covered (success)
100.00%
6 / 6
100.00% covered (success)
100.00%
1 / 1
 3
 getCirrusCompletionVariant
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isCirrusDumpQuery
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isCirrusDumpQueryAST
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isCirrusDumpResult
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getCirrusExplainFormat
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 4
 getCirrusMLRModel
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isDumpAndDie
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isReturnRaw
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 3
 applyDebugOptions
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 2
 mustNeverBeCached
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 2
1<?php
2
3namespace CirrusSearch;
4
5use Elastica\Query;
6use MediaWiki\Request\WebRequest;
7
8/**
9 * Cirrus debug options generally set via *unofficial* URI param (&cirrusXYZ=ZYX)
10 */
11class CirrusDebugOptions {
12
13    /**
14     * @var string[]|null
15     */
16    private $cirrusCompletionVariant;
17
18    /**
19     * @var bool
20     */
21    private $cirrusDumpQuery = false;
22
23    /**
24     * @var bool
25     */
26    private $cirrusDumpQueryAST = false;
27
28    /**
29     * @var bool
30     */
31    private $cirrusDumpResult = false;
32
33    /**
34     * @var string|null
35     */
36    private $cirrusExplain;
37
38    /**
39     * @var string|null
40     */
41    private $cirrusMLRModel;
42
43    /**
44     * @var bool used by unit tests (to not die and return the query as json back to the caller)
45     */
46    private $dumpAndDie = false;
47
48    private function __construct() {
49    }
50
51    /**
52     * @param WebRequest $request
53     * @return CirrusDebugOptions
54     */
55    public static function fromRequest( WebRequest $request ) {
56        $options = new self();
57        $options->cirrusCompletionVariant = $request->getArray( 'cirrusCompletionVariant' );
58        $options->cirrusDumpQuery = $request->getCheck( 'cirrusDumpQuery' );
59        $options->cirrusDumpQueryAST = $request->getCheck( 'cirrusDumpQueryAST' );
60        $options->cirrusDumpResult = $request->getCheck( 'cirrusDumpResult' );
61        $options->cirrusExplain = self::debugOption( $request, 'cirrusExplain', [ 'verbose', 'pretty', 'hot', 'raw' ] );
62        $options->cirrusMLRModel = $request->getVal( 'cirrusMLRModel' );
63        $options->dumpAndDie = $options->cirrusDumpQuery || $options->cirrusDumpQueryAST || $options->cirrusDumpResult;
64        return $options;
65    }
66
67    /**
68     * Default options (no debug options set)
69     * @return CirrusDebugOptions
70     */
71    public static function defaultOptions() {
72        return new self();
73    }
74
75    /**
76     * Dump the query but not die.
77     * Only useful in Unit tests.
78     * @return CirrusDebugOptions
79     */
80    public static function forDumpingQueriesInUnitTests() {
81        $options = new self();
82        $options->cirrusDumpQuery = true;
83        $options->dumpAndDie = false;
84        return $options;
85    }
86
87    /**
88     * @param string|null $withExplain
89     * @return CirrusDebugOptions
90     */
91    public static function forRelevanceTesting( $withExplain = null ) {
92        $options = new self();
93        $options->cirrusExplain = $withExplain;
94        return $options;
95    }
96
97    /**
98     * Inspect the param names $param and return its value only
99     * if it belongs to the set of allowed values declared in $allowedValues
100     * @param WebRequest $request
101     * @param string $param
102     * @param string[] $allowedValues
103     * @return string|null the debug option or null
104     */
105    private static function debugOption( WebRequest $request, $param, array $allowedValues ) {
106        $val = $request->getVal( $param );
107        if ( $val === null ) {
108            return null;
109        }
110        if ( in_array( $val, $allowedValues ) ) {
111            return $val;
112        }
113        return null;
114    }
115
116    /**
117     * @return null|string[]
118     */
119    public function getCirrusCompletionVariant() {
120        return $this->cirrusCompletionVariant;
121    }
122
123    /**
124     * @return bool
125     */
126    public function isCirrusDumpQuery() {
127        return $this->cirrusDumpQuery;
128    }
129
130    /**
131     * @return bool
132     */
133    public function isCirrusDumpQueryAST() {
134        return $this->cirrusDumpQueryAST;
135    }
136
137    /**
138     * @return bool
139     */
140    public function isCirrusDumpResult() {
141        return $this->cirrusDumpResult;
142    }
143
144    /**
145     * @return string|null The formatting to apply, or null to return raw explains
146     */
147    public function getCirrusExplainFormat() {
148        if ( $this->cirrusExplain === 'raw' || $this->cirrusDumpQuery || $this->cirrusDumpQueryAST ) {
149            return null;
150        }
151        return $this->cirrusExplain;
152    }
153
154    /**
155     * @return string|null
156     */
157    public function getCirrusMLRModel() {
158        return $this->cirrusMLRModel;
159    }
160
161    /**
162     * @return bool
163     */
164    public function isDumpAndDie() {
165        return $this->dumpAndDie;
166    }
167
168    /**
169     * @return bool true if raw data (query or results) needs to be returned
170     */
171    public function isReturnRaw() {
172        return $this->cirrusDumpQuery || $this->cirrusDumpQueryAST || $this->cirrusDumpResult;
173    }
174
175    /**
176     * @param Query $query
177     * @return Query
178     */
179    public function applyDebugOptions( Query $query ) {
180        if ( $this->cirrusExplain !== null ) {
181            $query->setExplain( true );
182        }
183        return $query;
184    }
185
186    /**
187     * @return bool True when queries built with this set of debug options must
188     *  not have their results cached and returned to other users.
189     */
190    public function mustNeverBeCached() {
191        return $this->isReturnRaw() || $this->cirrusExplain !== null;
192    }
193}