From da5bb77dc1bdedf88dae99715bf58a82d751f3ea Mon Sep 17 00:00:00 2001 From: supahgreg Date: Sat, 1 Nov 2025 04:12:20 +0000 Subject: [PATCH] Describe array shapes in some more places. --- classes/Config.php | 51 ++++++++++++++++++++---------------------- classes/Counters.php | 10 ++++----- classes/Feeds.php | 46 ++++++++++++++++++++++++------------- classes/Labels.php | 4 ++-- classes/Mailer.php | 2 +- classes/PluginHost.php | 2 +- classes/Pref_Feeds.php | 4 ++-- classes/Prefs.php | 4 ++-- classes/RSSUtils.php | 4 ++-- 9 files changed, 70 insertions(+), 57 deletions(-) diff --git a/classes/Config.php b/classes/Config.php index 5e47be425..6adaecf27 100644 --- a/classes/Config.php +++ b/classes/Config.php @@ -295,8 +295,8 @@ class Config { /** @var array> */ private array $params = []; - /** @var array */ - private array $version = []; + /** @var array{branch: string, timestamp: int, version: string, commit: string, status: int}|array{version: string, status: int} */ + private array $version; private Db_Migrations $migrations; @@ -348,49 +348,46 @@ class Config { } /** - * @return array|string + * @return array{branch: string, timestamp: int, version: string, commit: string, status: int}|array{version: string}|string */ private function _get_version(bool $as_string = true): array|string { $root_dir = self::get_self_dir(); if (empty($this->version)) { - $this->version["status"] = -1; - - if (getenv("CI_COMMIT_SHORT_SHA") && getenv("CI_COMMIT_TIMESTAMP")) { - - $this->version["branch"] = getenv("CI_COMMIT_BRANCH"); - $this->version["timestamp"] = strtotime(getenv("CI_COMMIT_TIMESTAMP")); - $this->version["version"] = sprintf("%s-%s", date("y.m", $this->version["timestamp"]), getenv("CI_COMMIT_SHORT_SHA")); - $this->version["commit"] = getenv("CI_COMMIT_SHORT_SHA"); - $this->version["status"] = 0; - - } else if (PHP_OS === "Darwin") { - $this->version["version"] = "UNKNOWN (Unsupported, Darwin)"; + if (getenv('CI_COMMIT_SHORT_SHA') && getenv('CI_COMMIT_TIMESTAMP')) { + $this->version = [ + 'branch' => getenv('CI_COMMIT_BRANCH'), + 'timestamp' => strtotime(getenv('CI_COMMIT_TIMESTAMP')), + 'version' => sprintf('%s-%s', date('y.m', $this->version['timestamp']), getenv('CI_COMMIT_SHORT_SHA')), + 'commit' => getenv('CI_COMMIT_SHORT_SHA'), + 'status' => 0, + ]; + } else if (PHP_OS === 'Darwin') { + $this->version = ['version' => 'UNKNOWN (Unsupported, Darwin)', 'status' => -1]; } else if (file_exists("$root_dir/version_static.txt")) { - $this->version["version"] = trim(file_get_contents("$root_dir/version_static.txt")) . " (Unsupported)"; + $this->version = ['version' => trim(file_get_contents("$root_dir/version_static.txt")) . ' (Unsupported)', 'status' => -1]; } else if (ini_get("open_basedir")) { - $this->version["version"] = "UNKNOWN (Unsupported, open_basedir)"; + $this->version = ['version' => 'UNKNOWN (Unsupported, open_basedir)', 'status' => -1]; } else if (is_dir("$root_dir/.git")) { $this->version = self::get_version_from_git($root_dir); - if ($this->version["status"] != 0) { - user_error("Unable to determine version: " . $this->version["version"], E_USER_WARNING); + if ($this->version['status'] != 0) { + user_error('Unable to determine version: ' . $this->version['version'], E_USER_WARNING); - $this->version["version"] = "UNKNOWN (Unsupported, Git error)"; - } else if (!getenv("SCRIPT_ROOT") || !file_exists("/.dockerenv")) { - $this->version["version"] .= " (Unsupported)"; + $this->version = ['version' => 'UNKNOWN (Unsupported, Git error)', 'status' => -1]; + } else if (!getenv('SCRIPT_ROOT') || !file_exists('/.dockerenv')) { + $this->version['version'] .= ' (Unsupported)'; } - } else { - $this->version["version"] = "UNKNOWN (Unsupported)"; + $this->version = ['version' => 'UNKNOWN (Unsupported)', 'status' => -1]; } } - return $as_string ? $this->version["version"] : $this->version; + return $as_string ? $this->version['version'] : $this->version; } /** - * @return array + * @return array{status: int, version: string, branch: string, commit: string, timestamp: string} */ static function get_version_from_git(string $dir): array { $descriptorspec = [ @@ -403,7 +400,7 @@ class Config { "version" => "", "branch" => "", "commit" => "", - "timestamp" => 0, + "timestamp" => "0", ]; $proc = proc_open('git --no-pager log --pretty="version-%ct-%h" --abbrev=8 -n1 HEAD', diff --git a/classes/Counters.php b/classes/Counters.php index d7e236037..602e8eed8 100644 --- a/classes/Counters.php +++ b/classes/Counters.php @@ -55,7 +55,7 @@ class Counters { /** * @param array|null $cat_ids - * @return array> + * @return array */ private static function get_cats(?array $cat_ids = null): array { $ret = []; @@ -150,7 +150,7 @@ class Counters { /** * @param array|null $feed_ids - * @return array> + * @return array */ private static function get_feeds(?array $feed_ids = null): array { $ret = []; @@ -191,7 +191,7 @@ class Counters { } /** - * @return array> + * @return array */ private static function get_global(): array { $ret = [ @@ -214,7 +214,7 @@ class Counters { } /** - * @return array> + * @return array */ private static function get_virt(): array { $ret = []; @@ -266,7 +266,7 @@ class Counters { /** * @param array|null $label_ids - * @return array> + * @return array */ static function get_labels(?array $label_ids = null): array { $ret = []; diff --git a/classes/Feeds.php b/classes/Feeds.php index 0d10c7902..eafa85d78 100644 --- a/classes/Feeds.php +++ b/classes/Feeds.php @@ -53,7 +53,13 @@ class Feeds extends Handler_Protected { } /** - * @return array{0: array, 1: int, 2: int, 3: bool, 4: array} $topmost_article_ids, $headlines_count, $feed, $disable_cache, $reply + * @return array{ + * 0: array, + * 1: int, + * 2: int, + * 3: bool, + * 4: array{content: string|array, first_id: int, is_vfeed: bool, search_query: array{0: string, 1: string}, vfeed_group_enabled: bool, toolbar: array} + * } $topmost_article_ids, $headlines_count, $feed, $disable_cache, $reply */ private function _format_headlines_list(int|string $feed, string $method, string $view_mode, int $limit, bool $cat_view, int $offset, string $override_order, bool $include_children, ?int $check_first_id = null, @@ -536,19 +542,19 @@ class Feeds extends Handler_Protected { * @return array */ private function _generate_error_feed(string $error): array { - $reply = []; - - $reply['headlines']['id'] = Feeds::FEED_ERROR; - $reply['headlines']['is_cat'] = false; - - $reply['headlines']['toolbar'] = ''; - $reply['headlines']['content'] = "
". $error . "
"; - - $reply['headlines-info'] = ["count" => 0, - "unread" => 0, - "disable_cache" => true]; - - return $reply; + return [ + 'headlines' => [ + 'id' => Feeds::FEED_ERROR, + 'is_cat' => false, + 'toolbar' => '', + 'content' => '
'. $error . '
', + ], + 'headlines-info' => [ + 'count' => 0, + 'unread' => 0, + 'disable_cache' => true, + ] + ]; } function subscribeToFeed(): void { @@ -1379,7 +1385,17 @@ class Feeds extends Handler_Protected { /** * @param array $params - * @return array $result, $feed_title, $feed_site_url, $last_error, $last_updated, $highlight_words, $first_id, $is_vfeed, $query_error_override + * @return array{ + * 0: PDOStatement|false|-1, + * 1: string, + * 2: string, + * 3: string, + * 4: string, + * 5: array, + * 6: int, + * 7: bool, + * 8: string + * } $result, $feed_title, $feed_site_url, $last_error, $last_updated, $highlight_words, $first_id, $is_vfeed, $query_error_override */ static function _get_headlines($params): array { $pdo = Db::pdo(); diff --git a/classes/Labels.php b/classes/Labels.php index d75e0396a..a6031f657 100644 --- a/classes/Labels.php +++ b/classes/Labels.php @@ -38,7 +38,7 @@ class Labels } /** - * @return array> + * @return array */ static function get_as_hash(int $owner_uid): array { $rv = []; @@ -52,7 +52,7 @@ class Labels } /** - * @return array> An array of label detail arrays + * @return array An array of label detail arrays */ static function get_all(int $owner_uid) { $rv = []; diff --git a/classes/Mailer.php b/classes/Mailer.php index b9bc40a07..76ca9f55a 100644 --- a/classes/Mailer.php +++ b/classes/Mailer.php @@ -3,7 +3,7 @@ class Mailer { private string $last_error = ""; /** - * @param array $params + * @param array{to_name?: string, to_address: string, subject: string, message: string, from_name?: string, from_address?: string, headers?: array} $params * @return bool|int bool if the default mail function handled the request, otherwise an int as described in Mailer#mail() */ function mail(array $params): bool|int { diff --git a/classes/PluginHost.php b/classes/PluginHost.php index ee511dd92..00c494c1c 100644 --- a/classes/PluginHost.php +++ b/classes/PluginHost.php @@ -8,7 +8,7 @@ class PluginHost { */ private ?PDO $pdo_data = null; - /** @var array>> hook types -> priority levels -> Plugins */ + /** @var array>> hook types -> priority levels -> Plugins */ private array $hooks = []; /** @var array */ diff --git a/classes/Pref_Feeds.php b/classes/Pref_Feeds.php index ada11be1c..ed19bf256 100644 --- a/classes/Pref_Feeds.php +++ b/classes/Pref_Feeds.php @@ -112,7 +112,7 @@ class Pref_Feeds extends Handler_Protected { } /** - * @return array|string> + * @return array{identifier: 'id', label: 'name', items: array{id: 'root', name: string, items: array, param: string, type: 'category'}|array} */ function _makefeedtree(): array { $profile = $_SESSION['profile'] ?? null; @@ -126,7 +126,7 @@ class Pref_Feeds extends Handler_Protected { $root['id'] = 'root'; $root['name'] = __('Feeds'); $root['items'] = []; - $root['param'] = 0; + $root['param'] = '0'; $root['type'] = 'category'; $enable_cats = Prefs::get(Prefs::ENABLE_FEED_CATS, $_SESSION['uid'], $profile); diff --git a/classes/Prefs.php b/classes/Prefs.php index 9ae703f48..b9a03c9b7 100644 --- a/classes/Prefs.php +++ b/classes/Prefs.php @@ -186,14 +186,14 @@ class Prefs { } /** - * @return array> + * @return array */ static function get_all(int $owner_uid, ?int $profile_id = null): array { return self::get_instance()->_get_all($owner_uid, $profile_id); } /** - * @return array> + * @return array */ private function _get_all(int $owner_uid, ?int $profile_id = null): array { $rv = []; diff --git a/classes/RSSUtils.php b/classes/RSSUtils.php index 0d3118a18..e9d906b9a 100644 --- a/classes/RSSUtils.php +++ b/classes/RSSUtils.php @@ -1981,7 +1981,7 @@ class RSSUtils { } /** - * @return array> An array of srcset subitem arrays with keys "url" and "size" + * @return array An array of srcset subitem arrays */ static function decode_srcset(string $srcset): array { $matches = []; @@ -1995,7 +1995,7 @@ class RSSUtils { } /** - * @param array> $matches An array of srcset subitem arrays with keys "url" and "size" + * @param array $matches An array of srcset subitem arrays */ static function encode_srcset(array $matches): string { return implode(',', array_map(fn(array $m) => trim($m['url']) . ' ' . trim($m['size']), $matches));