Skip to content

Commit

Permalink
refactor: Update types and docstrings (#410)
Browse files Browse the repository at this point in the history
  • Loading branch information
@DenverCoder1
DenverCoder1 authored Jan 6, 2023
1 parent eb2a4c3 commit c24b1af
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 34 deletions.
28 changes: 11 additions & 17 deletions src/card.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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);
Expand All @@ -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);
}
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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);
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
{
Expand Down
36 changes: 19 additions & 17 deletions src/stats.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -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
{
Expand Down Expand Up @@ -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
Expand All @@ -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"])) {
Expand All @@ -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) {
Expand All @@ -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",
Expand All @@ -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
{
Expand Down Expand Up @@ -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
{
Expand Down Expand Up @@ -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
{
Expand Down

0 comments on commit c24b1af

Please sign in to comment.