added type declarations; update php docs

classes/cronlog-renderer.class.php

@@ -32,21 +32,25 @@ require_once 'cronlog.class.php';
  *
  * @license GNU GPL 3.0
  * @author Axel Hahn <axel.hahn@iml.unibe.ch>
+ * 
+ * 2024-09-20  <axel.hahn@unibe.ch>  added type declarations; update php docs
  */
-class cronlogrenderer extends cronlog{
+class cronlogrenderer extends cronlog
+{
 
     /**
      * minimal length for execution time of a job to be rendered in the timeline; value is in seconds
      * @var integer
      */
-    protected $_iMinTime4Timeline = 60;
+    protected int $_iMinTime4Timeline = 60;
 
     /**
-     * show date of last data and last access; used in rendering methods to display it on top
+     * Show date of last data and last access; used in rendering methods to display it on top
      * @param integer $iLast  unix timestamp of last log entry
      * @return string
      */
-    protected function _renderAccessAndAge($iLast){
+    protected function _renderAccessAndAge(int $iLast): string
+    {
         if (!$iLast) {
             return '';
         }
@@ -59,22 +63,24 @@ class cronlogrenderer extends cronlog{
     }
 
     /**
-     * get onclick value to filter a datatable
+     * Get onclick value to filter a datatable
      * @param  string  $sDatatable   id of table
      * @param  string  $sFiltertext  text to filter
      * @return string
      * 
      */
-    protected function _filterDatatable($sDatatable, $sFiltertext){
+    protected function _filterDatatable($sDatatable, $sFiltertext)
+    {
         return '$(\'#' . $sDatatable . '\').dataTable().fnFilter(\'' . $sFiltertext . '\'); return false;';
     }
 
     /**
-     * helper function to be used in methods that render datatable tables
-     * get javascript code to be added in init options and set language specifi texts
+     * Helper function to be used in methods that render datatable tables
+     * Get javascript code to be added in init options and set language specifi texts
      * @return string
      */
-    protected function _getDatatableLanguage(){
+    protected function _getDatatableLanguage(): string
+    {
         return $this->t("dt-USE")
             ? ', "oLanguage":{
                 "sProcessing":"' . $this->t("dt-sProcessing") . '",
@@ -97,12 +103,13 @@ class cronlogrenderer extends cronlog{
         ;
     }
     /**
-     * get html code for a table with events of executed cronjobs
+     * Get html code for a table with events of executed cronjobs
      * 
      * @param array  $aData   result of $this->getServerLogs()
      * @return string
      */
-    public function renderCronlogs($aData=false){
+    public function renderCronlogs(array $aData = []): string
+    {
         $sTaskId = __FUNCTION__ . '-' . $this->_sActiveServer;
         $sHtml = $this->_getCacheData($sTaskId);
         if ($sHtml) {
@@ -110,7 +117,7 @@ class cronlogrenderer extends cronlog{
         }
         $sHtml = '';
 
-        if(!$aData){
+        if (!count($aData)) {
             $aData = array_merge($this->getRunningJobs(), $this->getServersLastLog());
         }
         $sTblHead = '';
@@ -120,7 +127,7 @@ class cronlogrenderer extends cronlog{
         // Array ( [SCRIPTNAME] => apt-get update [SCRIPTTTL] => 1440 [SCRIPTSTARTTIME] => 2016-06-21 06:00:02, 1466481602 [SCRIPTLABEL] => apt-get [SCRIPTENDTIME] => 2016-06-21 06:00:49, 1466481649 [SCRIPTEXECTIME] => 47 s [SCRIPTRC] => 0 )
         foreach ($aData as $sDtakey => $aEntry) {
             if (!$sTblHead) {
-                foreach(array(
+                foreach ([
                     $this->t("col-starting-time"), 
                     $this->t("col-label"), 
                     $this->t("col-server"), 
@@ -129,15 +136,15 @@ class cronlogrenderer extends cronlog{
                     $this->t("col-rc"), 
                     $this->t("col-expired"), 
                     $this->t("col-status"), 
-                    ) as $sKey){
-                    $sTblHead.='<th>'.$sKey.'</th>';
+                ] as $sKey) {
+                    $sTblHead .= "<th>$sKey</th>";
                 }
             }
             // $sViewerUrl='viewer.php?host='.$aEntry['host'].'&job='.$aEntry['job'];
             // $sClass='message-'.($aEntry['SCRIPTRC']?'error':'ok');
-            $iLast=max(array($iLast, date("U", $aEntry['SCRIPTSTARTTIME'])));
+            $iLast = max([$iLast, date("U", $aEntry['SCRIPTSTARTTIME'])]);
 
-            $aErrors=array();
+            $aErrors = [];
             $iTtlUsed = max($aEntry['SCRIPTTTL'], $this->_iMinTtl);
             $iNextRun = $aEntry['SCRIPTSTARTTIME'] + ((int) $aEntry['SCRIPTTTL'] * 60);
             $iNextRunWarn = $aEntry['SCRIPTSTARTTIME'] + ((int) $iTtlUsed * 60);
@@ -298,13 +305,14 @@ class cronlogrenderer extends cronlog{
     }
 
     /**
-     * get html code for a table with events of executed cronjobs for ALL servers
+     * Get html code for a table with events of executed cronjobs for ALL servers
      * 
      * @param array  $aData   result of $this->getServerLogs()
      * @return string
      */
-    public function renderCronlogsOfAllServers(){
-        $aData=array();
+    public function renderCronlogsOfAllServers(): string
+    {
+        $aData = [];
         foreach (array_keys($this->getServers()) as $sServer) {
             $this->setServer($sServer);
             $aData = array_merge($aData, $this->getRunningJobs(), $this->getServersLastLog());
@@ -314,14 +322,16 @@ class cronlogrenderer extends cronlog{
     }
 
     /**
-     * get html code for a switcher of multiple instances
+     * Get html code for a switcher of multiple instances.
+     * It returns an empty string if there is no / only one instance
      * 
      * @param array  $aData   result of $oCL->getServerLogs()
      * @return string
      */
-    public function renderInstances(){
+    public function renderInstances(): string
+    {
         if (count($this->_aInstances) < 2) {
-            return false;
+            return '';
         }
         $sReturn = '';
         $sServer = isset($_SERVER['SERVER_NAME']) ? $_SERVER['SERVER_NAME'] : false;
@@ -337,12 +347,13 @@ class cronlogrenderer extends cronlog{
         return $sReturn;
     }
     /**
-     * get html code for a table with history of executed cronjobs
+     * Get html code for a table with history of executed cronjobs
      * 
      * @param array  $aData   result of $oCL->getServerLogs()
      * @return string
      */
-    public function renderJoblist($aData=false){
+    public function renderJoblist(array $aData = []): string
+    {
         $sTaskId = __FUNCTION__ . '-' . $this->_sActiveServer;
         $sHtml = $this->_getCacheData($sTaskId);
         if ($sHtml) {
@@ -361,7 +372,7 @@ class cronlogrenderer extends cronlog{
         // job=dok-kvm-instances:host=kalium:start=1538358001:end=1538358001:exectime=0:ttl=60:rc=0
         foreach ($aData as $aEntry) {
             if (!$sTblHead) {
-                foreach(array(
+                foreach ([
                     $this->t("col-starting-time"), 
                     $this->t("col-label"), 
                     $this->t("col-server"), 
@@ -369,12 +380,11 @@ class cronlogrenderer extends cronlog{
                     $this->t("col-ttl"), 
                     $this->t("col-rc"), 
                     $this->t("col-status"), 
-                ) as $sKey){
+                ] as $sKey) {
                     $sTblHead .= '<th>' . $sKey . '</th>';
                 }
             }
-            $iLast=max(array($iLast, date("U", $aEntry['start'])));
-            $sClass='message-'.($aEntry['rc']?'error':'ok');
+            $iLast = max([$iLast, date("U", $aEntry['start'])]);
 
             if ($aEntry['rc']) {
                 $iErrors++;
@@ -448,10 +458,12 @@ class cronlogrenderer extends cronlog{
     /**
      * get html code for a joblist of the selected server
      * it uses the filter for hidden joblog entries (aHidelogs in config)
+     * 
      * @return string
      */
-    public function renderJoblistOfAllServers(){
-        $aData=array();
+    public function renderJoblistOfAllServers(): string
+    {
+        $aData = [];
         foreach (array_keys($this->getServers()) as $sServer) {
             $this->setServer($sServer);
             $aData = array_merge($aData, $this->getServerJobHistory());
@@ -470,7 +482,8 @@ class cronlogrenderer extends cronlog{
      * @param array  $aData   result of $oCL->getServerLogs()
      * @return string
      */
-    public function renderJobGraph($aData=false){
+    public function renderJobGraph(array $aData = []): string
+    {
         $sTaskId = __FUNCTION__ . '-' . $this->_sActiveServer;
         $sHtml = $this->_getCacheData($sTaskId);
         if ($sHtml) {
@@ -482,19 +495,19 @@ class cronlogrenderer extends cronlog{
             $iGraphCounter = 0;
         }
         $iGraphCounter++;
-        if(!$aData){
+        if (!count($aData)) {
             $aData = $this->getServerJobHistory(false);
         }
         $sDivId = 'vis-timeline-' . $iGraphCounter;
 
-        $aDataset=array();
+        $aDataset = [];
         $iLast = false;
         $iEntry = 0;
         foreach ($aData as $aEntry) {
             if ($aEntry['exectime'] > $this->_iMinTime4Timeline) {
                 $iEntry++;
-                $iLast=max(array($iLast, date("U", $aEntry['start'])));
-                $aDataset[]=array(
+                $iLast = max([$iLast, date("U", $aEntry['start'])]);
+                $aDataset[] = [
                     'id' => $iEntry,
                     /*
                     'start'=>(int)date("U", $aEntry['start']),
@@ -520,7 +533,7 @@ class cronlogrenderer extends cronlog{
                         . '<br>'
                         . 'rc = ' . $aEntry['rc'] . '<br>'
                     ,
-                );
+                ];
                 // if($iEntry>=265){break;}
             }
         }
@@ -577,8 +590,13 @@ class cronlogrenderer extends cronlog{
         ;
     }
 
-    public function renderJobGraphOfAllServers(){
-        $aData=array();
+    /**
+     * Get html code for the job graph of all servers
+     * @return string
+     */
+    public function renderJobGraphOfAllServers(): string
+    {
+        $aData = [];
         foreach (array_keys($this->getServers()) as $sServer) {
             $this->setServer($sServer);
             $aData = array_merge($aData, $this->getServerJobHistory());
@@ -588,10 +606,12 @@ class cronlogrenderer extends cronlog{
     }
 
     /**
-     * used in config/page-replacements.php
      * generate an array of javascript lang texts
+     * used in config/page-replacements.php
+     * @return string
      */
-    public function renderJSLang(){
+    public function renderJSLang(): string
+    {
         $aReturn = [];
 
         foreach ($this->_aLang as $sKey => $sText) {
@@ -606,12 +626,13 @@ class cronlogrenderer extends cronlog{
     }
 
     /**
-    * show a single log file
+     * Get html code to show a single log file with syntax highligt an marking the reeturn code
      * 
      * @param string $sLogfile  logfile; [server]/[filename.log]
      * @return string
      */
-   public function renderLogfile($sLogfile){
+    public function renderLogfile(string $sLogfile): string
+    {
         $sHtml = ''
             . '<button style="position: fixed;" onclick="closeOverlay();" class="btn btn-default"><i class="fas fa-chevron-left"></i> ' . $this->t('back') . '</button><br><br>'
             . '<h3>' . $this->t('logfile') . ' ' . basename($sLogfile) . '</h3>'
@@ -628,7 +649,6 @@ class cronlogrenderer extends cronlog{
             return $sHtml . sprintf($this->t('error-logfile-not-found'), $sMyFile);
         }
 
-        
         if ($fileHandle = fopen($sMyFile, "r")) {
             $sHtml .= '<div style="float: left;"><pre>';
             while (($line = fgets($fileHandle)) !== false) {
@@ -665,14 +685,15 @@ class cronlogrenderer extends cronlog{
     }
 
     /**
-     * get html code for a select box with all servers
+     * Get html code for a select box with all servers
      * @return string
      */
-    public function renderServerlist($sSelectedItem=false){
+    public function renderServerlist(string $sSelectedItem = ''): string
+    {
         $sHtml = '';
         $iMaxItemsToShow = 30;
         $sHtml .= '<option value="ALL"'
-                .($sSelectedItem===false || $sSelectedItem==='ALL' ? ' selected="selected"' : '')
+            . ($sSelectedItem === '' || $sSelectedItem === 'ALL' ? ' selected="selected"' : '')
             . '>[' . $this->t('ALL') . ' (' . count($this->getServers()) . ')]</option>';
         foreach ($this->getServers() as $sServer => $aData) {
             $sHtml .= '<option value="' . $sServer . '"'
@@ -689,7 +710,7 @@ class cronlogrenderer extends cronlog{
             ><button onclick="$(\'#serverfiltertext\').val(\'\'); filterServers();">X</button><br><br>'
             */
             . '<select'
-                    . ' size="'.( min(array(count($this->getServers())+1 , $iMaxItemsToShow)) ).'"'
+            . ' size="' . (min([count($this->getServers()) + 1, $iMaxItemsToShow])) . '"'
             // . ' size="1"'
             . ' onchange="setServer(this.value); return false;"'
             . '>' . $sHtml . '</select>'

classes/cronlog.class.php

@@ -31,44 +31,46 @@
  *
  * @license GNU GPL 3.0
  * @author Axel Hahn <axel.hahn@iml.unibe.ch>
+ * 
+ * 2024-09-20  <axel.hahn@unibe.ch>  added type declarations; update php docs
  */
 
-class cronlog {
+class cronlog
+{
 
 
-    protected $_sDataDir = "__APPDIR__/data";
-    protected $_iTtlCache = 60; // in sec
+    protected string $_sDataDir = "__APPDIR__/data";
+    protected int $_iTtlCache = 60; // in sec
 
     /**
      * when show an error for expired jobs (latency to execute job and sync logs)
      * @var integer
      */
-    protected $_iExpiredJobsFailAfter = 60*30; // in sec
-    protected $_iMinTtl = 0; // in sec
-    protected $_aSkipJoblogs = array();
+    protected int $_iExpiredJobsFailAfter = 60 * 30; // in sec
+    protected int $_iMinTtl = 0; // in sec
+    protected array $_aSkipJoblogs = [];
 
-    protected $_aInstances = array();
+    protected array $_aInstances = [];
 
-    protected $_aServers = array();
-    protected $_sActiveServer = false;
+    protected array $_aServers = [];
+    protected string $_sActiveServer = '';
 
-    protected $_sFileFilter_serverjoblog = '*joblog*.done';
-    protected $_sFileFilter_joblog = '*.log';
-    protected $_sFileFilter_jobrunning = '*.log.running*';
+    protected string $_sFileFilter_serverjoblog = '*joblog*.done';
+    protected string $_sFileFilter_joblog = '*.log';
+    protected string $_sFileFilter_jobrunning = '*.log.running*';
 
-    protected $_sLang = ''; // language ... read from config file
-    protected $_aLang = []; // language data
+    protected string $_sLang = ''; // language ... read from config file
+    protected array $_aLang = []; // language data
 
     // ----------------------------------------------------------------------
     // MAIN
     // ----------------------------------------------------------------------
 
     /**
-     * init
-     * @return boolean
+     * Constructor
      */
-    public function __construct() {
-
+    public function __construct()
+    {
         // read config
         if (file_exists(__DIR__ . '/../config/inc_cronlog.php')) {
             $aCfgTemp = include(__DIR__ . '/../config/inc_cronlog.php');
@@ -91,8 +93,6 @@ class cronlog {
         $this->_sDataDir = str_replace('\\', '/', $this->_sDataDir);
 
         $this->getServers();
-                
-        return true;
     }
 
     // ----------------------------------------------------------------------
@@ -104,33 +104,37 @@ class cronlog {
      * chaching: get the full path of directory for caching
      * @return string
      */
-    protected function _getCacheDir(){
+    protected function _getCacheDir(): string
+    {
         return $this->_sDataDir . '/__cache';
     }
 
     /**
-     * caching: get full path of a caching item
-     * @param string $sTaskId
+     * Caching: get full path of a caching item
+     * @param string $sTaskId  Name of a task
      * @return string
      */
-    protected function _getCacheFile($sTaskId){
+    protected function _getCacheFile(string $sTaskId): string
+    {
         return $this->_getCacheDir() . '/' . $sTaskId;
     }
 
     /**
-     * read logs: get full path to a servers cronjob logdata
+     * Read logs: get full path to a servers cronjob logdata
      * @return string
      */
-    protected function _getServerlogDir(){
+    protected function _getServerlogDir(): string
+    {
         return $this->_sDataDir . '/' . $this->_sActiveServer;
     }
 
     /**
-     * caching: get cached data if they exist and aren't expired
-     * @param  string  $sTaskId
+     * Caching: get cached data if they exist and aren't expired
+     * @param  string  $sTaskId  Name of the task
      * @return mixed boolean|array
      */
-    protected function _getCacheData($sTaskId){
+    protected function _getCacheData(string $sTaskId): string
+    {
         // DISABLE CACHE return false;
         $sFile = $this->_getCacheFile($sTaskId);
         if (file_exists($sFile)) {
@@ -142,15 +146,16 @@ class cronlog {
                 unlink($sFile);
             }
         }
-        return false;
+        return '';
     }
     /**
-     * read logs: parse a single line in the joblog and return has with all key value items
+     * Read logs: parse a single line in the joblog and return has with all key value items
      * @param  string  $sLine  single line in the log
      * @return array
      */
-    protected function _parseJoblogLine($sLine){
-        $aReturn=array();
+    protected function _parseJoblogLine(string $sLine): array
+    {
+        $aReturn = [];
         // echo "DEBUG $sLine<br>";
         // job=dok-kvm-instances:host=kalium:start=1538358001:end=1538358001:exectime=0:ttl=60:rc=0
         $sLine = str_replace("\n", '', $sLine);
@@ -168,11 +173,13 @@ class cronlog {
     }
 
     /**
-     * read logs: parse the whole cronwrapper logfile and return a hash
+     * Read logs: parse the whole cronwrapper logfile and return a hash
      * @param  string  $sFile  filename with full path
+     * @return array
      */
-    protected function _parseLogfile($sFile) {
-        $aReturn=array(
+    protected function _parseLogfile(string $sFile): array
+    {
+        $aReturn = [
             'SCRIPTNAME' => false,
             'SCRIPTTTL' => false,
             'SCRIPTSTARTTIME' => false,
@@ -180,8 +187,8 @@ class cronlog {
             'SCRIPTENDTIME' => false,
             'SCRIPTEXECTIME' => false,
             'SCRIPTRC' => false,
-            // 'SCRIPTOUT'=>array(),
-        );
+            // 'SCRIPTOUT'=>[],
+        ];
         $fileHandle = fopen($sFile, "r");
         while (($line = fgets($fileHandle)) !== false) {
             // get key ... the part before "="
@@ -207,10 +214,11 @@ class cronlog {
     /**
      * caching: write new data; it returns the success of write operation as bool
      * @param  string  $sTaskId
-     * @param  [any]   $data      data to store; can be any serializable value
-     * @return boolean
+     * @param  mixed   $data      data to store; can be any serializable value
+     * @return boolean|integer
      */
-    protected function _writeCacheData($sTaskId, $data){
+    protected function _writeCacheData(string $sTaskId, mixed $data): bool|int
+    {
         $sFile = $this->_getCacheFile($sTaskId);
         // echo "WRITE cache $sFile<br>";
         return file_put_contents($sFile, serialize($data));
@@ -221,24 +229,26 @@ class cronlog {
     // ----------------------------------------------------------------------
 
     /**
-     * get currently selected server
+     * Get currently selected server
      * @return string
      */
-    public function getServer(){
+    public function getServer(): string
+    {
         return $this->_sActiveServer;
     }
 
     /**
-     * get array with existing servers in data dir
+     * Get array with existing servers in data dir
      * @return array
      */
-    public function getServers(){
+    public function getServers(): array
+    {
 
         if (is_array($this->_aServers) && count($this->_aServers)) {
             return $this->_aServers;
         }
 
-        $this->_aServers=array();
+        $this->_aServers = [];
         // echo "DEBUG DATADIR: " . $this->_sDataDir."<br>";
         if (!is_dir($this->_sDataDir)) {
             echo "WARNING: no data. Check sDatadir in the config and set it to an existing directory.<br>";
@@ -249,7 +259,7 @@ class cronlog {
             while (false !== ($entry = readdir($handle))) {
                 if ($entry != "." && $entry != ".." && $entry != "__cache" && is_dir($this->_sDataDir . '/' . $entry)) {
                     // echo "DEBUG $entry<br>\n";
-                    $this->_aServers[$entry]=array();
+                    $this->_aServers[$entry] = [];
                 }
             }
             closedir($handle);
@@ -259,12 +269,13 @@ class cronlog {
     }
 
     /**
-     * get logs from jobfilea of the current or given server
+     * Get logs from jobfilea of the current or given server
      * @param  boolean  $bUseSkip  hide jobs if their label matches the skip list; default: true
      * @return array
      */
-    public function getServerJobHistory($bUseSkip=true){
-        $aReturn=array();
+    public function getServerJobHistory(bool $bUseSkip = true): bool|array
+    {
+        $aReturn = [];
         $sTaskId = __FUNCTION__ . '-' . $this->_sActiveServer;
 
         $aData = $this->_getCacheData($sTaskId);
@@ -272,7 +283,7 @@ class cronlog {
             return $aData;
         }
 
-        $aData=array();
+        $aData = [];
 
         foreach (glob($this->_getServerlogDir() . '/' . $this->_sFileFilter_serverjoblog) as $sMyJobfile) {
             // echo "DEBUG: $sMyJobfile<br>";
@@ -293,12 +304,13 @@ class cronlog {
 
 
     /**
-     * get logs from jobfilea of the current or given server
+     * Get logs from jobfilea of the current or given server
      * @return array
      */
-    public function getServersLastLog(){
-        $aReturn=array();
-        $aData=array();
+    public function getServersLastLog(): array
+    {
+        $aReturn = [];
+        $aData = [];
         foreach (glob($this->_getServerlogDir() . '/' . $this->_sFileFilter_joblog) as $sMyJobfile) {
             // echo "DEBUG: log file $sMyJobfile<br>";
             $aData = $this->_parseLogfile($sMyJobfile);
@@ -309,13 +321,15 @@ class cronlog {
         rsort($aReturn);
         return $aReturn;
     }
+
     /**
      * get logs from jobfilea of the current or given server
      * @return array
      */
-    public function getRunningJobs(){
-        $aReturn=array();
-        $aData=array();
+    public function getRunningJobs(): array
+    {
+        $aReturn = [];
+        $aData = [];
         foreach (glob($this->_getServerlogDir() . '/' . $this->_sFileFilter_jobrunning) as $sMyJobfile) {
             // echo "DEBUG: log file $sMyJobfile<br>";
             $aData = $this->_parseLogfile($sMyJobfile);
@@ -328,26 +342,27 @@ class cronlog {
     }
 
     /**
-     * translate ... get a language specific text of a given key
+     * Translate: get a language specific text of a given key
      * @param  string  $id  id of language text
      * @return string
      */
-    public function t($id){
-        return ''
-            .(isset($this->_aLang[$id]) ? $this->_aLang[$id] : '['.$id.'] ???')
-            ;
+    public function t($id): string
+    {
+        return $this->_aLang[$id] ?? '[' . $id . '] ???';
     }
     // ----------------------------------------------------------------------
     // public setter
     // ----------------------------------------------------------------------
 
     /**
-     * set which server is selected
+     * Set which server is selected
      * The given server must exist as directory (that contains its logs)
+     * It returns false if the given server does not exist or has value 'ALL'
      * @param  string  $sServer  server name
-     * @return string
+     * @return bool|string
      */
-    public function setServer($sServer){
+    public function setServer(string $sServer): bool|string
+    {
         $this->_sActiveServer = false;
         if ($sServer === 'ALL') {
             return false;