Add timezone option for current day checks

victorjudysen · victorjudysen · commit e5b5c192cdb5 · 2026-07-30T11:30:05.000+03:00
diff --git a/README.md b/README.md
@@ -137,6 +137,7 @@ If the `theme` parameter is specified, any color customizations specified will b
 |     `excludeDaysLabel`     |       Excluded days of the week text color       |                             **hex code** without `#` or **css color**                              |
 |       `date_format`        |  Date format pattern or empty for locale format  |                        See note below on [📅 Date Formats](#-date-formats)                         |
 |          `locale`          |  Locale for labels and numbers (Default: `en`)   |                            ISO 639-1 code - See [🗪 Locales](#-locales)                             |
+|         `timezone`         |    Timezone used to determine the current day    |                            IANA timezone identifier, eg. `Asia/Kolkata`                            |
 |      `short_numbers`       |  Use short numbers (e.g. 1.5k instead of 1,500)  |                                         `true` or `false`                                          |
 |           `type`           |          Output format (Default: `svg`)          |                              Current options: `svg`, `png` or `json`                               |
 |           `mode`           |          Streak mode (Default: `daily`)          |             `daily` (contribute daily) or `weekly` (contribute once per Sun-Sat week)              |
diff --git a/src/cache.php b/src/cache.php
@@ -19,7 +19,7 @@
  * user/options combinations that could produce the same concatenated string.
  *
  * @param string $user GitHub username
- * @param array $options Additional options that affect the stats (mode, exclude_days, starting_year)
+ * @param array $options Additional options that affect the stats (mode, exclude_days, starting_year, timezone)
  * @return string Cache key (filename-safe)
  */
 function getCacheKey(string $user, array $options = []): string
@@ -185,7 +185,7 @@ function clearExpiredCache(int $maxAge = CACHE_DURATION): int
  * Clear cache for a specific user
  *
  * Note: This function only clears the cache for the user with empty/default options.
- * Cache entries with non-empty options (starting_year, mode, exclude_days) will NOT
+ * Cache entries with non-empty options (starting_year, mode, exclude_days, timezone) will NOT
  * be cleared. This is a limitation of the hash-based cache key system - we cannot
  * enumerate all possible option combinations without storing additional metadata.
  *
diff --git a/src/demo/index.php b/src/demo/index.php
@@ -119,6 +119,9 @@ function gtag() {
                     <?php endforeach; ?>
                 </select>
 
+                <label for="timezone">Timezone</label>
+                <input class="param" type="text" id="timezone" name="timezone" placeholder="UTC" />
+
                 <label for="short-numbers">Short Numbers</label>
                 <select class="param" id="short-numbers" name="short_numbers">
                     <option>false</option>
diff --git a/src/demo/js/script.js b/src/demo/js/script.js
@@ -10,6 +10,7 @@ const preview = {
     hide_border: "false",
     date_format: "",
     locale: "en",
+    timezone: "",
     border_radius: "4.5",
     mode: "daily",
     type: "svg",
diff --git a/src/generator.php b/src/generator.php
@@ -19,12 +19,14 @@ function generateStreakStats(string $user, array $params = []): array
     $startingYear = isset($params["starting_year"]) ? intval($params["starting_year"]) : null;
     $mode = isset($params["mode"]) ? strval($params["mode"]) : null;
     $excludeDaysRaw = isset($params["exclude_days"]) ? strval($params["exclude_days"]) : "";
+    $timezone = isset($params["timezone"]) ? strval($params["timezone"]) : "";
 
     // Build cache options based on request parameters
     $cacheOptions = [
         "starting_year" => $startingYear,
         "mode" => $mode,
         "exclude_days" => $excludeDaysRaw,
+        "timezone" => $timezone,
     ];
 
     // Check if cache is disabled
@@ -33,13 +35,13 @@ function generateStreakStats(string $user, array $params = []): array
     // Check for cached stats first (24 hour cache) unless cache is disabled
     $cachedStats = $useCache ? getCachedStats($user, $cacheOptions) : null;
 
-    if (!statsMissingOrStale($cachedStats)) {
+    if (!statsMissingOrStale($cachedStats, $timezone)) {
         return $cachedStats;
     }
 
     // Fetch fresh data from GitHub API
     $contributionGraphs = getContributionGraphs($user, $startingYear);
-    $contributions = getContributionDates($contributionGraphs);
+    $contributions = getContributionDates($contributionGraphs, $timezone);
 
     if ($mode === "weekly") {
         $stats = getWeeklyContributionStats($contributions);
@@ -61,9 +63,10 @@ function generateStreakStats(string $user, array $params = []): array
  * Check if cached stats are missing or stale - Streak may be outdated if it ends before today
  *
  * @param array|null $cachedStats The cached stats to check
+ * @param string $timezone Timezone identifier, or empty for the server default
  * @return bool True if the cached stats are stale and should be refreshed
  */
-function statsMissingOrStale(?array $cachedStats): bool
+function statsMissingOrStale(?array $cachedStats, string $timezone = ""): bool
 {
     // If there are no cached stats, we need to refresh
     if ($cachedStats === null) {
@@ -87,9 +90,10 @@ function statsMissingOrStale(?array $cachedStats): bool
     $mode = $cachedStats["mode"] ?? "daily";
 
     if ($mode === "weekly") {
-        $startOfWeek = date("Y-m-d", strtotime("last Sunday"));
+        $today = getCurrentDate($timezone);
+        $startOfWeek = getPreviousSunday($today);
         return $currentStreakEnd < $startOfWeek;
     } else {
-        return $currentStreakEnd < date("Y-m-d");
+        return $currentStreakEnd < getCurrentDate($timezone);
     }
 }
diff --git a/src/stats.php b/src/stats.php
@@ -251,14 +251,16 @@ function getGraphQLCurlHandle(string $query, string $token): CurlHandle
 /**
  * Get an array of all dates with the number of contributions
  *
- * @param array<int,stdClass> $contributionCalendars List of GraphQL response objects by year
+ * @param array<int,stdClass> $contributionGraphs List of GraphQL response objects by year
+ * @param string $timezone Timezone identifier, or empty for the server default
+ * @param DateTimeImmutable|null $now Current time override for tests
  * @return array<string,int> Y-M-D dates mapped to the number of contributions
  */
-function getContributionDates(array $contributionGraphs): array
+function getContributionDates(array $contributionGraphs, string $timezone = "", ?DateTimeImmutable $now = null): array
 {
     $contributions = [];
-    $today = date("Y-m-d");
-    $tomorrow = date("Y-m-d", strtotime("tomorrow"));
+    $today = getCurrentDate($timezone, $now);
+    $tomorrow = date("Y-m-d", strtotime("$today +1 day"));
     // sort contribution calendars by year key
     ksort($contributionGraphs);
     foreach ($contributionGraphs as $graph) {
@@ -279,6 +281,25 @@ function getContributionDates(array $contributionGraphs): array
     return $contributions;
 }
 
+/**
+ * Get the current date for a requested timezone.
+ *
+ * @param string $timezone Timezone identifier, or empty for the server default
+ * @param DateTimeImmutable|null $now Current time override for tests
+ * @return string Current date in Y-m-d format
+ */
+function getCurrentDate(string $timezone = "", ?DateTimeImmutable $now = null): string
+{
+    try {
+        $dateTimezone = new DateTimeZone($timezone ?: date_default_timezone_get());
+    } catch (Exception) {
+        throw new InvalidArgumentException("Invalid timezone.", 400);
+    }
+
+    $now = $now ?: new DateTimeImmutable("now");
+    return $now->setTimezone($dateTimezone)->format("Y-m-d");
+}
+
 /**
  * Normalize names of days of the week (eg. ["Sunday", " mon", "TUE"] -> ["Sun", "Mon", "Tue"])
  *
diff --git a/tests/StatsTest.php b/tests/StatsTest.php
@@ -320,6 +320,53 @@ public function testFutureCommits(): void
         $this->assertEquals($expected, $stats);
     }
 
+    /**
+     * Test contribution dates with timezone override
+     */
+    public function testContributionDatesWithTimezone(): void
+    {
+        $now = new DateTimeImmutable("2026-01-01T01:00:00+00:00");
+        $today = getCurrentDate("America/New_York", $now);
+        $tomorrow = date("Y-m-d", strtotime("$today +1 day"));
+        $inTwoDays = date("Y-m-d", strtotime("$today +2 days"));
+        $contributionGraphs = [
+            (object) [
+                "data" => (object) [
+                    "user" => (object) [
+                        "contributionsCollection" => (object) [
+                            "contributionCalendar" => (object) [
+                                "weeks" => (object) [
+                                    (object) [
+                                        "contributionDays" => (object) [
+                                            (object) [
+                                                "contributionCount" => 1,
+                                                "date" => $today,
+                                            ],
+                                            (object) [
+                                                "contributionCount" => 0,
+                                                "date" => $tomorrow,
+                                            ],
+                                            (object) [
+                                                "contributionCount" => 1,
+                                                "date" => $inTwoDays,
+                                            ],
+                                        ],
+                                    ],
+                                ],
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+        ];
+
+        $contributions = getContributionDates($contributionGraphs, "America/New_York", $now);
+
+        $this->assertArrayHasKey($today, $contributions);
+        $this->assertArrayNotHasKey($tomorrow, $contributions);
+        $this->assertArrayNotHasKey($inTwoDays, $contributions);
+    }
+
     /**
      * Test weekly stats
      */

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@`
`19`	`19`	`* user/options combinations that could produce the same concatenated string.`
`20`	`20`	`*`
`21`	`21`	`* @param string $user GitHub username`
`22`		`- * @param array $options Additional options that affect the stats (mode, exclude_days, starting_year)`
	`22`	`+ * @param array $options Additional options that affect the stats (mode, exclude_days, starting_year, timezone)`
`23`	`23`	`* @return string Cache key (filename-safe)`
`24`	`24`	`*/`
`25`	`25`	`function getCacheKey(string $user, array $options = []): string`
`@@ -185,7 +185,7 @@ function clearExpiredCache(int $maxAge = CACHE_DURATION): int`
`185`	`185`	`* Clear cache for a specific user`
`186`	`186`	`*`
`187`	`187`	`* Note: This function only clears the cache for the user with empty/default options.`
`188`		`- * Cache entries with non-empty options (starting_year, mode, exclude_days) will NOT`
	`188`	`+ * Cache entries with non-empty options (starting_year, mode, exclude_days, timezone) will NOT`
`189`	`189`	`* be cleared. This is a limitation of the hash-based cache key system - we cannot`
`190`	`190`	`* enumerate all possible option combinations without storing additional metadata.`
`191`	`191`	`*`