Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
56.90% covered (warning)
56.90%
33 / 58
38.46% covered (danger)
38.46%
5 / 13
 CRAP
0.00% covered (danger)
0.00%
0 / 1
UnionQueryBuilder
56.90% covered (warning)
56.90%
33 / 58
38.46% covered (danger)
38.46%
5 / 13
 85.38
0.00% covered (danger)
0.00%
0 / 1
 __construct
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 add
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 all
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 limit
75.00% covered (warning)
75.00%
3 / 4
0.00% covered (danger)
0.00%
0 / 1
 2.06
 offset
75.00% covered (warning)
75.00%
3 / 4
0.00% covered (danger)
0.00%
0 / 1
 2.06
 orderBy
45.45% covered (danger)
45.45%
5 / 11
0.00% covered (danger)
0.00%
0 / 1
 9.06
 mergeOption
83.33% covered (warning)
83.33%
5 / 6
0.00% covered (danger)
0.00%
0 / 1
 3.04
 caller
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 fetchResultSet
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 fetchField
37.50% covered (danger)
37.50%
3 / 8
0.00% covered (danger)
0.00%
0 / 1
 5.20
 fetchFieldValues
0.00% covered (danger)
0.00%
0 / 8
0.00% covered (danger)
0.00%
0 / 1
 12
 fetchRow
75.00% covered (warning)
75.00%
3 / 4
0.00% covered (danger)
0.00%
0 / 1
 2.06
 getSQL
100.00% covered (success)
100.00%
4 / 4
100.00% covered (success)
100.00%
1 / 1
 2
