Subversion Repositories oidplus

Rev

Rev 1204 | Rev 1461 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed

  1. <?php
  2.  
  3. /*
  4.  * OIDplus 2.0
  5.  * Copyright 2019 - 2023 Daniel Marschall, ViaThinkSoft
  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.  
  20. namespace ViaThinkSoft\OIDplus;
  21.  
  22. // phpcs:disable PSR1.Files.SideEffects
  23. \defined('INSIDE_OIDPLUS') or die;
  24. // phpcs:enable PSR1.Files.SideEffects
  25.  
  26. abstract class OIDplusQueryResult extends OIDplusBaseClass {
  27.  
  28.         /**
  29.          * @return bool
  30.          */
  31.         abstract public function containsResultSet(): bool;
  32.  
  33.         /**
  34.          * @return int
  35.          */
  36.         abstract protected function do_num_rows(): int;
  37.  
  38.         /**
  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 driver 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.         /**
  67.          * @return int
  68.          * @throws OIDplusConfigInitializationException
  69.          * @throws OIDplusException
  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)'));
  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;
  83.         }
  84.  
  85.         /**
  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, although ODBC semms to be more correct.
  95.                 // We don't put this code into OIDplusQueryResultODBC.class.php, because other
  96.                 // DBMS might do the same - and then we would be prepared.
  97.                 foreach ($ret as &$value) {
  98.                         if ($value === chr(0)) $value = 0;
  99.                         if ($value === chr(1)) $value = 1;
  100.                 }
  101.  
  102.                 // Oracle and Firebird returns $ret['VALUE'] because unquoted column-names are always upper-case
  103.                 // We can't quote every single column throughout the whole program, so we use this workaround...
  104.                 if (is_array($ret)) {
  105.                         foreach ($ret as $name => $val) {
  106.                                 $ret[strtolower($name)] = $val;
  107.                                 $ret[strtoupper($name)] = $val;
  108.                         }
  109.                 } else if (is_object($ret)) {
  110.                         foreach ($ret as $name => $val) {
  111.                                 $ret->{strtoupper($name)} = $val;
  112.                                 $ret->{strtolower($name)} = $val;
  113.                         }
  114.                 } else {
  115.                         assert(false);
  116.                 }
  117.         }
  118.  
  119.         /**
  120.          * Please override do_fetch_object(), do_fetch_array(), or both.
  121.          * @return array|null
  122.          */
  123.         protected function do_fetch_array()/*: ?array*/ {
  124.                 assert(false);
  125.                 return null;
  126.         }
  127.  
  128.         /**
  129.          * @return array|null
  130.          * @throws OIDplusConfigInitializationException
  131.          * @throws OIDplusException
  132.          * @throws \ReflectionException
  133.          */
  134.         public final function fetch_array()/*: ?array*/ {
  135.                 if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)'));
  136.                 if (!is_null($this->prefetchedArray)) {
  137.                         // Prefetched value exists. Use it.
  138.                         $ary = array_shift($this->prefetchedArray);
  139.                 } else {
  140.                         $reflector = new \ReflectionMethod($this, 'do_fetch_array');
  141.                         $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
  142.                         if ($isImplemented) {
  143.                                 // do_fetch_array() is implemented. Use it.
  144.                                 $ary = $this->do_fetch_array();
  145.                         } else {
  146.                                 // Use the implementation of do_fetch_object()
  147.                                 $reflector = new \ReflectionMethod($this, 'do_fetch_object');
  148.                                 $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
  149.                                 if (!$isImplemented) {
  150.                                         throw new OIDplusException(_L("Class %1 is erroneous: At least one fetch-method needs to be overridden", get_class($this)));
  151.                                 }
  152.                                 $obj = $this->do_fetch_object();
  153.                                 $ary = is_null($obj) ? null : stdobj_to_array($obj);
  154.                         }
  155.                 }
  156.                 if (!is_null($ary)) {
  157.                         $this->countAlreadyFetched++;
  158.                         $this->fixFields($ary);
  159.                 }
  160.                 return $ary;
  161.         }
  162.  
  163.         /**
  164.          * Please override do_fetch_object(), do_fetch_array(), or both.
  165.          * @return object|null
  166.          */
  167.         protected function do_fetch_object()/*: ?\stdClass*/ {
  168.                 assert(false);
  169.                 return null;
  170.         }
  171.  
  172.         /**
  173.          * @return object|null
  174.          * @throws OIDplusConfigInitializationException
  175.          * @throws OIDplusException
  176.          * @throws \ReflectionException
  177.          */
  178.         public final function fetch_object()/*: ?\stdClass*/ {
  179.                 if (!$this->containsResultSet()) throw new OIDplusException(_L('The query has returned no result set (i.e. it was not a SELECT query)'));
  180.                 if (!is_null($this->prefetchedArray)) {
  181.                         // Prefetched value exists (as array). Convert and use it.
  182.                         $ary = array_shift($this->prefetchedArray);
  183.                         $obj = is_null($ary) ? null : array_to_stdobj($ary);
  184.                 } else {
  185.                         $reflector = new \ReflectionMethod($this, 'do_fetch_object');
  186.                         $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
  187.                         if ($isImplemented) {
  188.                                 // do_fetch_object() is implemented. Use it.
  189.                                 $obj = $this->do_fetch_object();
  190.                         } else {
  191.                                 // Use the implementation of do_fetch_array()
  192.                                 $reflector = new \ReflectionMethod($this, 'do_fetch_array');
  193.                                 $isImplemented = ($reflector->getDeclaringClass()->getName() !== self::class);
  194.                                 if (!$isImplemented) {
  195.                                         throw new OIDplusException(_L("Class %1 is erroneous: At least one fetch-method needs to be overridden", get_class($this)));
  196.                                 }
  197.                                 $ary = $this->do_fetch_array();
  198.                                 $obj = is_null($ary) ? null : array_to_stdobj($ary);
  199.                         }
  200.                 }
  201.                 if (!is_null($obj)) {
  202.                         $this->countAlreadyFetched++;
  203.                         $this->fixFields($obj);
  204.                 }
  205.                 return $obj;
  206.         }
  207.  
  208.         /**
  209.          * The any() function returns true if there is at least one
  210.          * row in the section. By default, num_rows() will be used.
  211.          * Plugins can override this method if they have a possibility
  212.          * of making this functionality more efficient.
  213.          *
  214.          * @return bool
  215.          * @throws OIDplusException
  216.          */
  217.         public function any(): bool {
  218.                 return $this->num_rows() > 0;
  219.         }
  220.  
  221.         /**
  222.          * @param string $dbField
  223.          * @return void
  224.          * @throws OIDplusConfigInitializationException
  225.          * @throws OIDplusException
  226.          * @throws \ReflectionException
  227.          */
  228.         public final function naturalSortByField(string $dbField) { // TODO: Argument asc or desc order
  229.                 if (is_null($this->prefetchedArray)) {
  230.                         $this->prefetchAll();
  231.                 }
  232.  
  233.                 // Sort $this->prefetchedArray by field $dbField
  234.                 natsort_field($this->prefetchedArray, $dbField);
  235.         }
  236. }
  237.