refactor: Update types and docstrings (DenverCoder1#410)

Author: DenverCoder1

src/card.php

@@ -56,13 +56,13 @@ function formatDate(string $dateString, string|null $format, string $locale): st
 /**
  * Check theme and color customization parameters to generate a theme mapping
  *
- * @param array<string, string> $params Request parameters
- * @return array<string, string> The chosen theme or default
+ * @param array<string,string> $params Request parameters
+ * @return array<string,string> The chosen theme or default
  */
 function getRequestedTheme(array $params): array
 {
     /**
-     * @var array<string, array<string, string>> $THEMES
+     * @var array<string,array<string,string>> $THEMES
      * List of theme names mapped to labeled colors
      */
     $THEMES = include "themes.php";
@@ -125,7 +125,7 @@ function getRequestedTheme(array $params): array
  *              than the word width.
  * @return string The given string wrapped at the specified length
  */
-function utf8WordWrap($string, $width = 75, $break = "\n", $cut_long_words = false)
+function utf8WordWrap(string $string, int $width = 75, string $break = "\n", bool $cut_long_words = false): string
 {
     // match anything 1 to $width chars long followed by whitespace or EOS
     $string = preg_replace("/(.{1,$width})(?:\s|$)/uS", "$1$break", $string);
@@ -145,7 +145,7 @@ function utf8WordWrap($string, $width = 75, $break = "\n", $cut_long_words = fal
  * @param string $string The input string
  * @return int The length of the string
  */
-function utf8Strlen($string)
+function utf8Strlen(string $string): int
 {
     return preg_match_all("/./us", $string, $matches);
 }
@@ -156,7 +156,6 @@ function utf8Strlen($string)
  * @param string $text Text to split
  * @param int $maxChars Maximum number of characters per line
  * @param int $line1Offset Offset for the first line
- *
  * @return string Original text if one line, or split text with <tspan> elements
  */
 function splitLines(string $text, int $maxChars, int $line1Offset): string
@@ -184,7 +183,6 @@ function splitLines(string $text, int $maxChars, int $line1Offset): string
  * Normalize a locale code
  *
  * @param string $localeCode Locale code
- *
  * @return string Normalized locale code
  */
 function normalizeLocaleCode(string $localeCode): string
@@ -210,10 +208,9 @@ function normalizeLocaleCode(string $localeCode): string
  * Get the translations for a locale code after normalizing it
  *
  * @param string $localeCode Locale code
- *
  * @return array Translations for the locale code
  */
-function getTranslations(string $localeCode)
+function getTranslations(string $localeCode): array
 {
     // normalize locale code
     $localeCode = normalizeLocaleCode($localeCode);
@@ -239,9 +236,8 @@ function getTranslations(string $localeCode)
 /**
  * Generate SVG output for a stats array
  *
- * @param array<string, mixed> $stats Streak stats
- * @param array<string, string>|NULL $params Request parameters
- *
+ * @param array<string,mixed> $stats Streak stats
+ * @param array<string,string>|NULL $params Request parameters
  * @return string The generated SVG Streak Stats card
  *
  * @throws InvalidArgumentException If a locale does not exist
@@ -424,8 +420,7 @@ function generateCard(array $stats, array $params = null): string
  * Generate SVG displaying an error message
  *
  * @param string $message The error message to display
- * @param array<string, string>|NULL $params Request parameters
- *
+ * @param array<string,string>|NULL $params Request parameters
  * @return string The generated SVG error card
  */
 function generateErrorCard(string $message, array $params = null): string
@@ -485,7 +480,6 @@ function generateErrorCard(string $message, array $params = null): string
  * Converts an SVG card to a PNG image
  *
  * @param string $svg The SVG for the card as a string
- *
  * @return string The generated PNG data
  */
 function convertSvgToPng(string $svg): string
@@ -516,7 +510,7 @@ function convertSvgToPng(string $svg): string
     if (empty($png)) {
         // `2>&1`: redirect stderr to stdout
         $error = shell_exec("$cmd 2>&1"); // skipcq: PHP-A1009
-        throw new Exception("Failed to convert SVG to PNG: {$error}", 500);
+        throw new InvalidArgumentException("Failed to convert SVG to PNG: {$error}", 500);
     }
 
     // return the generated png
@@ -527,7 +521,6 @@ function convertSvgToPng(string $svg): string
  * Return headers and response based on type
  *
  * @param string|array $output The stats (array) or error message (string) to display
- *
  * @return array The Content-Type header and the response body, and status code in case of an error
  */
 function generateOutput(string|array $output): array
@@ -573,6 +566,7 @@ function generateOutput(string|array $output): array
  *
  * @param string|array $output The Content-Type header and the response body
  * @param int $responseCode The HTTP response code to send
+ * @return void The function exits after sending the response
  */
 function renderOutput(string|array $output, int $responseCode = 200): void
 {

src/stats.php

@@ -7,10 +7,9 @@
  *
  * @param string $user GitHub username to get graphs for
  * @param int $year Year to get graph for
- *
  * @return string GraphQL query
  */
-function buildContributionGraphQuery(string $user, int $year)
+function buildContributionGraphQuery(string $user, int $year): string
 {
     $start = "$year-01-01T00:00:00Z";
     $end = "$year-12-31T23:59:59Z";
@@ -36,8 +35,7 @@ function buildContributionGraphQuery(string $user, int $year)
  *
  * @param string $user GitHub username to get graphs for
  * @param array<int> $years Years to get graphs for
- *
- * @return array<stdClass> List of GraphQL response objects
+ * @return array<int,stdClass> List of GraphQL response objects with years as keys
  */
 function executeContributionGraphRequests(string $user, array $years): array
 {
@@ -115,7 +113,6 @@ function executeContributionGraphRequests(string $user, array $years): array
  * Get all HTTP request responses for user's contributions
  *
  * @param string $user GitHub username to get graphs for
- *
  * @return array<stdClass> List of contribution graph response objects
  */
 function getContributionGraphs(string $user): array
@@ -138,7 +135,7 @@ function getContributionGraphs(string $user): array
  *
  * @return array<string> List of tokens
  */
-function getGitHubTokens()
+function getGitHubTokens(): array
 {
     // result is already calculated
     if (isset($GLOBALS["ALL_TOKENS"])) {
@@ -161,21 +158,28 @@ function getGitHubTokens()
  * Get a token from the token pool
  *
  * @return string GitHub token
+ *
+ * @throws AssertionError if no tokens are available
  */
-function getGitHubToken()
+function getGitHubToken(): string
 {
     $all_tokens = getGitHubTokens();
+    // if there is no available token, throw an error (this should never happen)
+    if (empty($all_tokens)) {
+        throw new AssertionError("There is no GitHub token available.", 500);
+    }
     return $all_tokens[array_rand($all_tokens)];
 }
 
 /**
  * Remove a token from the token pool
  *
  * @param string $token Token to remove
+ * @return void
  *
  * @throws AssertionError if no tokens are available after removing the token
  */
-function removeGitHubToken(string $token)
+function removeGitHubToken(string $token): void
 {
     $index = array_search($token, $GLOBALS["ALL_TOKENS"]);
     if ($index !== false) {
@@ -194,10 +198,9 @@ function removeGitHubToken(string $token)
  *
  * @param string $query GraphQL query
  * @param string $token GitHub token to use for the request
- *
  * @return CurlHandle The curl handle for the request
  */
-function getGraphQLCurlHandle(string $query, string $token)
+function getGraphQLCurlHandle(string $query, string $token): CurlHandle
 {
     $headers = [
         "Authorization: bearer $token",
@@ -221,9 +224,8 @@ function getGraphQLCurlHandle(string $query, string $token)
 /**
  * Get an array of all dates with the number of contributions
  *
- * @param array<stdClass> $contributionCalendars List of GraphQL response objects
- *
- * @return array<string, int> Y-M-D dates mapped to the number of contributions
+ * @param array<int,stdClass> $contributionCalendars List of GraphQL response objects by year
+ * @return array<string,int> Y-M-D dates mapped to the number of contributions
  */
 function getContributionDates(array $contributionGraphs): array
 {
@@ -253,8 +255,8 @@ function getContributionDates(array $contributionGraphs): array
 /**
  * Get a stats array with the contribution count, daily streak, and dates
  *
- * @param array<string, int> $contributions Y-M-D contribution dates with contribution counts
- * @return array<string, mixed> Streak stats
+ * @param array<string,int> $contributions Y-M-D contribution dates with contribution counts
+ * @return array<string,mixed> Streak stats
  */
 function getContributionStats(array $contributions): array
 {
@@ -331,8 +333,8 @@ function getPreviousSunday(string $date): string
 /**
  * Get a stats array with the contribution count, weekly streak, and dates
  *
- * @param array<string, int> $contributions Y-M-D contribution dates with contribution counts
- * @return array<string, mixed> Streak stats
+ * @param array<string,int> $contributions Y-M-D contribution dates with contribution counts
+ * @return array<string,mixed> Streak stats
  */
 function getWeeklyContributionStats(array $contributions): array
 {