Download the PHP package jasonlewis/expressive-date without Composer

Expressive Date

A fluent extension to PHPs DateTime class.

Table of Contents

• Installation
  • Composer
  • Manually
  • Laravel 4
• Usage
  • Getting Instances
  • Quick Helpers
  • Cloning
  • Manipulating Dates
  • Differences Between Dates
  • Comparing Dates
  • Interacting With Dates
  • Formatting Dates
  • Working With Timezones
• Changelog
• License

Installation

Composer

Add Expressive Date to your composer.json file.

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

Run composer install to get the latest version of the package.

Manually

It's recommended that you use Composer, however you can download and install from this repository.

Laravel 4

Expressive Date comes with a service provider for Laravel 4. You'll need to add it to your composer.json as mentioned in the above steps, then register the service provider with your application.

Open app/config/app.php and find the providers key. Add ExpressiveDateServiceProvider to the array.

You can get an instance of Expressive Date through the applications container.

You can also use the other instantiation methods described below.

Usage

Expressive Date is an extension to PHPs DateTime class. This means that if you can't do something with Expressive Date you still have the flexibility of DateTime at your disposal.

Getting Instances

Before you can begin working with dates you'll need to get an instance of ExpressiveDate. You have a number of options available to you.

Both of these methods accepts two parameters, a time string and a timezone. This is identical to the DateTime constructor except the second parameters timezone does not need to be an intance of DateTimeZone.

Alternatively, you can make a date from existing dates or times.

If you use null as any of the parameters then Expressive Date will use the current respective value. The only exception to this is if you supply an hour to ExpressiveDate::makeFromTime() but no minute or second, instead of defaulting to the current minute or second it will set them to 0. This mimicks the existing functionality when interacting with dates using PHP.

Quick Helpers

There are a couple of quick helper methods available to you when using Expressive Date.

These helpers also set the time to midnight.

Cloning

You can clone an instance of ExpressiveDate with the clone() method.

A clone is identical to the original instance and is useful when you need to compare or manipulate a date without affecting the original instance.

Manipulating Dates

When working with dates you'll often want to manipulate it in a number of ways. Expressive Date eases this process with a simple and intuitive syntax.

You can also set the unit manually using one of the setters.

There are also several methods to quick jump to the start or end of a day, month, or week.

The start and end of the week are influenced by what day you configure to be the start of the week. In America, the start of the week is Sunday and for most other places it's Monday. By default the start of the week is Sunday.

Lastly you can set the timestamp directly or set it from a string.

Differences Between Dates

Getting the difference between two dates is very easy with Expressive Date. Let's see how long it's been since my birthday, which was on the 31st January, 1991.

Wow, I'm over 689040000 seconds old!

In the above example I'm explicitly passing in another instance to compare against. You don't have to, by default it'll use the current date and time.

Comparing Dates

Being able to compare two dates is important in many applications. Expressive Date allows you to compare two ExpressiveDate instances against one another in a variety of ways.

The methods themselves should be self explanatory. The sameAs() method is an alias of equalTo().

Interacting With Dates

Expressive Date provides a number of helpful methods for interacting with your dates and times.

Formatting Dates

It's now time to display your date and time to everyone. Expressive Date comes with a couple of predefined formatting methods for your convenience.

You can set a default date format on each instance of Expressive Date which will then be used when you cast the object to a string.

Expressive Date also comes with a human readable or relative date method.

You can also pass in an instance of Expressive Date to compare against, and it's date can also be in the future.

Working with Timezones

It's always important to factor in timezones when working with dates and times. Because Expressive Date uses PHPs DateTime class it'll default to using the date defined with date_default_timezone_set().

If you need to you can manipulate the timezone on the fly.

You can also get an instance of PHPs DateTimeZone if you need it for other manipulations.

Or you can just get the name of the timezone.

Changelog

1.0.2

• Added copy method.
• Added docblock for magic method hints.
• Added startOfWeek, endOfWeek, setWeekStartDay, and getWeekStartDay methods.
• Allowed setWeekStartDay to accept the name of the day as a parameter, e.g., Monday.
• Fixed exceptions being thrown when using floats for manipulation, e.g., ExpressiveDate::addDays(0.5).
• Added makeFromDate, makeFromTime, and makeFromDateTime methods.
• Fixed bug with the week start day being inclusive resulting in 8 day weeks.
• Added equalTo, sameAs, greaterThan, lessThan, greaterOrEqualTo, and lessOrEqualTo methods.

1.0.1

• Added the setDefaultDate method.
• Added __toString method which uses the default date.
• Removed the String suffix from date formatting methods.

1.0.0

• Initial release.

License

Expressive Date is licensed under the 2-clause BSD, see the LICENSE file for more details.