Introducing Carbon : A simple API extension for DateTime with PHP 5.3+
Unofficially released last month, Carbon is A simple API extension for DateTime with PHP 5.3+. Code examples are worth a thousand words so lets start with this:
printf("Right now is %s", Carbon::now()->toDateTimeString());
printf("Right now in Vancouver is %s", Carbon::now('America/Vancouver')); //implicit __toString()
$tomorrow = Carbon::now()->addDay();
$lastWeek = Carbon::now()->subWeek();
$nextSummerOlympics = Carbon::createFromDate(2012)->addYears(4);
$officialDate = Carbon::now()->toRFC2822String();
$howOldAmI = Carbon::createFromDate(1975, 5, 21)->age;
$noonTodayLondonTime = Carbon::createFromTime(12, 0, 0, 'Europe/London');
$worldWillEnd = Carbon::createFromDate(2012, 12, 21, 'GMT');
// comparisons are always done in UTC
if (Carbon::now()->gte($worldWillEnd)) {
die();
}
if (Carbon::now()->isWeekend()) {
echo 'Party!';
}
echo Carbon::now()->subMinutes(2)->diffForHumans(); // '2 minutes ago'
// ... but also does 'from now', 'after' and 'before'
// rolling up to seconds, minutes, hours, days, months, years
$daysSinceEpoch = Carbon::createFromTimeStamp(0)->diffInDays();
For full installation instructions, documentation and code examples you should visit the repo https://github.com/briannesbitt/Carbon but with composer (or without, but why would you??) you should be up and running in seconds. If you want to see the project history, its tracked here. Feedback is welcomed.
I hate reading a readme.md file that has code errors and/or sample output that is incorrect. I tried something new with this project and wrote a quick readme parser that can lint sample source code or execute and inject the actual result into a generated readme. I'll create another post about this, but for now if you want to read more you can continue reading this in the Contributing section of the project readme.
What's up next?
There have been a few feature requests already submitted. A few users have asked for an immutable implementation. There are no definite plans, but I think a copy on write implementation would be pretty simple to layer on top. This might get in there in the future if it gets mentioned a few more times. The other feature, which was targeted at testability, was an implemention of the Delorean time travel API that allows the mocking of Time.now in Ruby. We went back and forth a bit on the implementation details and ended up closing it for lack of a satisfactory solution that wasn't confusing in the end. The idea is a good one and some implementation to allow easy mocking of Carbon::now() will get added in the future. As already mentioned feedback, ideas and code submissions are welcomed.
Why the name Carbon?
Read about Carbon Dating.
Why require PHP 5.3?
And finally just a quick note on the PHP 5.3 requirement. The implementation requires PHP 5.3+ since it makes use of DateTime::add which uses the DateInterval class and those were only introduced in 5.3 simple as that. Its also more than 3 years old so I doubt this is much of an issue for anyone.
