README

PHP DateTime 类的流畅扩展。

安装

Composer

将 Expressive Date 添加到您的 composer.json 文件中。

"jasonlewis/expressive-date": "1.0.*"

运行 composer install 以获取包的最新版本。

手动

建议使用 Composer，但您也可以从本存储库下载并安装。

Laravel 4

Expressive Date 包含 Laravel 4 的服务提供者。您需要按照上述步骤将其添加到 composer.json 中，然后将其注册到您的应用程序中。

打开 app/config/app.php 并找到 providers 键。将 ExpressiveDateServiceProvider 添加到数组中。

您可以通过应用程序容器获取 Expressive Date 的实例。

$date = App::make('date');

// Or if you have access to an instance of the application.
$date = $app['date'];

您还可以使用以下描述的其他实例化方法。

用法

Expressive Date 是 PHP 的 DateTime 类的扩展。这意味着如果您无法使用 Expressive Date 做某事，您仍然可以使用 DateTime 的灵活性。

获取实例

在您开始使用日期之前，您需要获取 ExpressiveDate 的实例。您有多种选择。

// Instantiate a new instance of Expressive Date.
// This will create an instance and use the current date and time
$date = new ExpressiveDate;

// Use the static make method to get an instance of Expressive Date.
$date = ExpressiveDate::make();

这两种方法接受两个参数，一个时间字符串和一个时区。这与 DateTime 构造函数相同，除了第二个参数时区不需要是 DateTimeZone 的实例。

// Pass a valid timezone as the second parameter.
$date = new ExpressiveDate(null, 'Australia/Melbourne');

// Or you can still use a DateTimeZone instance.
$timezone = new DateTimeZone('Australia/Melbourne');

$date = new ExpressiveDate(null, $timezone);

或者，您可以从现有的日期或时间创建一个日期。

// You can use existing dates to get an instance of Expressive Date.
$date = ExpressiveDate::makeFromDate(2012, 1, 31);

// If you have the time, you can use that instead.
$date = ExpressiveDate::makeFromTime(14, 30, 0);

如果您将 null 用作任何参数，则 Expressive Date 将使用当前相应的值。唯一例外的是，如果您向 ExpressiveDate::makeFromTime() 提供了小时但没有分钟或秒，而不是默认为当前分钟或秒，它将它们设置为 0。这模仿了使用 PHP 与日期交互时现有的功能。

快速助手

使用 Expressive Date 时，您有一组快速助手方法可用。

$date = new ExpressiveDate; // Creates an instance that uses current date and time

$date->today(); // Sets to todays date, e.g., 1991-01-31 00:00:00

$date->tomorrow(); // Sets to tomorrows date, e.g., 1991-02-01 00:00:00

$date->yesterday(); // Sets to yesterdays date, e.g., 1991-01-30 00:00:00

这些助手方法也将时间设置为午夜。

克隆

您可以使用 clone() 方法克隆一个 ExpressiveDate 的实例。

$date = new ExpressiveDate;

$clone = $date->clone();

克隆与原始实例相同，当您需要比较或操作日期而不影响原始实例时非常有用。

操作日期

当处理日期时，您通常会希望以多种方式对其进行操作。Expressive Date 通过简单直观的语法简化了此过程。

$date = new ExpressiveDate('December 1, 2012 12:00:00 PM');

$date->addOneDay(); // December 2, 2012 12:00:00 PM
$date->addDays(10); // December 12, 2012 12:00:00 PM
$date->minusOneDay(); // December 11, 2012 12:00:00 PM
$date->minusDays(10); // December 1, 2012 12:00:00 PM

$date->addOneWeek(); // December 8, 2012 12:00:00 PM
$date->addWeeks(10); // February 16, 2013, at 12:00:00 PM
$date->minusOneWeek(); // February 9, 2013 12:00:00 PM
$date->minusWeeks(10); // December 1, 2012 12:00:00 PM

$date->addOneMonth(); // January 1, 2013 12:00:00 PM
$date->addMonths(10); // November 1, 2013 12:00:00 PM
$date->minusOneMonth(); // October 1, 2013 12:00:00 PM
$date->minusMonths(10); // December 1, 2012 12:00:00 PM

$date->addOneYear(); // December 1, 2013 12:00:00 PM
$date->addYears(10); // December 1, 2023 12:00:00 PM
$date->minusOneYear(); // December 1, 2022 12:00:00 PM
$date->minusYears(10); // December 1, 2012 12:00:00 PM

