Initial Release

HumanDates.php

@@ -0,0 +1,124 @@
+<?php
+
+class HumanDates
+{
+  /* default range patterns */
+  const rangePatterns = [
+    // 1. Jan. 2023 - 3. Feb. 2024
+    'default'   => ['d. LLL. Y', ' – ', 'd. LLL. Y'],
+
+    // 1. Jan. - 3. Feb. 2023
+    'sameYear'  => ['d. LLL.', ' – ', 'd. LLL. Y'],
+
+    // 1. - 3. Jan. 2023
+    'sameMonth' => ['d.', ' – ', 'd. LLL. Y'],
+
+    // 1. Jan. 2023
+    'sameDay'   => ['d. LLL. Y', '', ''],
+  ];
+
+  /** @var IntlDateFormatter */
+  private $formatter;
+
+  private $patterns = self::rangePatterns;
+
+  function __construct(
+    $locale = "en_GB",
+    $format = "d. MMM Y",
+    $patterns = null,
+  ) {
+    $this->setPatterns($patterns);
+    $this->setLocale($locale);
+    $this->setFormat($format);
+  }
+
+  /**
+   * Format a single date as human readable date string
+   */
+  function format($time, $format = null): string
+  {
+    if ($format) {
+      $formatter = clone $this->formatter;
+      $formatter->setPattern($format);
+    } else $formatter = $this->formatter;
+    return $formatter->format($this->timestamp($time));
+  }
+
+  /**
+   * Given a timestamp return a formatted date string
+   */
+  private function getString(int $timestamp, $pattern): string
+  {
+    if (!$pattern) return '';
+    if (!$timestamp) return '';
+    $this->formatter->setPattern($pattern);
+    return $this->formatter->format($timestamp);
+  }
+
+  /**
+   * Format a daterange as human readable date string
+   */
+  function range($from, $to): string
+  {
+    $from = $this->timestamp($from);
+    $to = $this->timestamp($to);
+
+    if (date("Ymd", $from) === date("Ymd", $to)) $pattern = 'sameDay';
+    elseif (date("Ym", $from) === date("Ym", $to)) $pattern = 'sameMonth';
+    elseif (date("Y", $from) === date("Y", $to)) $pattern = 'sameYear';
+    else $pattern = 'default';
+
+    $pattern = $this->patterns[$pattern];
+    $pieces = array_filter([
+      $this->getString($from, $pattern[0]),
+      $this->getString($to, $pattern[2]),
+    ]);
+    return implode($pattern[1], $pieces);
+  }
+
+  /**
+   * Set default date format pattern
+   */
+  function setFormat(string $format): self
+  {
+    $this->formatter->setPattern($format);
+    return $this;
+  }
+
+  /**
+   * Set locale of the IntlDateFormatter used to format dates
+   */
+  function setLocale($locale): self
+  {
+    $this->formatter = new IntlDateFormatter(
+      $locale,
+      IntlDateFormatter::NONE,
+      IntlDateFormatter::NONE,
+    );
+    return $this;
+  }
+
+  /**
+   * Set range patterns
+   */
+  function setPatterns($patterns): self
+  {
+    if (!$patterns) return $this;
+    $this->patterns = array_merge(self::rangePatterns, $patterns);
+    return $this;
+  }
+
+  /**
+   * Convert time to timestamp
+   * Use syntax supported by strtotime()
+   */
+  private function timestamp($time): int
+  {
+    if (is_string($time)) {
+      if (is_numeric($time)) $time = (int)$time;
+      else $time = strtotime($time);
+    }
+    if (is_int($time)) return $time;
+    return 0;
+  }
+}

README.md

