Rev 1152 | Rev 1157 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
236 | daniel-mar | 1 | <?php |
2 | |||
3 | /* |
||
4 | * OIDplus 2.0 |
||
1086 | daniel-mar | 5 | * Copyright 2019 - 2023 Daniel Marschall, ViaThinkSoft |
236 | daniel-mar | 6 | * |
7 | * Licensed under the Apache License, Version 2.0 (the "License"); |
||
8 | * you may not use this file except in compliance with the License. |
||
9 | * You may obtain a copy of the License at |
||
10 | * |
||
11 | * http://www.apache.org/licenses/LICENSE-2.0 |
||
12 | * |
||
13 | * Unless required by applicable law or agreed to in writing, software |
||
14 | * distributed under the License is distributed on an "AS IS" BASIS, |
||
15 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
||
16 | * See the License for the specific language governing permissions and |
||
17 | * limitations under the License. |
||
18 | */ |
||
19 | |||
1050 | daniel-mar | 20 | namespace ViaThinkSoft\OIDplus; |
511 | daniel-mar | 21 | |
1086 | daniel-mar | 22 | // phpcs:disable PSR1.Files.SideEffects |
23 | \defined('INSIDE_OIDPLUS') or die; |
||
24 | // phpcs:enable PSR1.Files.SideEffects |
||
25 | |||
730 | daniel-mar | 26 | abstract class OIDplusQueryResult extends OIDplusBaseClass { |
1116 | daniel-mar | 27 | |
28 | /** |
||
29 | * @return bool |
||
30 | */ |
||
236 | daniel-mar | 31 | abstract public function containsResultSet(): bool; |
1116 | daniel-mar | 32 | |
33 | /** |
||
34 | * @return int |
||
35 | */ |
||
1152 | daniel-mar | 36 | abstract protected function do_num_rows(): int; |
1116 | daniel-mar | 37 | |
38 | /** |
||
1156 | daniel-mar | 39 | * @var array|null |
40 | */ |
||
41 | protected $prefetchedArray = null; |
||
42 | |||
43 | /** |
||
44 | * @var int |
||
45 | */ |
||
46 | protected $countAlreadyFetched = 0; |
||
47 | |||
48 | /** |
||
49 | * Please override this method if the database drive can perform a "fetch all" in its own way |
||
50 | * |
||
51 | * @return void |
||
52 | * @throws OIDplusConfigInitializationException |
||
53 | * @throws OIDplusException |
||
54 | * @throws \ReflectionException |
||
55 | */ |
||
56 | public function prefetchAll() { |
||
57 | if (!is_null($this->prefetchedArray)) return; |
||
58 | $pfa = array(); |
||
59 | while ($row = $this->fetch_array()) { |
||
60 | $pfa[] = $row; // you may not edit $this->prefetchedArray at this step, because $this->>fetch_array() checks it |
||
61 | $this->countAlreadyFetched--; // because fetch_array() increases $this->countAlreadyFetched, we need to revert it |
||
62 | } |
||
63 | $this->prefetchedArray = $pfa; |
||
64 | } |
||
65 | |||
66 | /** |
||
1152 | daniel-mar | 67 | * @return int |
1156 | daniel-mar | 68 | * @throws OIDplusConfigInitializationException |
69 | * @throws OIDplusException |
||
1152 | daniel-mar | 70 | */ |
71 | public final function num_rows(): int { |
||
72 | if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)')); |
||
1156 | daniel-mar | 73 | |
74 | if (!is_null($this->prefetchedArray)) { |
||
75 | return count($this->prefetchedArray) + $this->countAlreadyFetched; |
||
76 | } |
||
77 | |||
78 | $ret = $this->do_num_rows(); |
||
79 | |||
80 | if ($ret === -1) throw new OIDplusException(_L('The database driver has problems with "%1"','num_rows')); |
||
81 | |||
82 | return $ret; |
||
1152 | daniel-mar | 83 | } |
84 | |||
85 | /** |
||
1156 | daniel-mar | 86 | * Plugins can override and extend this method. It post-processes contents of fetch_array() and fetch_object() |
87 | * to fix various issues with database drivers. |
||
88 | * |
||
89 | * @param array|object &$ret |
||
90 | * @return void |
||
91 | */ |
||
92 | protected function fixFields(&$ret) { |
||
93 | // ODBC gives bit(1) as binary, MySQL as integer and PDO as string. |
||
94 | // We'll do it like MySQL does, even if ODBC is actually more correct. |
||
95 | foreach ($ret as &$value) { |
||
96 | if ($value === chr(0)) $value = 0; |
||
97 | if ($value === chr(1)) $value = 1; |
||
98 | } |
||
99 | |||
100 | // Oracle returns $ret['VALUE'] because unquoted column-names are always upper-case |
||
101 | // We can't quote every single column throughout the whole program, so we use this workaround... |
||
102 | if (is_array($ret)) { |
||
103 | $keys = array_keys($ret); |
||
104 | foreach ($keys as $key) { |
||
105 | $ret[strtolower($key)] = $ret[$key]; |
||
106 | $ret[strtoupper($key)] = $ret[$key]; |
||
107 | } |
||
108 | } else if (is_object($ret)) { |
||
109 | foreach ($ret as $name => $val) { |
||
110 | $ret->{strtoupper($name)} = $val; |
||
111 | $ret->{strtolower($name)} = $val; |
||
112 | } |
||
113 | } |
||
114 | } |
||
115 | |||
116 | /** |
||
117 | * Please override do_fetch_object(), do_fetch_array(), or both. |
||
1116 | daniel-mar | 118 | * @return array|null |
119 | */ |
||
1152 | daniel-mar | 120 | protected function do_fetch_array()/*: ?array*/ { |
121 | assert(false); |
||
122 | return null; |
||
123 | } |
||
1116 | daniel-mar | 124 | |
125 | /** |
||
1152 | daniel-mar | 126 | * @return array|null |
1156 | daniel-mar | 127 | * @throws OIDplusConfigInitializationException |
128 | * @throws OIDplusException |
||
129 | * @throws \ReflectionException |
||
1152 | daniel-mar | 130 | */ |
131 | public final function fetch_array()/*: ?array*/ { |
||
132 | if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)')); |
||
1156 | daniel-mar | 133 | if (!is_null($this->prefetchedArray)) { |
134 | // Prefetched value exists. Use it. |
||
135 | $ary = array_shift($this->prefetchedArray); |
||
136 | } else { |
||
137 | $reflector = new \ReflectionMethod($this, 'do_fetch_array'); |
||
138 | $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class); |
||
139 | if ($isImplemented) { |
||
140 | // do_fetch_array() is implemented. Use it. |
||
141 | $ary = $this->do_fetch_array(); |
||
142 | } else { |
||
143 | // Use the implementation of do_fetch_object() |
||
144 | $reflector = new \ReflectionMethod($this, 'do_fetch_object'); |
||
145 | $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class); |
||
146 | if (!$isImplemented) { |
||
147 | throw new OIDplusException(_L("Class %1 is erroneous: At least one fetch-method needs to be overridden", get_class($this))); |
||
148 | } |
||
149 | $obj = $this->do_fetch_object(); |
||
150 | $ary = is_null($obj) ? null : stdobj_to_array($obj); |
||
151 | } |
||
1152 | daniel-mar | 152 | } |
1156 | daniel-mar | 153 | if (!is_null($ary)) { |
154 | $this->countAlreadyFetched++; |
||
155 | $this->fixFields($ary); |
||
1152 | daniel-mar | 156 | } |
157 | return $ary; |
||
158 | } |
||
159 | |||
160 | /** |
||
1156 | daniel-mar | 161 | * Please override do_fetch_object(), do_fetch_array(), or both. |
1116 | daniel-mar | 162 | * @return object|null |
163 | */ |
||
1156 | daniel-mar | 164 | protected function do_fetch_object()/*: ?\stdClass*/ { |
1152 | daniel-mar | 165 | assert(false); |
166 | return null; |
||
167 | } |
||
790 | daniel-mar | 168 | |
1116 | daniel-mar | 169 | /** |
1152 | daniel-mar | 170 | * @return object|null |
1156 | daniel-mar | 171 | * @throws OIDplusConfigInitializationException |
172 | * @throws OIDplusException |
||
173 | * @throws \ReflectionException |
||
1152 | daniel-mar | 174 | */ |
1156 | daniel-mar | 175 | public final function fetch_object()/*: ?\stdClass*/ { |
1152 | daniel-mar | 176 | if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)')); |
1156 | daniel-mar | 177 | if (!is_null($this->prefetchedArray)) { |
178 | // Prefetched value exists. Use it. |
||
179 | $ary = array_shift($this->prefetchedArray); |
||
180 | $obj = is_null($ary) ? null : array_to_stdobj($ary); |
||
181 | } else { |
||
182 | $reflector = new \ReflectionMethod($this, 'do_fetch_object'); |
||
183 | $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class); |
||
184 | if ($isImplemented) { |
||
185 | // do_fetch_object() is implemented. Use it. |
||
186 | $obj = $this->do_fetch_object(); |
||
187 | } else { |
||
188 | // Use the implementation of do_fetch_array() |
||
189 | $reflector = new \ReflectionMethod($this, 'do_fetch_array'); |
||
190 | $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class); |
||
191 | if (!$isImplemented) { |
||
192 | throw new OIDplusException(_L("Class %1 is erroneous: At least one fetch-method needs to be overridden", get_class($this))); |
||
193 | } |
||
194 | $ary = $this->do_fetch_array(); |
||
195 | $obj = is_null($ary) ? null : array_to_stdobj($ary); |
||
196 | } |
||
1152 | daniel-mar | 197 | } |
1156 | daniel-mar | 198 | if (!is_null($obj)) { |
199 | $this->countAlreadyFetched++; |
||
200 | $this->fixFields($obj); |
||
1152 | daniel-mar | 201 | } |
202 | return $obj; |
||
203 | } |
||
204 | |||
205 | /** |
||
1116 | daniel-mar | 206 | * The any() function returns true if there is at least one |
207 | * row in the section. By default, num_rows() will be used. |
||
208 | * Plugins can override this method if they have a possibility |
||
209 | * of making this functionality more efficient. |
||
1156 | daniel-mar | 210 | * |
1116 | daniel-mar | 211 | * @return bool |
1156 | daniel-mar | 212 | * @throws OIDplusException |
1116 | daniel-mar | 213 | */ |
790 | daniel-mar | 214 | public function any(): bool { |
215 | return $this->num_rows() > 0; |
||
216 | } |
||
1156 | daniel-mar | 217 | |
218 | /** |
||
219 | * @param string $dbField |
||
220 | * @return void |
||
221 | * @throws OIDplusConfigInitializationException |
||
222 | * @throws OIDplusException |
||
223 | * @throws \ReflectionException |
||
224 | */ |
||
225 | public final function naturalSortByField(string $dbField) { |
||
226 | if (is_null($this->prefetchedArray)) { |
||
227 | $this->prefetchAll(); |
||
228 | } |
||
229 | |||
230 | // Sort $this->prefetchedArray by field $dbField |
||
231 | natsort_field($this->prefetchedArray, $dbField); |
||
232 | } |
||
236 | daniel-mar | 233 | } |