README

HumanDates 是一个 PHP 库，它提供了方便的方法来格式化日期为人类可读的字符串和生成人类友好的日期范围。它使用 IntlDateFormatter 类以确保基于指定区域的准确本地化和格式化。

<!-- before --> 1.1.2023 - 3.1.2023
<!-- after  --> 1. - 3.1.2023

用法

要开始使用，请包含 HumanDates 库并创建一个新的实例

// 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

为什么使用 HumanDates？

HumanDates 提供了几个优点和理由，可以考虑在您的 PHP 项目中使用它

简化日期格式化

HumanDates 简化了在 PHP 中格式化日期的过程。它提供了一个简单直观的 API 来格式化单个日期和日期范围，消除了复杂且易出错的手动格式化的需要。
本地化支持

HumanDates 利用 IntlDateFormatter 类，确保根据指定区域准确本地化日期格式。这允许您生成文化上适当且易于不同地区用户理解的日期字符串。
可定制的日期范围格式

使用 HumanDates，您有权定义自定义格式模式以用于日期范围。您可以轻松调整输出以满足特定要求，例如包括或排除某些日期组件、调整分隔符或更改元素顺序。
替换废弃的 strftime()

从 PHP 8 开始，strftime() 函数已被废弃，并在 PHP 9 中将被移除。HumanDates 可以作为 strftime() 的替代品，为 PHP 中的日期格式化提供现代和可靠的替代方案。
MIT 许可证

HumanDates 在宽松的 MIT 许可证下发布，允许您自由使用、修改和分发库，适用于个人和商业项目。

使用 HumanDates，您可以通过以人类可读的格式展示日期来提升用户体验，提高代码可维护性，并确保应用程序中日期格式的一致性和准确性。

试试 HumanDates，轻松简化您的日期格式化需求！

格式化单个日期

您可以使用 format() 方法格式化单个日期，该方法可以作为 PHP 8 中已废弃并在 PHP 9 中将被移除的 strftime() 函数的替代品。

echo $dates->format("2023-01-01", "d.M.y"); // Output: 1.1.2023

format() 方法接受一个日期字符串或时间戳作为第一个参数，以及一个可选的格式模式作为第二个参数。格式模式遵循由 IntlDateFormatter 类定义的语法：请在此处查看所有可用字母的列表。

格式化日期范围

HumanDates 还提供了一种方便的方法来格式化日期范围。通过传递起始日期和结束日期来使用 range() 方法

// 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

默认情况下，range() 方法使用预定义的模式来格式化日期范围。但是，您也可以通过提供模式数组作为第三个参数来指定自定义模式

// example using locale de_DE
echo $dates->range("2023-01-01", "2023-01-03", [
	'default'   => ['d. MMMM y', ' bis ', 'd. MMMM y'], // 1. Januar 2023 bis 3. Februar 2024
	'sameYear'  => ['d. MMMM',   ' bis ', 'd. MMMM y'], // 1. Januar bis 3. Februar 2023
	'sameMonth' => ['d.',        ' bis ', 'd. MMMM y'], // 1. bis 3. Januar 2023
	'sameDay'   => ['d. MMMM y'],                       // 1. Januar 2023
]);

请注意，这仅为此单一请求设置模式！如果您想修改全局使用的模式，可以这样做

echo $dates->setPatterns(...)->range(...);

设置区域设置

您可以为日期格式设置区域设置，无论是针对当前 HumanDates 实例的全局设置，还是基于特定格式的设置。

要全局设置区域设置，在创建新的 HumanDates 实例时传递所需的区域设置参数。

$dates = new HumanDates("de_AT");
echo $dates->format($timestamp, "d. MMMM y"); // Output: 1. Jänner 2023

要为特定的 format() 调用设置区域设置，请包含 locale 参数。

echo $dates->format(
  $timestamp,
  format: "d. MMMM y",
  locale: "de_DE",
); // Output: 1. Januar 2023

设置默认值

您可以通过在初始化时指定区域设置和格式模式来为您的 HumanDates 实例设置默认格式化选项。

$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. Jänner 2023

收藏仓库

如果您认为 HumanDates 有用或有趣，请在 GitHub 上收藏该仓库。通过收藏仓库，您表达了对项目的赞赏和支持。这也有助于我们了解社区的兴趣水平，并激励我们进一步改进库。⭐

baumrock / humandates

维护者

详情