From c9768fef8b73e8a038444640ab0b64e6782edf6b Mon Sep 17 00:00:00 2001 From: Mathieu Trossevin Date: Tue, 31 Oct 2023 10:23:32 +0100 Subject: [PATCH 1/5] Fix some of the docblocks --- inc/common.php | 6 ++++++ lib/letsencrypt.php | 20 +++++++++++++------- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/inc/common.php b/inc/common.php index 129ae90..b730a63 100644 --- a/inc/common.php +++ b/inc/common.php @@ -48,6 +48,12 @@ function is_superadmin() { } } +/** + * execute a command with sudo + * @param string $cmd The command that will be executed. + * @param ?array $output see $output parameter of exec(). + * @param ?int $return_var see $result_code parameter of exec(). + */ function sudoexec($cmd, &$output, &$return_var) { global $conf; diff --git a/lib/letsencrypt.php b/lib/letsencrypt.php index 8c0d2d4..83f1010 100644 --- a/lib/letsencrypt.php +++ b/lib/letsencrypt.php @@ -30,7 +30,7 @@ class LetsEncrypt /** * generate a CSR * @param string $vhost - * @param Array $domains + * @param array $domains * @return boolean */ public function makeCsr($vhost, $domains) @@ -69,7 +69,7 @@ class LetsEncrypt /** * perform a cURL call on the remote resource * the cURL call follows redirections - * @param Array $domains list of domains + * @param array $domains list of domains * @return boolean */ public function checkRemoteResourceAvailability($domain) @@ -108,8 +108,8 @@ class LetsEncrypt /** * Query the corresponding IP for each domain - * @param Array $domains list of HTTP checked domains - * @return Array $valid_dns_domains list of valid domains + * @param array $domains list of HTTP checked domains + * @return array $valid_dns_domains list of valid domains */ public function checkDNSValidity($domains) { @@ -151,7 +151,7 @@ class LetsEncrypt /** * Retrieve the SSL certificate from the URL * @param string $domain - * @return Array|false $cont list of parameters of the certificate, or false + * @return array|false $cont list of parameters of the certificate, or false */ public function getCertificate($domain) { @@ -164,8 +164,8 @@ class LetsEncrypt /** * Parse the certificat arguments and extract data - * @param Array $certificateParameters certificat arguments - * @return Array $infosCert contains only the issuer, domains and expiration date + * @param array $certificateParameters certificat arguments + * @return array $infosCert contains only the issuer, domains and expiration date */ public function parseCertificate($certificateParameters) { @@ -204,6 +204,12 @@ class LetsEncrypt return ($timestampCertValidUntil > $currentDate) ? true : false; } + /** + * Check if the requested domain is included in the certificate + * @param string $domainRequested + * @param array|string $san + * @return bool + */ public function isDomainIncludedInCert($domainRequested, $san) { $san = preg_replace('/DNS:| DNS:/', '', $san); -- 2.39.2 From a691259ae68c93df72390ca8643ff7f16c00ae5e Mon Sep 17 00:00:00 2001 From: Mathieu Trossevin Date: Thu, 16 Nov 2023 09:52:42 +0100 Subject: [PATCH 2/5] Add some of the missing doc-comments --- evolibs/Form.php | 6 ++++++ inc/common.php | 52 ++++++++++++++++++++++++++++++++++----------- lib/letsencrypt.php | 16 ++++++++------ 3 files changed, 55 insertions(+), 19 deletions(-) diff --git a/evolibs/Form.php b/evolibs/Form.php index 74aea53..611caf6 100644 --- a/evolibs/Form.php +++ b/evolibs/Form.php @@ -257,11 +257,17 @@ class FormPage { class FormField { protected $value = null; protected $error = null; + /** @var string|null $label */ protected $label = null; + /** @var string|null $name */ protected $name = null; + /** @var string|null $css_class */ protected $css_class = null; + /** @var bool|null $read_only */ protected $read_only = null; + /** @var bool|null $disabled True if the field is supposed to be disabled */ protected $disabled = null; + /** @var array|null $storage */ private $storage = NULL; protected function __construct($label) { diff --git a/inc/common.php b/inc/common.php index b730a63..8bb1ece 100644 --- a/inc/common.php +++ b/inc/common.php @@ -16,6 +16,12 @@ /** * Functions */ + + /** + * Check if a file exists and is readable and `die()` if it doesnt. + * @param string $file + * @return void + */ function test_exist($file) { if(!file_exists($file)) { die("Erreur, vous devez mettre en place le fichier $file !\n"); @@ -25,11 +31,20 @@ function test_exist($file) { } } +/** + * Redirect the page to $path on the same HOST + * @param string $path + * @return never + */ function http_redirect($path) { header('Location: '.$_SERVER['REQUEST_SCHEME'].'://'.$_SERVER['HTTP_HOST'].$path); exit(0); } +/** + * @param string $filename + * @return string + */ function findexts ($filename) { $filename = strtolower($filename) ; @@ -39,20 +54,25 @@ function findexts ($filename) return $exts; } +/** + * Check if the user is a superadmin + * @return bool + */ function is_superadmin() { global $conf; if(!empty($_SESSION['user']) && in_array($_SESSION['user'], $conf['superadmin'])) { - return 1; + return true; } else { - return 0; + return false; } } /** - * execute a command with sudo + * Execute a command with sudo * @param string $cmd The command that will be executed. - * @param ?array $output see $output parameter of exec(). - * @param ?int $return_var see $result_code parameter of exec(). + * @param array $output output of the command. + * @param int $return_var return status of the command. + * @return void */ function sudoexec($cmd, &$output, &$return_var) { global $conf; @@ -66,7 +86,8 @@ function sudoexec($cmd, &$output, &$return_var) { } /** - * Return TRUE is Evoadmin is installed in cluster mode. + * Check if Evoadmin is installed in cluster mode + * @return boolean */ function is_cluster_mode() { global $conf; @@ -74,7 +95,8 @@ function is_cluster_mode() { } /** - * Return TRUE is Evoadmin is installed in multi-cluster mode. + * Check if Evoadmin is installed in multi-cluster mode. + * @return boolean */ function is_mcluster_mode() { global $conf; @@ -83,6 +105,8 @@ function is_mcluster_mode() { /** * Load config file for the specified cluster. + * @param string $cluster + * @return void */ function load_config_cluster($cluster) { global $conf; @@ -93,8 +117,7 @@ function load_config_cluster($cluster) { } /** - * Return wether or not this evoadmin install is a multi PHP install - * + * Check if evoadmin install is a multi PHP install * @return boolean - True when it's a multi PHP system */ function is_multiphp() { @@ -103,9 +126,9 @@ function is_multiphp() { } /** - * Webadd - * - * @return boolean - True when it's a multi PHP system + * Webadd + * @param string $command webadd command to run + * @return array output from the command */ function run_webadd_cmd($command) { global $conf; @@ -133,6 +156,11 @@ if (!(ini_set('include_path', ini_get('include_path')))) { require_once 'PEAR.php'; require_once 'Log.php'; + /** + * (simply there to silence a warning) + * @var array $oriconf + * @var array $localconf + */ // config files // (here because need Log PEAR lib) test_exist('../conf/connect.php'); diff --git a/lib/letsencrypt.php b/lib/letsencrypt.php index 83f1010..b581657 100644 --- a/lib/letsencrypt.php +++ b/lib/letsencrypt.php @@ -10,7 +10,8 @@ class LetsEncrypt const HTTP_CHALLENGE_URL = '/.well-known/acme-challenge/testfile'; /** - * create the file used to test the HTTP challenge + * Create the file used to test the HTTP challenge + * @return void */ private function createFileHttpChallenge() { @@ -19,7 +20,8 @@ class LetsEncrypt } /** - * delete the file used to test the HTTP challenge + * Delete the file used to test the HTTP challenge + * @return void */ private function deleteFileHttpChallenge() { @@ -28,9 +30,9 @@ class LetsEncrypt } /** - * generate a CSR + * Generate a CSR * @param string $vhost - * @param array $domains + * @param string[] $domains * @return boolean */ public function makeCsr($vhost, $domains) @@ -108,7 +110,7 @@ class LetsEncrypt /** * Query the corresponding IP for each domain - * @param array $domains list of HTTP checked domains + * @param string[] $domains list of HTTP checked domains * @return array $valid_dns_domains list of valid domains */ public function checkDNSValidity($domains) @@ -133,7 +135,7 @@ class LetsEncrypt } /** - * check the presence of make-csr and evoacme binaries + * Check the presence of make-csr and evoacme binaries * @return boolean */ public function isEvoacmeInstalled() @@ -207,7 +209,7 @@ class LetsEncrypt /** * Check if the requested domain is included in the certificate * @param string $domainRequested - * @param array|string $san + * @param string[]|string $san * @return bool */ public function isDomainIncludedInCert($domainRequested, $san) -- 2.39.2 From 10ceade38cb0cc43612b5c291015a110ade81fa2 Mon Sep 17 00:00:00 2001 From: Mathieu Trossevin Date: Thu, 16 Nov 2023 10:51:53 +0100 Subject: [PATCH 3/5] Add remaining missing PHPDoc comments (outside of lib/) --- inc/accounts.php | 12 ++++++++++++ inc/ftpadmin.php | 10 +++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/inc/accounts.php b/inc/accounts.php index 95980ab..080ec18 100644 --- a/inc/accounts.php +++ b/inc/accounts.php @@ -31,6 +31,12 @@ else { $cache = $conf['cache']; } +/** + * Create a new domain (local only) + * @param FormPage $form + * @param string $admin_mail + * @return array + */ function web_add($form, $admin_mail) { global $conf; @@ -84,6 +90,12 @@ function web_add($form, $admin_mail) { return array($exec_cmd, $exec_return, $exec_output); } +/** + * Create a new domain (cluster only) + * @param FormPage $form + * @param string $admin_mail + * @return array + */ function web_add_cluster($form, $admin_mail) { global $cache; global $conf; diff --git a/inc/ftpadmin.php b/inc/ftpadmin.php index 98d8884..983dc00 100644 --- a/inc/ftpadmin.php +++ b/inc/ftpadmin.php @@ -229,6 +229,12 @@ if ($action=="add") { $_SESSION['error']=null; $_SESSION['form']=null; +/** + * Format Byte representation in human readable format (power of 1024) + * @param float|int $bytes + * @param int|null $precision + * @return string Human formatted amount of bytes + */ function formatBytes($bytes, $precision = 2) { $bytes *= 1024; $units = array('o', 'Ko', 'Mo', 'Go', 'To'); @@ -242,7 +248,9 @@ function formatBytes($bytes, $precision = 2) { return round($bytes, $precision) . ' ' . $units[$pow]; } - +/** + * @return string[] + */ function get_owner_list() { $owner_list = array(); -- 2.39.2 From 659575960d6b1225c64cc2afa2005c6fc48545c1 Mon Sep 17 00:00:00 2001 From: Mathieu Trossevin Date: Thu, 16 Nov 2023 10:53:21 +0100 Subject: [PATCH 4/5] fix(lib/bdd.php) Fix PHPDoc @desc doesn't exists in PHPDoc causing VSCode to ignore the description lines. (Also it is superfluous anyway.) --- lib/bdd.php | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/lib/bdd.php b/lib/bdd.php index 6784650..1129a78 100644 --- a/lib/bdd.php +++ b/lib/bdd.php @@ -1,7 +1,7 @@ "$name", * 'domain' => "$domain", @@ -236,7 +236,7 @@ class bdd { /** - * @desc Add an alias to the table Serveralias + * Add an alias to the table Serveralias * @param array { * 'domain' => "$domain", * 'alias' => "$alias", @@ -264,7 +264,7 @@ class bdd { } /** - * @desc Del an alias from the table Serveralias + * Delete an alias from the table Serveralias * @param array { * 'domain' => "$domain", * 'alias' => "$alias", @@ -289,7 +289,7 @@ class bdd { } /** - * @desc Get the server id of a server_name + * Get the server id of a server_name * @param string $server_name Name of the server * @return int 0 if server_name doesn't exist, * id else @@ -312,7 +312,7 @@ class bdd { } /** - * @desc Check if server_name entry exists on table Servers + * Check if server_name entry exists on table Servers * @param string $server_name Name of the server * @return int 1 if it exists, * 0 else @@ -324,7 +324,7 @@ class bdd { /** - * @desc Add an server to the table Servers + * Add an server to the table Servers * @param array { * 'name' => "$name", * } @@ -353,7 +353,7 @@ class bdd { } /** - * @desc Add a role to the table Roles + * Add a role to the table Roles * @param string $account_name * string $server_name * string $role master or slave @@ -397,7 +397,7 @@ class bdd { /** - * @desc List domains by server's role + * List domains by server's role * @param none * @return list of array * example : Array ( -- 2.39.2 From e66cca7e2ef7f43408fa4c1cf4c45e3c0a5f3fba Mon Sep 17 00:00:00 2001 From: Mathieu Trossevin Date: Thu, 16 Nov 2023 10:59:27 +0100 Subject: [PATCH 5/5] Add missing PHPDoc --- lib/domain.php | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lib/domain.php b/lib/domain.php index 1e6dea7..5c189f3 100644 --- a/lib/domain.php +++ b/lib/domain.php @@ -1,5 +1,13 @@