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 self
54     */
55    public static function fromRequest( WebRequest $request ): self {
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     */
70    public static function defaultOptions(): self {
71        return new self();
72    }
73
74    /**
75     * Dump the query but not die.
76     * Only useful in Unit tests.
77     */
78    public static function forDumpingQueriesInUnitTests(): self {
79        $options = new self();
80        $options->cirrusDumpQuery = true;
81        $options->dumpAndDie = false;
82        return $options;
83    }
84
85    /**
86     * @param string|null $withExplain
87     * @return self
88     */
89    public static function forRelevanceTesting( $withExplain = null ): self {
90        $options = new self();
91        $options->cirrusExplain = $withExplain;
92        return $options;
93    }
94
95    /**
96     * Inspect the param names $param and return its value only
97     * if it belongs to the set of allowed values declared in $allowedValues
98     * @param WebRequest $request
99     * @param string $param
100     * @param string[] $allowedValues
101     * @return string|null the debug option or null
102     */
103    private static function debugOption( WebRequest $request, $param, array $allowedValues ) {
104        $val = $request->getVal( $param );
105        if ( $val === null ) {
106            return null;
107        }
108        if ( in_array( $val, $allowedValues ) ) {
109            return $val;
110        }
111        return null;
112    }
113
114    /**
115     * @return null|string[]
116     */
117    public function getCirrusCompletionVariant() {
118        return $this->cirrusCompletionVariant;
119    }
120
121    /**
122     * @return bool
123     */
124    public function isCirrusDumpQuery() {
125        return $this->cirrusDumpQuery;
126    }
127
128    /**
129     * @return bool
130     */
131    public function isCirrusDumpQueryAST() {
132        return $this->cirrusDumpQueryAST;
133    }
134
135    /**
136     * @return bool
137     */
138    public function isCirrusDumpResult() {
139        return $this->cirrusDumpResult;
140    }
141
142    /**
143     * @return string|null The formatting to apply, or null to return raw explains
144     */
145    public function getCirrusExplainFormat() {
146        if ( $this->cirrusExplain === 'raw' || $this->cirrusDumpQuery || $this->cirrusDumpQueryAST ) {
147            return null;
148        }
149        return $this->cirrusExplain;
150    }
151
152    /**
153     * @return string|null
154     */
155    public function getCirrusMLRModel() {
156        return $this->cirrusMLRModel;
157    }
158
159    /**
160     * @return bool
161     */
162    public function isDumpAndDie() {
163        return $this->dumpAndDie;
164    }
165
166    /**
167     * @return bool true if raw data (query or results) needs to be returned
168     */
169    public function isReturnRaw() {
170        return $this->cirrusDumpQuery || $this->cirrusDumpQueryAST || $this->cirrusDumpResult;
171    }
172
173    /**
174     * @param Query $query
175     * @return Query
176     */
177    public function applyDebugOptions( Query $query ) {
178        if ( $this->cirrusExplain !== null ) {
179            $query->setExplain( true );
180        }
181        return $query;
182    }
183
184    /**
185     * @return bool True when queries built with this set of debug options must
186     *  not have their results cached and returned to other users.
187     */
188    public function mustNeverBeCached() {
189        return $this->isReturnRaw() || $this->cirrusExplain !== null;
190    }
191}