feat: Add date_format parameter

README.md

@@ -73,12 +73,30 @@ If the `theme` parameter is specified, any color customizations specified will b
 | `currStreakLabel` |              Current streak label              |       **hex code** without `#` or **css color**       |
 |   `sideLabels`    |        Total and longest streak labels         |       **hex code** without `#` or **css color**       |
 |      `dates`      |             Date range text color              |       **hex code** without `#` or **css color**       |
+|   `date_format`   |       Date format (Default: `M j[, Y]`)        |    See note below on [Date Formats](#date-formats)    |
 |      `type`       |         Output format (Default: `svg`)         |           Current options: `svg` or `json`            |
 
+### Date Formats
+
+A custom date format can be specified by passing a string to the `date_format` parameter.
+
+The required format is to use format string characters from [PHP's date function](https://www.php.net/manual/en/datetime.format.php) with brackets around the part representing the year.
+
+When the contribution year is equal to the current year, the characters in brackets will be omitted.
+
+**Examples:**
+
+|     Date Format     |                                     Result                                      |
+| :-----------------: | :-----------------------------------------------------------------------------: |
+| <pre>d F[, Y]</pre> | <pre>"2020-04-14" => "14 April, 2020"<br/><br/>"2021-04-14" => "14 April"</pre> |
+|  <pre>j/n/Y</pre>   |   <pre>"2020-04-14" => "14/4/2020"<br/><br/>"2021-04-14" => "14/4/2021"</pre>   |
+| <pre>[Y.]n.j</pre>  |     <pre>"2020-04-14" => "2020.4.14"<br/><br/>"2021-04-14" => "4.14"</pre>      |
+| <pre>M j[, Y]</pre> |   <pre>"2020-04-14" => "Apr 14, 2020"<br/><br/>"2021-04-14" => "Apr 14"</pre>   |
+
 ### Example
 
 ```md
-[![GitHub Streak](https://github-readme-streak-stats.herokuapp.com/?user=denvercoder1&currStreakNum=2FD3EB&fire=pink&sideLabels=F00)](https://git.io/streak-stats)
+[![GitHub Streak](https://github-readme-streak-stats.herokuapp.com/?user=denvercoder1&currStreakNum=2FD3EB&fire=pink&sideLabels=F00&date_format=[Y.]n.j)](https://git.io/streak-stats)
 ```
 
 ## ℹ️ How these stats are calculated

src/card.php

@@ -4,17 +4,19 @@
  * Convert date from Y-M-D to more human-readable format
  *
  * @param string $dateString String in Y-M-D format
- * @return string formatted Date string
+ * @param string $format Date format to use
+ * @return string Formatted Date string
  */
-function formatDate(string $dateString): string
+function formatDate(string $dateString, string $format): string
 {
     $date = new DateTime($dateString);
     // if current year, display only month and day
     if (date_format($date, "Y") == date("Y")) {
-        return date_format($date, "M j");
+        // remove brackets and all text within them
+        return date_format($date, preg_replace("/\[.*?\]/", "", $format));
     }
-    // otherwise, display month, day, and year
-    return date_format($date, "M j, Y");
+    // otherwise, display month, day, and year (just brackets removed)
+    return date_format($date, str_replace(array("[", "]"), "", $format));
 }
 
 /**
@@ -87,24 +89,29 @@ function generateCard(array $stats, array $params = null): string
     // get requested theme, use $_REQUEST if no params array specified
     $theme = getRequestedTheme($params ?? $_REQUEST);
 
+    // get date format
+    $dateFormat = isset(($params ?? $_REQUEST)["date_format"]) 
+        ? ($params ?? $_REQUEST)["date_format"] 
+        : "M j[, Y]";
+
     // total contributions
     $totalContributions = $stats["totalContributions"];
-    $firstContribution = formatDate($stats["firstContribution"]);
+    $firstContribution = formatDate($stats["firstContribution"], $dateFormat);
     $totalContributionsRange = $firstContribution . " - Present";
 
     // current streak
     $currentStreak = $stats["currentStreak"]["length"];
-    $currentStreakStart = formatDate($stats["currentStreak"]["start"]);
-    $currentStreakEnd = formatDate($stats["currentStreak"]["end"]);
+    $currentStreakStart = formatDate($stats["currentStreak"]["start"], $dateFormat);
+    $currentStreakEnd = formatDate($stats["currentStreak"]["end"], $dateFormat);
     $currentStreakRange = $currentStreakStart;
     if ($currentStreakStart != $currentStreakEnd) {
         $currentStreakRange .= " - " . $currentStreakEnd;
     }
 
     // longest streak
     $longestStreak = $stats["longestStreak"]["length"];
-    $longestStreakStart = formatDate($stats["longestStreak"]["start"]);
-    $longestStreakEnd = formatDate($stats["longestStreak"]["end"]);
+    $longestStreakStart = formatDate($stats["longestStreak"]["start"], $dateFormat);
+    $longestStreakEnd = formatDate($stats["longestStreak"]["end"], $dateFormat);
     $longestStreakRange = $longestStreakStart;
     if ($longestStreakStart != $longestStreakEnd) {
         $longestStreakRange .= " - " . $longestStreakEnd;

tests/OptionsTest.php

@@ -169,7 +169,7 @@ public function testHideBorder(): void
     public function testDateFormatSameYear(): void
     {
         $year = date("Y");
-        $formatted = formatDate("$year-04-12");
+        $formatted = formatDate("$year-04-12", "M j[, Y]");
         $this->assertEquals("Apr 12", $formatted);
     }
 
@@ -178,7 +178,26 @@ public function testDateFormatSameYear(): void
      */
     public function testDateFormatDifferentYear(): void
     {
-        $formatted = formatDate("2000-04-12");
+        $formatted = formatDate("2000-04-12", "M j[, Y]");
         $this->assertEquals("Apr 12, 2000", $formatted);
     }
+
+    /**
+     * Test date formatter no brackets different year
+     */
+    public function testDateFormatNoBracketsDiffYear(): void
+    {
+        $formatted = formatDate("2000-04-12", "Y/m/d");
+        $this->assertEquals("2000/04/12", $formatted);
+    }
+
+    /**
+     * Test date formatter no brackets same year
+     */
+    public function testDateFormatNoBracketsSameYear(): void
+    {
+        $year = date("Y");
+        $formatted = formatDate("$year-04-12", "Y/m/d");
+        $this->assertEquals("$year/04/12", $formatted);
+    }
 }

tests/RenderTest.php

@@ -56,6 +56,20 @@ public function testErrorCardRender(): void
         $this->assertEquals($expected, $render);
     }
 
+    /**
+     * Test date_format parameter in render
+     */
+    public function testDateFormatRender(): void
+    {
+        $year = date("Y");
+        $this->testStats["currentStreak"]["end"] = "$year-04-12";
+        $this->testParams["date_format"] = "[Y-]m-d";
+        // Check that the card is rendered as expected
+        $render = generateCard($this->testStats, $this->testParams);
+        $expected = file_get_contents("tests/expected/test_date_card.svg");
+        $this->assertEquals($expected, $render);
+    }
+
     /**
      * Test JSON render
      */