valuestore class: php8 only; added variable types; short array syntax

public_html/valuestore/classes/valuestore.class.php

@@ -26,40 +26,45 @@
  *     $aVersions=$oVersion->deleteValues("version");
  * 
  * @author hahn
+ * 
+ * Axel: <axel.hahn@unibe.ch>
+ * (...)
+ * 2024-08-29  Axel   php8 only; added variable types; short array syntax
  */
-class valuestore {
+class valuestore
+{
 
-    public $sProject = false;
-    public $sPackage = false;
-    public $sPhase = false;
-    public $sPlace = false;
-    public $sHost = false;
-    public $sVariable = false;
-    public $sData = false;
+    public string $sProject = '';
+    public string $sPackage = '';
+    public string $sPhase = '';
+    public string $sPlace = '';
+    public string $sHost = '';
+    public string $sVariable = '';
+    public string $sData = '';
 
-    protected $_bDebug = true;
+    protected bool $_bDebug = true;
 
     /**
      * filename of sqlite database file
-     * @var type 
+     * @var string
      */
-    private $_dbfile = false;
+    private string $_dbfile = '';
 
     /**
      * database connection
      * @var object
      */
-    protected $_oDB = false;
+    protected object $_oDB;
 
     /**
      * TTL vor stored values - 1 day [sec]
      * @var integer
      */
-    protected $_iTTL = 86400;
+    protected int $_iTTL = 86400;
 
     /**
      * create statement for the database
-     * @var type 
+     * @var string
      */
     private $_sCreate = '
         CREATE TABLE "values" (
@@ -77,17 +82,18 @@ class valuestore {
     ;
 
     // hardcoded
-    protected $_allowedPhases=array('preview', 'stage', 'live');
-    protected $_allowedPlaces=array('onhold', 'ready2install', 'deployed');
+    protected array $_allowedPhases = ['preview', 'stage', 'live'];
+    protected array $_allowedPlaces = ['onhold', 'ready2install', 'deployed'];
 
     // ----------------------------------------------------------------------
     // CONSTRUCTOR
     // ----------------------------------------------------------------------
 
     /**
-     * constructor ... no params
+     * Constructor ... no params
      */
-    public function __construct(){
+    public function __construct()
+    {
 
         // cache dir is hardcoded to versions directory :-/
         $this->_dbfile = __DIR__ . '/../data/versioncache.db';
@@ -97,14 +103,18 @@ class valuestore {
             $this->_createDb();
         }
     }
+
     /**
-     * add a log messsage
+     * Add a logging messsage with ahlogger
+     * 
      * @global object $oLog
+     * 
      * @param  string $sMessage  messeage text
      * @param  string $sLevel    warnlevel of the given message
      * @return bool
      */
-    private function log($sMessage, $sLevel = "info") {
+    private function log($sMessage, $sLevel = "info"): bool
+    {
         global $oCLog;
         if ($oCLog) {
             return $oCLog->add(basename(__FILE__) . " class " . __CLASS__ . " - " . $sMessage, $sLevel);
@@ -118,8 +128,10 @@ class valuestore {
 
     /**
      * create sqlite database - called in constructor if the file does not exist
+     * @return boolean
      */
-    private function _createDb() {
+    private function _createDb(): bool
+    {
         if (file_exists($this->_dbfile)) {
             echo $this->_bDebug ? "removing existing file $this->_dbfile ...<br>\n" : '';
             unlink($this->_dbfile);
@@ -135,12 +147,16 @@ class valuestore {
     }
 
     /**
-     * execute a sql statement
+     * Execute a sql statement
+     * It returns false if the query failed.
+     * On success you get a PDO result object
+     * 
      * @param string $sSql   sql statement
      * @param array  $aVars  array with values (uses PDO::prepare(); $sSql must contain placeholders :key)
-     * @return database object
+     * @return bool|object result object of query
      */
-    private function _makeQuery($sSql, $aVars=false) {
+    private function _makeQuery(string $sSql, array $aVars = []): bool|object
+    {
         // $this->_log(__FUNCTION__."($sSql)");
         // echo "DEBUG: executing SQL<pre>$sSql</pre>";
         $this->log("start query");
@@ -158,20 +174,23 @@ class valuestore {
     }
 
     /**
-     * execute a sql statement
+     * Execute a sql SELECT statement and get an array with results
+     * 
      * @param string $sSql  sql statement
+     * @param string $sKey  optional: return only values of this key
      * @return array of resultset
      */
-    private function _makeSelectQuery($sSql, $aKey=false) {
+    private function _makeSelectQuery(string $sSql, string $sKey = ''): array
+    {
         // $this->_log(__FUNCTION__."($sSql)");
         // echo "DEBUG: executing select SQL<pre>$sSql</pre>";
         $this->log("start query");
         $oStatement = $this->_oDB->prepare($sSql);
         $oStatement->execute();
-        $aReturn=array();
+        $aReturn = [];
         while ($row = $oStatement->fetch(PDO::FETCH_ASSOC)) {
-          if ($aKey && array_key_exists($aKey, $row)){
-            $aReturn[] = $row[$aKey];
+            if ($sKey && array_key_exists($sKey, $row)) {
+                $aReturn[] = $row[$sKey];
             } else {
                 $aReturn[] = $row;
             }
@@ -181,13 +200,15 @@ class valuestore {
     }
 
     /**
-     * log error and quit. it echoes the error message on screen if debug 
+     * Log error and quit. it echoes the error message on screen if debug 
      * is enabled.
+     * 
      * @param string  $sFunction  name of method that throws the error
      * @param string  $sMessage   error message
-     * @return boolean
+     * @return void
      */
-    private function _quit($sFunction, $sMessage){
+    private function _quit(string $sFunction, string $sMessage): void
+    {
         error_log(__CLASS__ . "::$sFunction - $sMessage " . "whereiam: " . print_r($this->whereiam(), 1));
         if ($this->_bDebug) {
             echo __CLASS__ . "::$sFunction stopped.<br>\n"
@@ -197,7 +218,6 @@ class valuestore {
         } else {
             die("ERROR ... wrong usage of class " . __CLASS__);
         }
-        return false;
     }
 
     // ----------------------------------------------------------------------
@@ -206,28 +226,31 @@ class valuestore {
 
 
     /**
-     * get list of current projects
-     * @return type
+     * Get list of current projects
+     * @return array
      */
-    public function getProjects(){
+    public function getProjects(): array
+    {
         $sSql = "select distinct(project) from `values`";
         return $this->_makeSelectQuery($sSql, 'project');
     }
 
     /**
-     * get list of current projects
-     * @return type
+     * Get list of current projects
+     * @return array
      */
-    public function getPackages(){
+    public function getPackages(): array
+    {
         $sSql = "select distinct(package) from `values`";
         return $this->_makeSelectQuery($sSql, 'package');
     }
 
     /**
-     * get phases of the current project; a project must be set be set before
-     * @return type
+     * Get phases of the current project; a project must be set be set before
+     * @return array
      */
-    public function getPhases(){
+    public function getPhases(): array
+    {
         if (!$this->sProject && !$this->sPackage) {
             $this->_quit(__FUNCTION__, "you need to set a project first. Use the setProject() method to do so.");
         }
@@ -262,9 +285,10 @@ class valuestore {
 
     /**
      * get hosts that have installed a project
-     * @return type
+     * @return array
      */
-    public function getHosts(){
+    public function getHosts(): array
+    {
         $sWhere = '1=1 '
             . ($this->sProject ? "AND project='" . $this->sProject . "' " : "")
             . ($this->sPackage ? "AND package='" . $this->sPackage . "' " : "")
@@ -277,13 +301,16 @@ class valuestore {
     }
 
     /**
-     * get entries of the current place (project, phase and place can be
+     * Get entries of the current place (project, phase and place can be
      * set before)
+     * 
      * @see setProject()
+     * 
      * @param string  $sVariable  variable for filtering column "variable"
      * @return array
      */
-    public function getVar($sVariable=''){
+    public function getVar($sVariable = ''): array
+    {
         $sWhere = '1=1 '
             . ($this->sProject ? "AND project='" . $this->sProject . "' " : "")
             . ($this->sPackage ? "AND package='" . $this->sPackage . "' " : "")
@@ -297,12 +324,15 @@ class valuestore {
     }
 
     /**
-     * get versions of the current place (project, phase and place can be
+     * Get versions of the current place (project, phase and place can be
      * set before)
+     * 
      * @see setProject()
+     * 
      * @return array
      */
-    public function getVersion(){
+    public function getVersion(): array
+    {
         $aData = $this->getVar('version');
 
         // get json in subkey host -> data and store keys in host -> _data
@@ -316,23 +346,26 @@ class valuestore {
     }
 
     /**
-     * return currebntly set project, phase, place and host
+     * Get currently set project, phase, place and host
      * @return array
      */
-    public function whereiam(){
-        return array(
+    public function whereiam(): array
+    {
+        return [
             'project' => $this->sProject,
             'package' => $this->sPackage,
             'phase' => $this->sPhase,
             'place' => $this->sPlace,
             'host' => $this->sHost,
-        );
+        ];
     }
+
     /**
-     * return currebntly set project, phase, place and host
-     * @return type
+     * Get all values in valuestore as array
+     * @return array
      */
-    public function dumpdb(){
+    public function dumpdb(): array
+    {
         $sSql = "select * from `values`";
         return $this->_makeSelectQuery($sSql);
     }
@@ -343,47 +376,50 @@ class valuestore {
     // ----------------------------------------------------------------------
 
     /**
-     * init a "position" before getting or updating deleting a value
+     * Init a "position" before getting or updating deleting a value
      * 
      * @param string  $sProject  project id
      * @param string  $sPackage  package id
-     * @param string  $sPhase    phase (preview|stage|live)
-     * @param string  $sPlace    place (onhold|ready2install|deployed)
-     * @param string  $sHost     hostname (for place deployed)
-     * @return type string
+     * @param string  $sPhase    optional: phase (preview|stage|live)
+     * @param string  $sPlace    optional: place (onhold|ready2install|deployed)
+     * @param string  $sHost     optional: hostname (for place deployed)
+     * @return string
      */
-    public function setProject($sProject, $sPackage, $sPhase=false, $sPlace=false, $sHost=false){
+    public function setProject(string $sProject, string $sPackage, string $sPhase = '', string $sPlace = '', $sHost = ''): string
+    {
         $this->sProject = preg_replace('/[^a-z\-\_0-9]/', '', $sProject);
         $this->setPackage($sPackage, $sPhase, $sPlace, $sHost);
         return $this->sProject;
     }
 
     /**
-     * set a package (and more granular items)
+     * Set a package (and more granular items)
      * @see setProject()
      * 
      * @param string  $sPackage  package id
      * @param string  $sPhase    phase (preview|stage|live)
-     * @param string  $sPlace    place (onhold|ready2install|deployed)
-     * @param string  $sHost     hostname (for place deployed)
-     * @return type string
+     * @param string  $sPlace    optional: place (onhold|ready2install|deployed)
+     * @param string  $sHost     optional: hostname (for place deployed)
+     * @return string
      */
-    public function setPackage($sPackage, $sPhase, $sPlace=false, $sHost=false){
+    public function setPackage(string $sPackage, string $sPhase, string $sPlace = '', string $sHost = ''): string 
+    {
         $this->sPackage = preg_replace('/[^a-z\-\_0-9]/', '', $sPackage);
         $this->setPhase($sPhase, $sPlace, $sHost);
         return $this->sPackage;
     }
 
     /**
-     * set a phase (and more granular items)
+     * Set a phase (and more granular items)
      * @see setProject()
      * 
      * @param string  $sPhase    phase (preview|stage|live)
-     * @param string  $sPlace    place (onhold|ready2install|deployed)
-     * @param string  $sHost     hostname (for place deployed)
+     * @param string  $sPlace    optional: place (onhold|ready2install|deployed)
+     * @param string  $sHost     optional: hostname (for place deployed)
      * @return type string
      */
-    public function setPhase($sPhase, $sPlace=false, $sHost=false){
+    public function setPhase(string $sPhase, string $sPlace = '', string $sHost = ''): string 
+    {
         if (!$this->sProject && !$this->sPackage) {
             $this->_quit(__FUNCTION__, "ERROR: you need to set a project. Use the setProject() method to do so.");
             return false;
@@ -397,14 +433,17 @@ class valuestore {
     }
 
     /**
-     * set a place (and host)
+     * Set a place (and optional a host)
+     * It aborts if project and package are not set
+     * 
      * @see setProject()
      * 
      * @param string  $sPlace    place (onhold|ready2install|deployed)
-     * @param string  $sHost     hostname (for place deployed)
-     * @return type string
+     * @param string  $sHost     optional: hostname (for place deployed)
+     * @return bool
      */
-    public function setPlace($sPlace, $sHost=false){
+    public function setPlace($sPlace, string $sHost = ''): bool
+    {
         if ((!$this->sProject && !$this->sPackage)) {
             $this->_quit(__FUNCTION__, "ERROR: you need to set a project and phase. Use the setProject() method to do so.");
             return false;
@@ -417,17 +456,20 @@ class valuestore {
         }
         $this->sPlace = $sPlace;
         $this->setHost($sHost);
-        return $this->sPlace;
+        return true;
     }
 
     /**
-     * set a host for place "deployed"
+     * Set a host for place "deployed".
+     * It aborts if project and package are not set
+     * 
      * @see setProject()
      * 
      * @param string  $sHost     hostname
-     * @return type string
+     * @return bool
      */
-    public function setHost($sHost=false){
+    public function setHost($sHost = ''): bool
+    {
         if ((!$this->sProject && !$this->sPackage)) {
             $this->_quit(__FUNCTION__, "ERROR: you need to set a project, phase and place. Use the setProject() method to do so.");
             return false;
@@ -441,7 +483,7 @@ class valuestore {
         }
          */
         $this->sHost = preg_replace('/[^a-z\.\-0-9]/', '', $sHost);
-        return $this->sHost;
+        return true;
     }
 
     // ----------------------------------------------------------------------
@@ -449,12 +491,15 @@ class valuestore {
     // ----------------------------------------------------------------------
 
     /**
-     * cleanup value store
+     * Cleanup value store: delete entries older a given ttl value in seconds
+     * Afterwards a "vacuum" command will be started.
+     * 
      * @param integer  $iTtl  optional: max age in seconds of items to keep; 0 to delete all; default is 1 day
      * @return boolean
      */
-    public function cleanup($iTtl=false){
-        if ($iTtl===false){
+    public function cleanup(int $iTtl = -1): bool
+    {
+        if ($iTtl === -1) {
             $iTtl = $this->_iTTL;
         }
         $sTtlDate = date("Y-m-d H:i:s", date("U") - (int) $iTtl);
@@ -472,13 +517,18 @@ class valuestore {
     }
 
     /**
-     * delete values from value store. You need to call setProject() to set
+     * Delete values from value store. You need to call setProject() to set
      * project or package and optional phase, place, host. Then call this delete
      * method.
+     * It returns a PDO result object.
+     * It aborts if project and package are not set
+     * It returns false on database query error
+     * 
      * @param string $sVariable  optional: limit deletion to a given variable
-     * @return boolean
+     * @return boolean|object
      */
-    public function deleteValues($sVariable){
+    public function deleteValues($sVariable): bool|object
+    {
         if ((!$this->sProject && !$this->sPackage)) {
             $this->_quit(__FUNCTION__, "ERROR: you need to set a project, phase and place. use the setProject() method to do so.");
         }
@@ -497,10 +547,15 @@ class valuestore {
     }
 
     /**
-     * update a version
-     * @return boolean
+     * Update a version informatio in value store.
+     * It returns a PDO result object.
+     * It aborts if project and package are not set
+     * It returns false on database query error
+     * 
+     * @return boolean|object
      */
-    public function updateVar($sVarname,$sValue){
+    public function updateVar($sVarname, $sValue): bool|object
+    {
         if ((!$this->sProject && !$this->sPackage) || !$this->sPhase || !$this->sPlace) {
             $this->_quit(__FUNCTION__, "ERROR: you need to set a project, phase and place. use the setProject() method to do so.");
         }
@@ -521,10 +576,10 @@ class valuestore {
         ";
         return $this->_makeQuery(
             $sSql,
-                array(
+            [
                 'variable' => $sVarname,
                 'value' => $sValue,
-                )
+            ]
         );
     }
     /**
@@ -532,7 +587,8 @@ class valuestore {
      * @param type $sVersioninfos
      * @return boolean
      */
-    public function updateVersion($sVersioninfos){
+    public function updateVersion($sVersioninfos)
+    {
         return $this->updateVar('version', $sVersioninfos);
     }