1<?php
2
3namespace Wikimedia\Rdbms;
4
5use Wikimedia\Rdbms\Platform\ISQLPlatform;
6
7/**
8 * A query builder for UNION queries takes SelectQueryBuilder objects
9 *
10 * Any particular query builder object should only be used for a single database query,
11 * and not be reused afterwards.
12 *
13 * @since 1.41
14 * @ingroup Database
15 */
16class UnionQueryBuilder {
17    /** @var string sort the results in ascending order */
18    public const SORT_ASC = 'ASC';
19
20    /** @var string sort the results in descending order */
21    public const SORT_DESC = 'DESC';
22
23    /**
24     * @var SelectQueryBuilder[]
25     */
26    private $sqbs = [];
27
28    /** @var IDatabase */
29    private $db;
30
31    private $all = IReadableDatabase::UNION_DISTINCT;
32
33    private $options = [];
34
35    /**
36     * @var string The caller (function name) to be passed to IDatabase::query()
37     */
38    private $caller = __CLASS__;
39
40    /**
41     * To create a UnionQueryBuilder instance, use `$db->newUnionQueryBuilder()` instead.
42     *
43     * @param IDatabase $db
44     */
45    public function __construct( IDatabase $db ) {
46        $this->db = $db;
47    }
48
49    /**
50     * Add a select query builder object to the list of union
51     *
52     * @return $this
53     */
54    public function add( SelectQueryBuilder $selectQueryBuilder ) {
55        $this->sqbs[] = $selectQueryBuilder;
56        return $this;
57    }
58
59    /**
60     * Enable UNION_ALL option, the default is UNION_DISTINCT
61     *
62     * @return $this
63     */
64    public function all() {
65        $this->all = $this->db::UNION_ALL;
66        return $this;
67    }
68
69    /**
70     * Set the query limit. Return at most this many rows. The rows are sorted
71     * and then the first rows are taken until the limit is reached. Limit
72     * is applied to a result set after offset.
73     *
74     * If the query builder already has a limit, the old limit will be discarded.
75     * This would be also ignored if the DB does not support limit in union queries.
76     *
77     * @param int $limit
78     * @return $this
79     */
80    public function limit( $limit ) {
81        if ( !$this->db->unionSupportsOrderAndLimit() ) {
82            return $this;
83        }
84        $this->options['LIMIT'] = $limit;
85        return $this;
86    }
87
88    /**
89     * Set the offset. Skip this many rows at the start of the result set. Offset
90     * with limit() can theoretically be used for paging through a result set,
91     * but this is discouraged for performance reasons.
92     *
93     * If the query builder already has an offset, the old offset will be discarded.
94     * This would be also ignored if the DB does not support offset in union queries.
95     *
96     * @param int $offset
97     * @return $this
98     */
99    public function offset( $offset ) {
100        if ( !$this->db->unionSupportsOrderAndLimit() ) {
101            return $this;
102        }
103        $this->options['OFFSET'] = $offset;
104        return $this;
105    }
106
107    /**
108     * Set the ORDER BY clause. If it has already been set, append the
109     * additional fields to it.
110     *
111     * This would be ignored if the DB does not support order by in union queries.
112     *
113     * @param string[]|string $fields The field or list of fields to order by.
114     * @param-taint $fields exec_sql
115     * @param string|null $direction self::SORT_ASC or self::SORT_DESC.
116     * If this is null then $fields is assumed to optionally contain ASC or DESC
117     * after each field name.
118     * @param-taint $direction exec_sql
119     * @return $this
120     */
121    public function orderBy( $fields, $direction = null ) {
122        if ( !$this->db->unionSupportsOrderAndLimit() ) {
123            return $this;
124        }
125        if ( $direction === null ) {
126            $this->mergeOption( 'ORDER BY', $fields );
127        } elseif ( is_array( $fields ) ) {
128            $fieldsWithDirection = [];
129            foreach ( $fields as $field ) {
130                $fieldsWithDirection[] = "$field $direction";
131            }
132            $this->mergeOption( 'ORDER BY', $fieldsWithDirection );
133        } else {
134            $this->mergeOption( 'ORDER BY', "$fields $direction" );
135        }
136        return $this;
137    }
138
139    /**
140     * Add a value to an option which may be not set or a string or array.
141     *
142     * @param string $name
143     * @param string|string[] $newArrayOrValue
144     */
145    private function mergeOption( $name, $newArrayOrValue ) {
146        $value = isset( $this->options[$name] )
147            ? (array)$this->options[$name] : [];
148        if ( is_array( $newArrayOrValue ) ) {
149            $value = array_merge( $value, $newArrayOrValue );
150        } else {
151            $value[] = $newArrayOrValue;
152        }
153        $this->options[$name] = $value;
154    }
155
156    /**
157     * Set the method name to be included in an SQL comment.
158     *
159     * @param string $fname
160     * @param-taint $fname exec_sql
161     * @return $this
162     */
163    public function caller( $fname ) {
164        $this->caller = $fname;
165        return $this;
166    }
167
168    /**
169     * Run the constructed UNION query and return all results.
170     *
171     * @return IResultWrapper
172     */
173    public function fetchResultSet() {
174        $query = new Query( $this->getSQL(), ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT' );
175        return $this->db->query( $query, $this->caller );
176    }
177
178    /**
179     * Run the constructed UNION query, and return a single field extracted
180     * from the first result row. If there were no result rows, false is
181     * returned. This may only be called when only one field has been added to
182     * the constituent queries.
183     *
184     * @since 1.42
185     * @return mixed
186     * @return-taint tainted
187     */
188    public function fetchField() {
189        $this->limit( 1 );
190        foreach ( $this->fetchResultSet() as $row ) {
191            $row = (array)$row;
192            if ( count( $row ) !== 1 ) {
193                throw new \UnexpectedValueException(
194                    __METHOD__ . ' expects the query to have only one field' );
195            }
196            return $row[ array_key_first( $row ) ];
197        }
198        return false;
199    }
200
201    /**
202     * Run the constructed UNION query, and extract a single field from each
203     * result row, returning an array containing all the values. This may only
204     * be called when only one field has been added to the constituent queries.
205     *
206     * @since 1.42
207     * @return array
208     * @return-taint tainted
209     */
210    public function fetchFieldValues() {
211        $values = [];
212        foreach ( $this->fetchResultSet() as $row ) {
213            $row = (array)$row;
214            if ( count( $row ) !== 1 ) {
215                throw new \UnexpectedValueException(
216                    __METHOD__ . ' expects the query to have only one field' );
217            }
218            $values[] = $row[ array_key_first( $row ) ];
219        }
220        return $values;
221    }
222
223    /**
224     * Run the constructed UNION query, and return the first result row. If
225     * there were no results, return false.
226     *
227     * @since 1.42
228     * @return \stdClass|false
229     * @return-taint tainted
230     */
231    public function fetchRow() {
232        $this->limit( 1 );
233        foreach ( $this->fetchResultSet() as $row ) {
234            return $row;
235        }
236        return false;
237    }
238
239    /**
240     * Get the SQL query string which would be used by fetchResultSet().
241     *
242     * @since 1.42
243     * @return string
244     */
245    public function getSQL() {
246        $sqls = [];
247        foreach ( $this->sqbs as $sqb ) {
248            $sqls[] = $sqb->getSQL();
249        }
250        return $this->db->unionQueries( $sqls, $this->all, $this->options );
251    }
252
253}