README

一个简单的服务，用于在整个PHP项目/ API中格式化日期，保持格式的一致性。

目录

• 如何安装
• 如何使用
  • 解析器
  • 格式化器
  • 服务提供商

如何安装

需要PHP 7。使用composer安装

composer require mducharme/date-formatter

如何使用

可立即使用，带有Pimple容器

$container = new \Pimple\Container();
$container->register(new \Mducharme\DateFormatter\ServiceProvider());


$formatter = $container['date/formatter'];
$displayDate = $formatter->format($date);

直接使用服务

$formatter = new \Mducharme\DateFormatter\Formatter(
    new \Mducharme\DateFormatter\Parser()
);
$displayDate = $formatter->format($date);

解析器

除了Formatter之外，还包括一个Parser服务。它的唯一目的是确保混合值（DateTime对象或可解析的字符串）被解析为DateTime对象。

在解析过程中，任何无效的字符串或参数都会抛出异常（\InvalidArgumentException）。除了null值外，默认允许，但可以通过parse()方法的参数来禁止。在这种情况下，如果允许作为参数，parse()方法将返回null而不是\DateTimeInterface对象。

use \Mducharme\DateFormatter\Parser;

$parser = new Parser();

// Setting the strict mode to false allows a parser that will not throw exceptions.
$softParser = new Parser(false);

// With proper parameters, the parser returns (parsed) Datetime objects
$parser->parse('now');

// With invalid string or types of parameter, the strict parser throws an `\InvalidArgumentException`.
$parser->parse('-invalid-');
$parser->parse(new InvalidObject());
$oarser->parse(false);

处理null

// By default, null is allowed. 
// Parsing returns null in this case, instead of the usual DateTimeInterface.
$parser->parse(null);

// If null is disallowed, attempting to parse a null value also throws an `\InvalidArgumentException`.
$parser->parse(null, false);

作为单一用途的服务，Parser也是可调用的，可以直接调用

$parsed = $parser($date);

格式化器

格式化器是本库提供的主要服务。它的唯一目的是将DateTime对象渲染为格式化的字符串（或多个格式）。

作为单一用途的服务，Formatter也是可调用的

echo $formatter($date, 'atom');

它默认提供了许多格式。有关默认格式的详细信息，请参阅Formatter源文件。您可以通过使用Formatter::ALL作为格式参数来获取所有可用格式的数组。

$formatter = new Formatter($parser);
$allFormats = $formatter($date, Formatter::ALL);
var_dump($allFormats);

通过传递一个可选的格式数组到格式化器构造函数，可以添加自定义格式或覆盖默认格式。

$customFormats = [
    'is-leap-year' => function(\DateTimeInterface $date) {
        return ($date->format('L') ? 'Yes' : 'No';
    },
    'custom-string' => 'H:i:S (u) d-m-Y'
];
$formatter = new Formatter($parser, $customFormats);

// Outputs "Yes" because 2012 was a leap year
echo $formatter(new DateTime('2012-01-01'), 'is-leap-year');

// Outputs the custom format
echo $formatter(new DateTime('2012-01-01'), 'custom-string');

通过指定一个格式数组，也可以返回一个格式化日期的数组

$formats = $formatter('2012-01-01', ['atom', 'custom-string', 'is-leap-year']);

格式可以是字符串，它将被DateTimeInterface::format()格式化，或者是一个具有以下签名的回调函数：

/**
 * @param \DateTimeInterface A date object.
 * @return string
 */
function callback(\DateTimeInterface $date);

如果没有提供$format给format()方法（第二个参数），则将使用默认格式。可以通过构造函数设置默认格式，这是可选的，默认为'atom'格式。

// This will use the "atom" format as no default format was specified to the constructor
$formatter1 = new Formatter($parser, null, null);
echo $formatter1($date);

// This will use the "rfc822" format, as it was set as default
$formatter2 = new Formatter($parser, null, 'rfc822');
echo $formatter2($date);

服务提供商

作为便利，还包括一个Pimple服务提供商，用于已启动的解析器（date/parser）和格式化器（date/formatter）。

$container = new \Pimple\Container();
$container->register(new \Mducharme\DateFormatter\ServiceProvider());

$parser = $container['date/parser'];
$formatter = $container['date/formatter'];

要自定义选项，可以扩展date/custom-formats和date/default-format容器选项。