$date->addOneHour(); // December 1, 2012 1:00:00 PM
$date->addHours(10); // December 1, 2012 11:00:00 PM
$date->minusOneHour(); // December 1, 2012 10:00:00 PM
$date->minusHours(10); // December 1, 2012 12:00:00 PM

$date->addOneMinute(); // December 1, 2012 12:01:00 PM
$date->addMinutes(10); // December 1, 2012 12:11:00 PM
$date->minusOneMinute(); // December 1, 2012 12:10:00 PM
$date->minusMinutes(10); // December 1, 2012 12:00:00 PM

$date->addOneSecond(); // December 1, 2012 12:00:01 PM
$date->addSeconds(10); // December 1, 2012 12:00:11 PM
$date->minusOneSecond(); // December 1, 2012 12:00:10 PM
$date->minusSeconds(10); // December 1, 2012 12:00:00 PM

您还可以使用一个设置器手动设置单位。

$date = new ExpressiveDate('December 1, 2012 12:00:00 PM');

$date->setDay(31); // December 31, 2012 12:00:00 PM
$date->setMonth(1); // January 31, 2012 12:00:00 PM
$date->setYear(1991); // January 31, 1991 12:00:00 PM
$date->setHour(6); // January 31, 1991 6:00:00 AM
$date->setMinute(30); // January 31, 1991 6:30:00 AM
$date->setSecond(53); // January 31, 1991 6:30:53 AM

还有几种方法可以快速跳转到一天、一个月或一周的开始或结束。

$date = new ExpressiveDate('December 1, 2012 12:00:00 PM');

$date->startOfDay(); // December 1, 2012 12:00:00 AM
$date->endOfDay(); // December 1, 2012 11:59:59 PM

$date->startOfWeek(); // 25th November, 2012 at 12:00 AM
$date->endOfWeek(); // 1st December, 2012 at 11:59 PM

$date->startOfMonth(); // December 1, 2012 12:00:00 AM
$date->endOfMonth(); // December 31, 2012 11:59:59 PM

一周的开始和结束受您配置为一周开始的那一天的影响。在美国，一周的开始是星期日，而在大多数其他地方是一周的开始是星期一。默认情况下，一周的开始是星期日。

$date = new ExpressiveDate('December 1, 2012 12:00:00 PM');

// Set the week start day to Monday, to set it to Sunday you'd use 0.
$date->setWeekStartDay(1);

// You can also use the actual name of the day so it makes more sense.
$date->setWeekStartDay('monday');

$date->startOfWeek(); // 26th November, 2012 at 12:00 AM

最后，您可以直接设置时间戳或从字符串设置它。

$date = new ExpressiveDate;

$date->setTimestamp(time()); // Set the timestamp to the current time.
$date->setTimestampFromString('31 January 1991'); // Set timestamp from a string.

日期之间的差异

使用 Expressive Date 获取两个日期之间的差异非常简单。让我们看看自从我的生日以来有多长时间了，我的生日是在 1991 年 1 月 31 日。

$date = new ExpressiveDate('January 31, 1991');
$now = new ExpressiveDate('December 1, 2012');

$date->getDifferenceInYears($now); // 21
$date->getDifferenceInMonths($now); // 262
$date->getDifferenceInDays($now); // 7975
$date->getDifferenceInHours($now); // 191400
$date->getDifferenceInMinutes($now); // 11484000
$date->getDifferenceInSeconds($now); // 689040000

哇，我已经超过 689040000 秒了！

在上面的示例中，我明确地传递了一个实例进行比较。您不必这么做，默认情况下它将使用当前日期和时间。

$date = new ExpressiveDate('January 31, 1991');

$date->getDifferenceInYears(); // Will use the current date and time to get the difference.

比较日期

在许多应用程序中，能够比较两个日期非常重要。Expressive Date 允许您以多种方式比较两个 ExpressiveDate 实例。

$date = new ExpressiveDate;

$date->equalTo($date->clone()); // true
$date->sameAs($date->clone()->minusOneDay()); // false
$date->notEqualTo($date->clone()); // false
$date->greaterThan($date->clone()->minusOneDay()); // true
$date->lessThan($date->clone()->addOneDay()); // true
$date->greaterOrEqualTo($date->clone()); // true
$date->lessOrEqualTo($date->clone()->minusOneDay()); // false

