vcs interface + git: added variable types; short array syntax

public_html/deployment/classes/vcs.git.class.php

@@ -9,74 +9,85 @@ require_once __DIR__.'/../../vendor/axelhahn/ahcache/cache.class.php';
  * 
  *
  * @author hahn
+ * 
+ * Axel: <axel.hahn@unibe.ch>
+ * (...)
+ * 2024-08-28  Axel   php8 only; added variable types; short array syntax
+
  */
-class vcs implements iVcs {
+class vcs implements iVcs
+{
     // class vcs {
 
     /**
      * configuration
      * @var array 
      */
-    private $_aCfg = array();
+    private array $_aCfg = [];
 
     /**
      * temp dir to fetch repo version and ommit message; its value will be
      * generated in set_config()
      * @var string
      */
-    private $_sTempDir = false;  // 
+    private string $_sTempDir = '';  // 
 
     /**
      * filename of ssh key file with complete path
      * @var string
      */
-    private $_sKeyfile = false;
+    private string $_sKeyfile = '';
 
     /**
      * filename of ssh wrapper script with complete path
      * @var string
      */
-    private $_sWrapper = false;
+    private string $_sWrapper = '';
 
     /**
      * flat array with remote branch names
      * @var array
      */
-    private $_aRemoteBranches = array();
+    private array $_aRemoteBranches = [];
 
     /**
      * name of the default remote branch to access
      * @var string
      */
-    private $_sCurrentBranch = "";
+    private string $_sCurrentBranch = '';
 
     /**
-     * constructor
+     * Constructor
      * @param array $aRepoConfig
      */
-    public function __construct($aRepoConfig = array()) {
+    public function __construct(array $aRepoConfig = [])
+    {
         $this->setConfig($aRepoConfig);
         $this->getRemoteBranches(); // to fill the cache
     }
 
     /**
-     * add a log messsage
+     * Add a log messsage
      * @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(string $sMessage, string $sLevel = "info"): bool
+    {
         global $oCLog;
         return $oCLog->add(basename(__FILE__) . " class " . __CLASS__ . " - " . $sMessage, $sLevel);
     }
 
     /**
-     * set a config and update internal (private) variables
+     * Set a config and update internal (private) variables
+     * 
      * @param array $aRepoConfig
      * @return boolean
      */
-    public function setConfig($aRepoConfig = array()) {
+    public function setConfig(array $aRepoConfig = []): bool
+    {
         // checks
         // foreach (array("type", "url") as $key) {
         foreach (array("type") as $key) {
@@ -99,15 +110,18 @@ class vcs implements iVcs {
         $this->_sWrapper = $this->_aCfg["appRootDir"] . "/shellscripts/gitsshwrapper.sh";
         $this->_setTempdir();
 
-        return $this->_aCfg = $aRepoConfig;
+        $this->_aCfg = $aRepoConfig;
+        return true;
     }
 
     /**
-     * set directory für current branch of a project below tempdir
-     * In it the branch will be initialized
-     * @return type
+     * Get directory für current branch of a project below tempdir
+     * If it does not exist yet it will be created and the repository will be initialized.
+     * 
+     * @return string
      */
-    private function _setTempdir() {
+    private function _setTempdir()
+    {
         $this->_sTempDir = $this->_aCfg["url"];
         $this->_sTempDir = preg_replace('/[\@\.\:\/]/', '_', $this->_sTempDir);
         $this->_sTempDir = $this->_aCfg["tmpDir"] . '/checkout_vcsgit_' . $this->_sTempDir . '/';
@@ -129,20 +143,23 @@ class vcs implements iVcs {
     }
 
     /**
-     * set the current branch
+     * Set the current branch
+     * 
      * @param string $sBranchname  name of the branch
+     * @return void
      */
-    public function setCurrentBranch($sBranchname) {
+    public function setCurrentBranch($sBranchname): void
+    {
         $this->_sCurrentBranch = $sBranchname;
         $this->_setTempdir();
-        return $this->_sCurrentBranch;
     }
 
     /**
      * helper: dump values
      * @return boolean
      */
-    public function dump() {
+    public function dump(): bool
+    {
         echo "<h3>Dump class " . __CLASS__ . "</h3>";
         echo "config array: <pre>" . print_r($this->_aCfg, true) . "</pre>";
         echo "temp dir to read revision: " . $this->_sTempDir . "<br>";
@@ -151,10 +168,14 @@ class vcs implements iVcs {
 
     /**
      * cleanup unneeded files and directories in a checked out directory
-     * and remove all vcs specific files and directories
+     * and remove all vcs specific files and directories.
+     * This method works on linux only
+     * 
+     * @param string $sWorkDir  path of the build directory to cleanup the git meta data from
      * @return bool
      */
-    public function cleanupWorkdir($sWorkDir) {
+    public function cleanupWorkdir(string $sWorkDir): bool
+    {
         if (!is_dir($sWorkDir)) {
             return false;
         }
@@ -164,11 +185,13 @@ class vcs implements iVcs {
     }
 
     /**
-     * get the current branch
+     * Get the current branch
+     * 
      * @param bool  $bReturnMasterIfEmpty  flag: if there is no current branch then detect a master branch
      * @return string
      */
-    public function getCurrentBranch($bReturnMasterIfEmpty=false) {
+    public function getCurrentBranch(bool $bReturnMasterIfEmpty = false): string
+    {
         if (!$this->_sCurrentBranch) {
             if ($bReturnMasterIfEmpty) {
                 $this->_sCurrentBranch = $this->_getMasterbranchname();
@@ -178,10 +201,12 @@ class vcs implements iVcs {
     }
 
     /**
-     * detect an existing master branch ... and return one of 'origin/main' | 'origin/master'
+     * Detect an existing master branch ... and return one of 'origin/main' | 'origin/master'
+     * 
      * @return string
      */
-    protected function _getMasterbranchname(){
+    protected function _getMasterbranchname(): string
+    {
         $sMasterBranch = '';
         $aMasternames = ['origin/main', 'origin/master'];
 
@@ -198,26 +223,32 @@ class vcs implements iVcs {
     }
 
     /**
-     * return the build type, i.e. git|svn|cvs|
+     * Get the build type, i.e. git|svn|cvs|
      * @return string
      */
-    public function getBuildType() {
-        return $this->_aCfg["type"];
+    public function getBuildType(): string
+    {
+        return $this->_aCfg["type"] ?? '';
     }
 
     /**
-     * get a nice name for a cache module based on repo url
-     * @return type
+     * Get a nice name for a cache module based on repo url
+     * 
+     * @return string
      */
-    private function _getNameOfCacheModule() {
+    private function _getNameOfCacheModule(): string
+    {
         return preg_replace('/([^0-9a-z])/i', "", $this->getUrl());
     }
 
     /**
-     * cleanup cache data for this project (revisions, list of branches+tags)
+     * Cleanup cache data for this project (revisions, list of branches+tags)
+     * 
+     * @param int $iAge  max age in sec; older items will be deleted
      * @return bool
      */
-    public function cleanupCache($iAge) {
+    public function cleanupCache(int $iAge): string
+    {
         $this->log(__FUNCTION__ . " start");
         $oCache = new AhCache($this->_getNameOfCacheModule());
         ob_start();
@@ -228,11 +259,13 @@ class vcs implements iVcs {
     }
 
     /**
-     * helper: cache hash with all branches
+     * helper: store hash with all branches in cache
      * It saves 1.5 sec for reading 300 branches
+     * 
      * @return boolean
      */
-    private function _cacheRemoteBranches() {
+    private function _cacheRemoteBranches(): bool
+    {
         $iTtl = 300;
         $oCache = new AhCache($this->_getNameOfCacheModule(), "RemoteBranches");
         // $this->log(__FUNCTION__." <pre>".print_r($this->_aRemoteBranches, 1)."</pre>");
@@ -241,15 +274,18 @@ class vcs implements iVcs {
     }
 
     /**
-     * read remote repository and get an array with names and revisions of 
+     * Read remote repository and get an array with names and revisions of 
      * all branches and tags
-     * pre branch you get an array element with the keys revision, name, type
+     * per branch you get an array element with the keys revision, name, type
+     * It returns false if there is no git url
+     * 
      * @param bool $bIgnoreCache  flag to overrde cache
      * @return array
      */
-    private function _fetchRemoteBranches($bIgnoreCache = false) {
+    private function _fetchRemoteBranches($bIgnoreCache = false): bool|array
+    {
         $this->log(__FUNCTION__ . "(bIgnoreCache = " . ($bIgnoreCache ? 'true' : 'false') . ") start");
-        $aReturn = array();
+        $aReturn = [];
 
         $sGitUrl = $this->getUrl();
         if (!$sGitUrl) {
@@ -349,11 +385,12 @@ class vcs implements iVcs {
     }
 
     /**
-     * get a flat array with names of all remote branches
+     * Get a flat array with names of all remote branches
      * @param  bool  $bIgnoreCache  flag: ignore caching; default: use cache
      * @return array
      */
-    public function getRemoteBranches($bIgnoreCache=false) {
+    public function getRemoteBranches(bool $bIgnoreCache = false): array
+    {
         $this->log(__FUNCTION__ . "($bIgnoreCache) start");
         if (!$this->_aRemoteBranches || $bIgnoreCache) {
             $this->log(__FUNCTION__ . "($bIgnoreCache) --> fetching fresh data");
@@ -365,12 +402,15 @@ class vcs implements iVcs {
     }
 
     /**
-     * get current revision and commit message from remote repository
+     * Get current revision and commit message from remote repository
      * @see $this::getRevision
+     * It returns false if no branch is set
+     * 
      * @param boolean  $bRefresh  optional: refresh data; default: use cache
-     * @return array
+     * @return bool|array
      */
-    public function getRepoRevision($bRefresh=false) {
+    public function getRepoRevision(bool $bRefresh = false): bool|array
+    {
         $this->log(__FUNCTION__ . "($bRefresh) start");
         if (!$this->_sCurrentBranch) {
             return false;
@@ -392,12 +432,15 @@ class vcs implements iVcs {
     }
 
     /**
-     * get a commit message of a given branch
+     * Get a commit message of a given branch.
+     * It reurns if no branch was found in meta infos
+     * 
      * @param string  $sBranch          name of a branch
      * @param string  $sVerifyRevision  optional: revision to verify if it is the newsest
      * @return string
      */
-    public function getCommitmessageByBranch($sBranch = false, $sVerifyRevision = false) {
+    public function getCommitmessageByBranch(string $sBranch = '', string $sVerifyRevision = ''): bool|string
+    {
         $this->log(__FUNCTION__ . "($sBranch, $sVerifyRevision) start");
         if (!$sBranch) {
             $sBranch = $this->_sCurrentBranch;
@@ -440,7 +483,7 @@ class vcs implements iVcs {
     }
 
     /**
-     * get current revision and commit message from an existing directory or a
+     * Get current revision and commit message from an existing directory or a
      * remote repository
      * the return will fill $this->_aData["phases"]["source"] in project class
      * (array keys are revision, message or error)
@@ -455,13 +498,15 @@ class vcs implements iVcs {
      *      array(
      *          "error" => $sErrormessage,
      *      );
+     * 
      * @param string  $sWorkDir  optional: local directory with initialized git repo
-     * @return array
+     * @return bool|array
      */
-    public function getRevision($sWorkDir = false) {
+    public function getRevision(string $sWorkDir = ''): bool|array
+    {
         $this->log(__FUNCTION__ . " start");
-        $aReturn = array();
-        $aOutput=array();
+        $aReturn = [];
+        $aOutput = [];
         $iRc = false;
         if (!$this->getUrl()) {
             return false;
@@ -521,7 +566,7 @@ class vcs implements iVcs {
 
         // parse revision
         $sRevision = false;
-        $aRev=array();
+        $aRev = [];
         if (preg_match('#commit\ (.*)#', $sLoginfo, $aRev)) {
             $sRevision = $aRev[1];
         }
@@ -555,10 +600,15 @@ class vcs implements iVcs {
     }
 
     /**
-     * get sources from vsc and check them out in given directory
-     * @return bool
+     * Get sources from vsc and check them out in given directory
+     * It returns false if the workdir was not found or the url for git repo is not set
+     * Otherwise it retunrs the output of git clone + git checkout
+     * 
+     * @param string $sWorkDir working dir where to check out source url
+     * @return bool|string
      */
-    public function getSources($sWorkDir) {
+    public function getSources(string $sWorkDir): bool|string
+    {
         $this->log(__FUNCTION__ . " start");
         if (!$sWorkDir || !is_dir($sWorkDir)) {
             return false;
@@ -586,19 +636,25 @@ class vcs implements iVcs {
     }
 
     /**
-     * return url to vcs sources
+     * Get url to vcs sources
+     * 
+     * @return string
      */
-    public function getUrl() {
+    public function getUrl(): string
+    {
         $this->log(__FUNCTION__ . " --> " . $this->_aCfg["url"]);
-        return $this->_aCfg["url"];
+        return $this->_aCfg["url"] ?? '';
     }
 
     /**
-     * return url to view sources in webrowser to generate an infolink
+     * Get url to view sources in webrowser to generate an infolink
+     * 
+     * @return string
      */
-    public function getWebGuiUrl() {
+    public function getWebGuiUrl(): string
+    {
         $this->log(__FUNCTION__ . " start");
-        return $this->_aCfg["webaccess"];
+        return $this->_aCfg["webaccess"] ?? '';
     }
 
 }

public_html/deployment/classes/vcs.interface.php

@@ -4,6 +4,10 @@
  * 
  * interface for a version control system
  * @author hahn
+ * 
+ * Axel: <axel.hahn@unibe.ch>
+ * (...)
+ * 2024-08-28  Axel   php8 only; added variable types; short array syntax
  */
 interface iVcs {
 
@@ -14,46 +18,54 @@ interface iVcs {
     /**
      * return url to vcs sources
      */
-    public function getUrl();
+    public function getUrl(): string;
     
     /**
      * return url to view sources in webrowser to generate an infolink
      */
-    public function getWebGuiUrl();
+    public function getWebGuiUrl(): string;
     
     /**
      * return the build type, i.e. git|svn|cvs|
      */
-    public function getBuildType();
+    public function getBuildType(): string;
     
     // ----------------------------------------------------------------------
     // actions
     // ----------------------------------------------------------------------
+
     /**
      * cleanup unneeded files and directories in a checked out directory
-     * and remove all vcs specific files and directories
+     * and remove all vcs specific files and directories.
+     * This method works on linux only
+     * 
+     * @param string $sWorkDir  path of the build directory to cleanup the vcs meta data from
      * @return bool
      */
-    public function cleanupWorkdir($sWorkDir);
+    public function cleanupWorkdir(string $sWorkDir): bool;
     
     /**
      * get current revision and commit message from remote repository
      * @param boolean  $bRefresh  optional: refresh data; default: use cache
      * @return array
      */
-    public function getRepoRevision($bRefresh=false);
+    public function getRepoRevision(bool $bRefresh=false);
     
     /**
      * get current revision and log message from given directory
-     * @return array
+     * @return bool|array
      */
-    public function getRevision($sWorkDir);
+    public function getRevision(string $sWorkDir = ''): bool|array;
 
     /**
-     * get sources from vsc and check them out in given directory
-     * @return bool
+     * Get sources from vsc and check them out in given directory
+     * It returns false if the workdir was not found or the url for git repo is not set
+     * Otherwise it retunrs the output of the checkout commands
+     * 
+     * @param string $sWorkDir working dir where to check out source url
+     * @return bool|string
      */
-    public function getSources($sWorkDir);
+    public function getSources(string $sWorkDir): bool|string;
     
 
 }