README

为您的日期敏感型应用程序提供的业务逻辑抽象层。

安装

composer require hylianshield/date:^1.0

使用

日期容器是一个易于理解的容器，可以存储与完整的 DateTimeInterface 实例一起的数据。它使用 DateTimeInterface 实例作为键，并使用用户提供的数据作为相应的值。

它通过内部使用日期存储实体来实现，该实体使用日期格式确定的精度存储日期对象。

创建日期容器

可以使用工厂创建新的日期容器。这是最简单的方法，需要的配置最少。

<?php
$factory = new HylianShield\Date\DateContainerFactory();

// Create a date container with a precision of whole days.
$container = $factory->createIntervalDay();

使用自定义存储

日期存储是内部将日期及其对应数据存储到内存中的实体。它需要一个日期格式和一个 DateTimeZone 实例来正确配置。

<?php
$storage = new HylianShield\Date\DateStorage(
    'Y-m-d',
    new DateTimeZone('Europe/Amsterdam')
);
$container = new HylianShield\Date\DateContainer($storage);

提供的日期格式用于唯一标识日期对象。为了避免来自不同时区的日期污染我们的业务逻辑，存储只接受与给定时区匹配的日期实例。

填充容器

下面的示例代码只是一个示例。通常，这可能是通过遍历数据源来填充的。

我们使用一个参考日期，位于日期期间的中间。

<?php
$today = new DateTime('today');

然后我们将使用它来构建一个日期范围。

<?php
/** @var DateTime $today */
$start = clone $today;
$start->modify('-1 day');

$end = clone $today;
$end->modify('+2 days');

// Interval of 1 day.
$interval = new DateInterval('P1D');

$period = new DatePeriod($start, $interval, $end);

有了这个，我们用模拟数据填充容器。

<?php
/**
 * @var DatePeriod $period 
 * @var \HylianShield\Date\DateContainerInterface $container
 */
foreach ($period as $date) {
    $container->attach($date, 'foo');
}

现在我们可以检查今天是否存储在容器中

<?php
/**
 * @var DateTimeInterface $today
 * @var \HylianShield\Date\DateContainerInterface $container
 */
var_dump($container->contains($today)); // bool(true)

我们可以显式获取该日期的数据。

<?php
/**
 * @var DateTimeInterface $today
 * @var \HylianShield\Date\DateContainerInterface $container
 */
var_dump($container->getData($today)); // string(3) "foo"

覆盖数据仍然是一个可能的选择。

<?php
/**
 * @var DateTimeInterface $today
 * @var \HylianShield\Date\DateContainerInterface $container
 */
$container->attach($today, 'bar');
var_dump($container->getData($today)); // string(3) "bar"

遍历容器

容器真正的力量在于，您的容器键是完全的 DateTimeInterface 实例。

<?php
/** @var \HylianShield\Date\DateContainerInterface $container */
foreach ($container as $date => $userData) {
    var_dump(
        $date->format('Y-m-d H:i:s'),
        $userData
    );
}

这会输出类似以下的内容

string(19) "2016-04-09 00:00:00"
string(3) "foo"
string(19) "2016-04-10 00:00:00"
string(3) "bar"
string(19) "2016-04-11 00:00:00"
string(3) "foo"

导出容器

为了轻松导出容器内部的数据，它提供了一个转换为 PHP 数组的方法。

<?php
/** @var \HylianShield\Date\DateContainerInterface $container */
var_dump($container->toArray());

这将输出类似以下的内容

array(3) {
  ["2016-04-09"]=>
  string(3) "foo"
  ["2016-04-10"]=>
  string(3) "bar"
  ["2016-04-11"]=>
  string(3) "foo"
}

这里使用的键将对应于在日期存储上配置的格式。

分离日期

当分离日期时，日期及其所有对应数据将消失

<?php
/**
 * @var DateTimeInterface $today
 * @var \HylianShield\Date\DateContainerInterface $container
 */
$container->detach($today);
var_dump(
    $container->contains($today),
    $container->getData($today),
    $container->toArray()
);

输出类似以下的内容

bool(false)
NULL
array(2) {
  ["2016-04-09"]=>
  string(3) "foo"
  ["2016-04-11"]=>
  string(3) "foo"
}

设置非法日期

当混合来自不同时区的日期时，您的业务逻辑会受到影响。为了避免这种情况，日期存储不允许混合时区。

<?php
/** @var \HylianShield\Date\DateContainerInterface $container */
$illegalDate = new DateTime('now', new DateTimeZone('UTC'));
$container->attach($illegalDate, 'baz');

将渲染以下内容

PHP Fatal error:  Uncaught exception 'HylianShield\Date\IllegalDateTimeZoneException' with message 'Date storage expects date in time zone Europe/Amsterdam, yet received UTC'