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