<?php
/*
* OIDplus 2.0
* Copyright 2019 - 2023 Daniel Marschall, ViaThinkSoft
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
namespace ViaThinkSoft\OIDplus;
// phpcs:disable PSR1.Files.SideEffects
// phpcs:enable PSR1.Files.SideEffects
abstract class OIDplusQueryResult extends OIDplusBaseClass {
/**
* @return bool
*/
abstract public function containsResultSet(): bool;
/**
* @return int
*/
abstract protected function do_num_rows(): int;
/**
* @var array|null
*/
protected $prefetchedArray = null;
/**
* @var int
*/
protected $countAlreadyFetched = 0;
/**
* Please override this method if the database drive can perform a "fetch all" in its own way
*
* @return void
* @throws OIDplusConfigInitializationException
* @throws OIDplusException
* @throws \ReflectionException
*/
public function prefetchAll() {
if (!is_null($this->prefetchedArray)) return; while ($row = $this->fetch_array()) {
$pfa[] = $row; // you may not edit $this->prefetchedArray at this step, because $this->>fetch_array() checks it
$this->countAlreadyFetched--; // because fetch_array() increases $this->countAlreadyFetched, we need to revert it
}
$this->prefetchedArray = $pfa;
}
/**
* @return int
* @throws OIDplusConfigInitializationException
* @throws OIDplusException
*/
public final function num_rows(): int {
if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)'));
if (!is_null($this->prefetchedArray)) { return count($this->prefetchedArray) + $this->countAlreadyFetched; }
$ret = $this->do_num_rows();
if ($ret === -1) throw new OIDplusException(_L('The database driver has problems with "%1"','num_rows'));
return $ret;
}
/**
* Plugins can override and extend this method. It post-processes contents of fetch_array() and fetch_object()
* to fix various issues with database drivers.
*
* @param array|object &$ret
* @return void
*/
protected function fixFields(&$ret) {
// ODBC gives bit(1) as binary, MySQL as integer and PDO as string.
// We'll do it like MySQL does, even if ODBC is actually more correct.
foreach ($ret as &$value) {
if ($value === chr(0)) $value = 0; if ($value === chr(1)) $value = 1; }
// Oracle returns $ret['VALUE'] because unquoted column-names are always upper-case
// We can't quote every single column throughout the whole program, so we use this workaround...
foreach ($keys as $key) {
}
foreach ($ret as $name => $val) {
}
}
}
/**
* Please override do_fetch_object(), do_fetch_array(), or both.
* @return array|null
*/
protected function do_fetch_array()/*: ?array*/ {
return null;
}
/**
* @return array|null
* @throws OIDplusConfigInitializationException
* @throws OIDplusException
* @throws \ReflectionException
*/
public final function fetch_array()/*: ?array*/ {
if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)'));
if (!is_null($this->prefetchedArray)) { // Prefetched value exists. Use it.
} else {
$reflector = new \ReflectionMethod($this, 'do_fetch_array');
$isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
if ($isImplemented) {
// do_fetch_array() is implemented. Use it.
$ary = $this->do_fetch_array();
} else {
// Use the implementation of do_fetch_object()
$reflector = new \ReflectionMethod($this, 'do_fetch_object');
$isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
if (!$isImplemented) {
throw new OIDplusException
(_L
("Class %1 is erroneous: At least one fetch-method needs to be overridden", get_class($this))); }
$obj = $this->do_fetch_object();
$ary = is_null($obj) ?
null : stdobj_to_array
($obj); }
}
$this->countAlreadyFetched++;
$this->fixFields($ary);
}
return $ary;
}
/**
* Please override do_fetch_object(), do_fetch_array(), or both.
* @return object|null
*/
protected function do_fetch_object()/*: ?\stdClass*/ {
return null;
}
/**
* @return object|null
* @throws OIDplusConfigInitializationException
* @throws OIDplusException
* @throws \ReflectionException
*/
public final function fetch_object()/*: ?\stdClass*/ {
if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)'));
if (!is_null($this->prefetchedArray)) { // Prefetched value exists. Use it.
$obj = is_null($ary) ?
null : array_to_stdobj
($ary); } else {
$reflector = new \ReflectionMethod($this, 'do_fetch_object');
$isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
if ($isImplemented) {
// do_fetch_object() is implemented. Use it.
$obj = $this->do_fetch_object();
} else {
// Use the implementation of do_fetch_array()
$reflector = new \ReflectionMethod($this, 'do_fetch_array');
$isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
if (!$isImplemented) {
throw new OIDplusException
(_L
("Class %1 is erroneous: At least one fetch-method needs to be overridden", get_class($this))); }
$ary = $this->do_fetch_array();
$obj = is_null($ary) ?
null : array_to_stdobj
($ary); }
}
$this->countAlreadyFetched++;
$this->fixFields($obj);
}
return $obj;
}
/**
* The any() function returns true if there is at least one
* row in the section. By default, num_rows() will be used.
* Plugins can override this method if they have a possibility
* of making this functionality more efficient.
*
* @return bool
* @throws OIDplusException
*/
public function any(): bool {
return $this->num_rows() > 0;
}
/**
* @param string $dbField
* @return void
* @throws OIDplusConfigInitializationException
* @throws OIDplusException
* @throws \ReflectionException
*/
public final function naturalSortByField(string $dbField) {
if (is_null($this->prefetchedArray)) { $this->prefetchAll();
}
// Sort $this->prefetchedArray by field $dbField
natsort_field($this->prefetchedArray, $dbField);
}
}