这些方法本身应该很容易理解。sameAs() 方法是 equalTo() 的别名。

与日期交互

Expressive Date 提供了多种方便的方法来与您的日期和时间交互。

$date = new ExpressiveDate('December 1, 2012 2:30:50 PM');

$date->getDay(); // 1
$date->getMonth(); // 12
$date->getYear(); // 2012
$date->getHour(); // 14
$date->getMinute(); // 30
$date->getSecond(); // 50
$date->getDayOfWeek(); // Saturday
$date->getDayOfWeekAsNumeric(); // 6
$date->getDaysInMonth(); // 31
$date->getDayOfYear(); // 335
$date->getDaySuffix(); // st
$date->getGmtDifference(); // +1100
$date->getSecondsSinceEpoch(); // 1354320000
$date->isLeapYear(); // true
$date->isAmOrPm(); // PM
$date->isDaylightSavings(); // true
$date->isWeekday(); // false
$date->isWeekend(); // true

日期格式化

现在是时候向所有人显示您的日期和时间了。Expressive Date 随附一些预定义的格式化方法，方便您使用。

$date = new ExpressiveDate('December 1, 2012 2:30:50 PM');

$date->getDate(); // 2012-12-01
$date->getDateTime(); // 2012-12-01 14:30:50
$date->getShortDate(); // Dec 1, 2012
$date->getLongDate(); // December 1st, 2012 at 2:30pm
$date->getTime(); // 14:30:50

// You can still define your own formats.
$date->format('jS F, Y'); // 31st January, 2012

您可以为 Expressive Date 的每个实例设置默认日期格式，然后在将对象转换为字符串时使用该格式。

$date = new ExpressiveDate('December 1, 2012 2:30:50 PM');

echo $date; // 1st December, 2012 at 2:30pm

$date->setDefaultDateFormat('d M y');

echo $date; // 1 Dec 12

Expressive Date 还提供了一种人类可读或相对日期方法。

$date = new ExpressiveDate('December 1, 2012 2:30:50 PM');

$date->getRelativeDate(); // Would show something similar to: 4 days ago

您还可以传递一个 Expressive Date 实例进行比较，并且它的日期也可以在未来。

$now = new ExpressiveDate('December 1, 2012 2:30:50 PM');
$future = new ExpressiveDate('December 9, 2012 7:45:32 AM');

$now->getRelativeDate($future); // 1 week from now

处理时区

在处理日期和时间时，始终需要考虑时区。由于 Expressive Date 使用 PHP 的 DateTime 类，因此它将默认使用 date_default_timezone_set() 定义的日期。

如果需要，您可以在运行时操纵时区。

$date = new ExpressiveDate;

$date->setTimezone('Australia/Darwin');

// Or use an instance of DateTimeZone.
$timezone = new DateTimeZone('Australia/Darwin');

$date->setTimezone($timezone);

您还可以获取 PHP 的 DateTimeZone 实例，如果您需要用于其他操作。

$date = new ExpressiveDate;

$timezone = $date->getTimezone();

或者，您也可以直接获取时区的名称。

$date = new ExpressiveDate;

$timezone = $date->getTimezoneName(); // Australia/Melbourne

变更日志

1.0.2

添加了 copy 方法。
添加了用于魔法方法提示的 docblock。
添加了 startOfWeek、endOfWeek、setWeekStartDay 和 getWeekStartDay 方法。
允许 setWeekStartDay 接受天的名称作为参数，例如，星期一。
修复了使用浮点数进行操作时抛出异常的问题，例如，ExpressiveDate::addDays(0.5)。
添加了 makeFromDate、makeFromTime 和 makeFromDateTime 方法。
修复了周起始日包含导致8天周的错误。
添加了 equalTo、sameAs、greaterThan、lessThan、greaterOrEqualTo 和 lessOrEqualTo 方法。

1.0.1

添加了 setDefaultDate 方法。
添加了 __toString 方法，它使用默认日期。
从日期格式化方法中移除了 String 后缀。

1.0.0

初始发布。

许可证

Expressive Date 根据 2-clause BSD 许可证授权，有关更多详细信息，请参阅 LICENSE 文件。

jasonlewis / expressive-date

维护者

详细信息