@@ -1 +1,116 @@
-# HumanDates
+# HumanDates
+
+HumanDates is a PHP library that provides convenient methods for formatting dates as human-readable strings and generating human-friendly date ranges. It uses the `IntlDateFormatter` class to ensure accurate localization and formatting based on the specified locale.
+
+## Usage
+
+To get started, include the HumanDates library and create a new instance:
+
+```php
+// manual download
+require_once "/path/to/HumanDates.php";
+
+// using composer
+// composer require baumrock/humandates
+require_once "/path/to/composer/autoload.php";
+
+// create HumanDates instance
+$dates = new HumanDates();
+echo $dates->format("2023-01-01");              // 1. Jan 2023
+echo $dates->range("2023-01-01", "2023-01-03"); // 1. - 3. Jan 2023
+```
+
+## Why Use HumanDates?
+
+HumanDates provides several benefits and reasons to consider using it in your PHP projects:
+
+1. Simplified Date Formatting
+
+    HumanDates simplifies the process of formatting dates in PHP. It offers a straightforward and intuitive API for formatting both single dates and date ranges, eliminating the need for complex and error-prone manual formatting.
+
+2. Localization Support
+
+    HumanDates leverages the `IntlDateFormatter` class, ensuring accurate localization of date formats based on the specified locale. This allows you to generate date strings that are culturally appropriate and easily understood by users from different regions.
+
+3. Customizable Date Range Formats
+
+    With HumanDates, you have the flexibility to define custom format patterns for date ranges. You can easily tailor the output to match your specific requirements, such as including or excluding certain date components, adjusting separators, or changing the order of elements.
+
+4. Replacement for Deprecated `strftime()`
+
+    As of PHP 8, the `strftime()` function is deprecated and will be removed in PHP 9. HumanDates can serve as a replacement for `strftime()`, providing a modern and reliable alternative for formatting dates in PHP.
+
+5. MIT License
+
+    HumanDates is released under the permissive MIT License, allowing you to freely use, modify, and distribute the library in your projects, both personal and commercial.
+
+By using HumanDates, you can enhance the user experience by presenting dates in a human-readable format, improve code maintainability, and ensure consistent and accurate date formatting across your application.
+
+Give HumanDates a try and simplify your date formatting needs with ease!
+
+## Formatting a Single Date
+
+You can format a single date using the `format()` method, which can serve as a replacement for the `strftime()` function which is deprecated in PHP8 and will be removed in PHP9:
+
+```php
+echo $dates->format("2023-01-01", "d.M.y"); // Output: 1.1.2023
+```
+
+The `format()` method accepts a date string or timestamp as the first parameter and an optional format pattern as the second parameter. The format pattern follows the syntax defined by the `IntlDateFormatter` class: [See here for a list of all available letters](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table).
+
+## Formatting a Date Range
+
+HumanDates provides a convenient way to format date ranges as well. Use the `range()` method by passing the start and end dates:
+
+```php
+// example using locale de_DE
+echo $dates->range("2023-01-01", "2023-02-03"); // Output: 1. Jan. - 3. Feb. 2023
+echo $dates->range("2023-01-01", "2023-01-03"); // Output: 1. - 3. Jan. 2023
+```
+
+By default, the `range()` method uses predefined patterns to format the date range. However, you can also specify custom patterns by providing an array of patterns as the third parameter:
+
+```php
+// example using locale de_DE
+echo $dates->range("2023-01-01", "2023-01-03", [
+	'default'   => ['d. MMMM y', ' – ', 'd. MMMM y'], // 1. Januar 2023 - 3. Februar 2024
+	'sameYear'  => ['d. MMMM',   ' – ', 'd. MMMM y'], // 1. Januar - 3. Februar 2023
+	'sameMonth' => ['d.',        ' – ', 'd. MMMM y'], // 1. - 3. Januar 2023
+	'sameDay'   => ['d. MMMM y'],                     // 1. Januar 2023
+]);
+```
+
+## Setting Locales
+
+You can set the locale for date formatting either globally for the current `HumanDates` instance or on a per-format basis.
+
+To set the locale globally, pass the desired locale as a parameter when creating a new `HumanDates` instance:
+
+```php
+$dates = new HumanDates("de_AT");
+echo $dates->format($timestamp, "d. MMMM y"); // Output: 1. Jänner 2023
+```
+
+To set the locale for a specific `format()` call, include the `locale` parameter:
+
+```php
+echo $dates->format(
+  $timestamp,
+  format: "d. MMMM y",
+  locale: "de_DE",
+); // Output: 1. Januar 2023
+```
+
+## Setting Defaults
+
+You can set default formatting options for your `HumanDates` instance by specifying the locale and format pattern during initialization:
+
+```php
+$dates = new HumanDates("de_AT", "dd.MM.Y");
+echo $dates->format("2023-1-1"); // Output: 01.01.2023
+echo $dates->format("2023-1-1", "d. MMMM y"); // Output: 1.
+```
+
+## Star the Repository
+
+If you find HumanDates useful or interesting, please star the repository on GitHub. By starring the repository, you show your appreciation and support for the project. It also helps us understand the level of community interest and motivates us to further improve the library. So, why not give us a star today? ⭐

composer.json

@@ -0,0 +1,8 @@
+{
+  "name": "baumrock/humandates",
+  "description": "Format date ranges in a human-readable format with automatic pattern selection and localization support.",
+  "require": {
+    "php": ">=8.0"
+  },
+  "license": "MIT"
+}

package.json

@@ -0,0 +1,3 @@
+{
+  "version": "1.0.0"
+}