Introduction
Carbon * inherits PHP's * Datetime * class and jsonseriable. Therefore, the methods not covered in * carbon * but implemented in * Datetime * and JsonSerializable * can be used.
class Carbon extends DateTime implements JsonSerializable
{
//code here
}
The Carbon class is declared under the Carbon namespace. Instead of entering the complete class name each time, you can introduce a namespace.
<?php use Carbon\Carbon;
Pay special attention to whether the correct time zone is used, such as the time zone set by the system or used for all difference comparisons
$dtToronto = Carbon::create(2012, 1, 1, 0, 0, 0, 'America/Toronto'); $dtVancouver = Carbon::create(2012, 1, 1, 0, 0, 0, 'America/Vancouver'); echo $dtVancouver->diffInHours($dtToronto); //
The time comparison above is completed in the time zone of the carbon instance provided. For example, the author's time zone is Tokyo time minus 13 hours, so after 1 p.m. Carbon::now('Asia/Tokyo ') - > istoday() will return false. If the time zone is set to Tokyo time zone when calling now(), it is unreasonable to use Tokyo time zone for subsequent operations. Therefore, when comparing with the instance created by * now() *, it is completed in the current time zone by default.
Instantiation
There are several different ways to create a new Carbon instance. The first is the constructor. It overrides the parent constructor, and you'd better read the first parameter in the PHP manual and understand the date / time string format it accepts. You may find that you rarely use constructors and rely on explicit static methods to improve readability
$carbon = new Carbon(); // Equivalent to Carbon::now()
$carbon = new Carbon('first day of January 2008', 'America/Vancouver');
echo get_class($carbon); // 'Carbon\Carbon'
$carbon = Carbon::now(-5);//1 means London, England, 2 means Paris, FranceYou will notice above that the timezone(2nd) parameter is passed as a string and integer instead of a \ DateTimeZone instance. All DateTimeZone parameters have been enhanced, so you can pass a DateTimeZone instance, string, or integer offset to GMT and create a time zone for you. This is shown again in the next example, which also introduces the now() function.
$nowInLondonTz = Carbon::now(new \DateTimeZone('Europe/London'));
// Or just pass the time zone as a string
$nowInLondonTz = Carbon::now('Europe/London');
// Or create a date with a time zone of + 1 to GMT during DST, and then pass an integer
echo Carbon::now(1)->tzName; // Europe/LondonIf you really like your dynamic method calls and are disappointed with the extra lines or ugly parentheses required to use constructors, you will like the parse method.
echo (new Carbon('first day of December 2008'))->addWeeks(2); // 2008-12-15 00:00:00
echo Carbon::parse('first day of December 2008')->addWeeks(2); // 2008-12-15 00:00:00NOTE *: before PHP 5.4 * (New myclass()) - > method() will report syntax error * *. If you use * * PHP 5.3, you need to create a variable and then call the method:
$date = new Carbon('first day of December 2008');
echo $date->addWeeks(2);The string passed to Carbon:::parse or new Carbon can represent relative time (next sunday, tomorrow, first day of next month, last year) or absolute time (first day of December 2008, January 6, 2017). You can use Carbon::hasRelativeKeywords() to test whether a string produces a relative or absolute date.
$string = 'first day of next month';
if (strtotime($string) === false) {
echo "'$string' is not a valid date/time string.";
} elseif (Carbon::hasRelativeKeywords($string)) {
echo "'$string' is a relative valid date/time string, it will returns different dates depending on the current date.";
} else {
echo "'$string' is an absolute date/time string, it will always returns the same date.";
}In order to cooperate with now(), there are some static instantiation assistants to create well-known instances. The only thing to note here is that today(), tomorrow(), and yesterday() accept a time zone parameter in addition to the expected behavior, and the time value of each parameter is set to 00:00:00.
$now = Carbon::now();
echo $now; // 2018-07-26 16:25:49
$today = Carbon::today();
echo $today; // 2018-07-26 00:00:00
$tomorrow = Carbon::tomorrow('Europe/London');
echo $tomorrow; // 2018-07-27 00:00:00
$yesterday = Carbon::yesterday();
echo $yesterday; // 2018-07-25 00:00:00
The next set of static helpers is the createXXX() function. Most static create functions allow you to provide many or a few parameters and provide default values for all other parameters. Typically, the default is the current date, time, or time zone. Higher values will be properly wrapped, but invalid values will throw an InvalidArgumentException with a message. The error message is obtained from the DateTime:::getLastErrors() call.
Carbon::createFromDate($year, $month, $day, $tz);
Carbon::createFromTime($hour, $minute, $second, $tz);
Carbon::createFromTimeString("$hour:$minute:$second", $tz);
Carbon::create($year, $month, $day, $hour, $minute, $second, $tz);The default value of createFromDate() is the current time. The default value of createFromTime() is today. If create() does not pass parameters, it is also the current time. As before, $tz is set to the current time zone by default. Otherwise, it can be a DateTimeZone instance or a string time zone value. The only special case of default values (simulating the underlying PHP Library) occurs when hour values are specified but there are no minutes or seconds, they will default to 0.
Note: * * * createFromTime()** will default the date to today * *. After printing the actual combat code, I found that the default value of * * createFromTime() * * is also the current time, not today (hours, minutes and seconds are not * * 00:00:00 * *)***
$xmasThisYear = Carbon::createFromDate(null, 12, 25); // The default value of Year is this Year
$Y2K = Carbon::create(2000, 1, 1, 0, 0, 0); // Equivalent to carbon:: createmidlightdate (2000, 1, 1)
$alsoY2K = Carbon::create(1999, 12, 31, 24);
$noonLondonTz = Carbon::createFromTime(12, 0, 0, 'Europe/London');
$teaTime = Carbon::createFromTimeString('17:00:00', 'Europe/London');
// A two digit minute could not be found
try {
Carbon::create(1975, 5, 21, 22, -2, 0);
} catch(\InvalidArgumentException $x) {
echo $x->getMessage()
}Creating an exception occurs when a negative value is used instead of an overflow. To get an exception on an overflow, use createSafe()
echo Carbon::create(2000, 1, 35, 13, 0, 0);// 2000-02-04 13:00:00
//(there are 31 days in January, and 4 days are automatically added to convert to February 4)
try {
Carbon::createSafe(2000, 1, 35, 13, 0, 0);
} catch (\Carbon\Exceptions\InvalidDateException $exp) {
echo $exp->getMessage();
}
// An error will be reported: Day: 35 is not a valid valueNote1: an exception will be generated on February 29, 2018, but no exception will be generated on February 29, 2020, because 2020 is a leap year.
NOTE2:Carbon::createSafe(2014,3,30,1,30,0,’Europe/London’); Starting with PHP 5.4, an exception will also be generated because an hour is skipped during daylight saving time, but before PHP 5.4, it will only create this invalid date.
Carbon::createFromFormat($format, $time, $tz);
createFromFormat() is the wrapper for the most basic php function DateTime:::createFromFormat. The difference is that the $tz parameter can be a DateTimeZone instance or a string time zone value. In addition, if there is a format error, this function will call the DateTime::getLastErrors() method, and then throw an InvalidArgumentException as an error message. If you look at the source code of the createXX() function above, they all call createFromFormat().
echo Carbon::createFromFormat('Y-m-d H', '1975-05-21 22')->toDateTimeString(); // 1975-05-21 22:00:00The last three create functions are used to use unix timestamps. The first will create a Carbon instance equal to the given timestamp and will set the time zone or default to the current time zone. The second createFromTimestampUTC() is different because the time zone will remain UTC(GMT). The second method is the same as Carbon: createFromFormat('@'. $timestamp), but I just make it more explicit. The third is createFromTimestampMs(), which accepts timestamps in milliseconds instead of seconds. Negative timestamps are also allowed.
echo Carbon::createFromTimestamp(-1)->toDateTimeString(); // 1969-12-31 18:59:59
echo Carbon::createFromTimestamp(-1, 'Europe/London')->toDateTimeString(); // 1970-01-01 00:59:59
echo Carbon::createFromTimestampUTC(-1)->toDateTimeString(); // 1969-12-31 23:59:59
echo Carbon::createFromTimestampMs(1)->format('Y-m-d\TH:i:s.uP T'); // 1969-12-31T19:00:00.001000-05:00 EST
echo Carbon::createFromTimestampMs(1, 'Europe/London')->format('Y-m-d\TH:i:s.uP T'); // 1970-01-01T01:00:00.001000+01:00 BST
You can also copy() on an existing Carbon instance. As expected, the date, time, and time zone values are copied to the new instance.
$dt = Carbon::now(); echo $dt->diffInYears($dt->copy()->addYear()); // 1
//The $dt instance has not changed, but it is still Carbon:now()
You can use nowWithSameTz() on an existing Carbon instance to get a new instance in the same time zone.
$meeting = Carbon::createFromTime(19, 15, 00, 'Africa/Johannesburg');
// 19:15 in Johannesburg
echo 'Meeting starts at '.$meeting->format('H:i').' in Johannesburg.'; // Meeting starts at 19:15 in Johannesburg.
// now in Johannesburg
echo "It's ".$meeting->nowWithSameTz()->format('H:i').' right now in Johannesburg.'; // It's 09:37 right now in Johannesburg.
Finally, if you find yourself inheriting the \ DateTime instance from another library, don't be afraid! You can create a Carbon instance through the friendly instance() method. Or use the more flexible method make(), which can return a new Carbon instance from DateTime, Carbon or string, otherwise it will only return null.
$dt = new \DateTime('first day of January 2008'); // <== instance from another API
$carbon = Carbon::instance($dt);
echo get_class($carbon); // 'Carbon\Carbon'
echo $carbon->toDateTimeString(); // 2008-01-01 00:00:00A brief description of microseconds. The PHP DateTime object allows you to set a microsecond value, but ignores all of its dates. Carbon in 1.12.0 now supports microseconds during instantiation or copy operations, and uses the format() method by default.
$dt = Carbon::parse('1975-05-21 22:23:00.123456');
echo $dt->micro; //
echo $dt->copy()->micro; //Before PHP 7.1, DateTime microseconds were not added to the "now" instance and cannot be changed later, which means:
$date = new DateTime('now');
echo $date->format('u');
// display current microtime in PHP >= 7.1 (expect a bug in PHP 7.1.3 only)
// display 000000 before PHP 7.1
$date = new DateTime('2001-01-01T00:00:00.123456Z');
echo $date->format('u');
// display 123456 in all PHP versions
$date->modify('00:00:00.987654');
echo $date->format('u');
// display 987654 in PHP >= 7.1
// display 123456 before PHP 7.1
To solve this limitation, we called microseconds in PHP < 7.1, but this feature can be disabled when needed (PHP > 7.1):
Carbon::useMicrosecondsFallback(false); var_dump(Carbon::isMicrosecondsFallbackEnabled()); // false echo Carbon::now()->micro; // 0 in PHP < 7.1, microtime in PHP >= 7.1 Carbon::useMicrosecondsFallback(true); // default value var_dump(Carbon::isMicrosecondsFallbackEnabled()); // true echo Carbon::now()->micro; // microtime in all PHP version
Do you need to traverse some dates to find the earliest or most recent date? Don't know how to set the initial maximum / minimum value? Now there are two assistants who can help you make simple decisions:
echo Carbon::maxValue(); // '9999-12-31 23:59:59' echo Carbon::minValue(); // '0001-01-01 00:00:00'
The minimum and maximum values mainly depend on the system (32-bit or 64 bit).
Use 32-bit OS system or 32-bit version of PHP (you can use PHP_INT_SIZE == 4 to check it in PHP), the minimum value is 0-unix-timestamp(1970-01-01 00:00:00), and the maximum value is constant PHP_ INT_ The timestamp given by max.
64 bit OS system and 64 bit PHP version are used. The minimum value is 01-01 00:00 and the maximum value is 9999-12-31 23:59:59.
Localization
Unfortunately, the base class DateTime does not have any localization support. To start localization support, a formatLocalized($format) method has also been added. The implementation uses the timestamp of the current instance to call strftime. If you first set the current locale using the PHP function setlocale(), the returned string will be formatted to the correct locale.
$newLocale = setlocale(LC_TIME, 'German');
if ($newLocale === false) {
echo '"German" locale is not installed on your machine, it may have a different name a different name on your machine or you may need to install it.';
}
echo $dt->formatLocalized('%A %d %B %Y'); // Mittwoch 21 Mai 1975
setlocale(LC_TIME, 'English');
echo $dt->formatLocalized('%A %d %B %Y'); // Wednesday 21 May 1975
setlocale(LC_TIME, ''); // reset localediffForHumans() is also located. You can set Carbon locale() by using the static Carbon::setLocale() function and get the current setting by using Carbon::getLocale().
Carbon::setLocale('de');
echo Carbon::getLocale(); // de
echo Carbon::now()->addYear()->diffForHumans(); // in 1 Jahr
Carbon::setLocale('en');
echo Carbon::getLocale(); // enAlternatively, you can isolate some code from a given locale:
Carbon::executeWithLocale('de', function ($newLocale) {
// You can optionally get $newLocale as the first argument of the closure
// It will be set to the new locale or false if the locale was not found.
echo Carbon::now()->addYear()->diffForHumans();
}); // in 1 Jahr
// outside the function the locale did not change
echo Carbon::getLocale(); // en
// or same using a return statement
$french = Carbon::executeWithLocale('fr', function () {
return Carbon::now()->addYear()->diffForHumans();
});
echo $french; // dans 1 anSome languages need to print utf8 encoding (mainly locale packages ending in. Utf8). In this example, you can use the static method ` ` php
Carbon::setUtf8()Right, right utf8 Character set formatlocalized()Encode the result of the call.
setlocale(LC_TIME, 'Spanish');
$dt = Carbon::create(2016, 01, 06, 00, 00, 00);
Carbon::setUtf8(false);
echo $dt->formatLocalized('%A %d %B %Y'); // mi�rcoles 06 enero 2016
Carbon::setUtf8(true);
echo $dt->formatLocalized('%A %d %B %Y'); // miércoles 06 enero 2016
Carbon::setUtf8(false);
setlocale(LC_TIME, '');On Linux
If you have problems with translation, please check the region (local and production) installed in the system.
Locale - lists the enabled locales.
sudo locale-gen fr_FR. UTF-8 installs a new locale.
Sudo dpkg reconfigure locale to publish all enabled locales.
And restart the system.
You can customize an existing language in the following ways:
Carbon::setLocale('en');
$translator = Carbon::getTranslator();
$translator->setMessages('en', array(
'day' => ':count boring day|:count boring days',
));
$date1 = Carbon::create(2018, 1, 1, 0, 0, 0);
$date2 = Carbon::create(2018, 1, 4, 4, 0, 0);
echo $date1->diffForHumans($date2, true, false, 2); // 3 boring days 4 hours
$translator->resetMessages('en'); // reset language customizations for en languageNote that you can also use another converter, Carbon::setTranslator($custom), as long as the given converter inherits symfony \ component \ translation \ translator interface. Therefore, locale support for format localization, getters (such as localeMonth, localedayayofweek, and short variants) is driven by the locale installed in the operating system. For other translations, it is supported internally due to the support of the carbon community. You can check the supported content using the following methods:
echo implode(', ', array_slice(Carbon::getAvailableLocales(), 0, 3)).'...'; // af, ar, ar_Shakl...
// Support diff syntax (before, after, from now, ago)
var_dump(Carbon::localeHasDiffSyntax('en')); // bool(true)
var_dump(Carbon::localeHasDiffSyntax('zh_TW')); // bool(true)
// Support 1-day diff words (just now, yesterday, tomorrow)
var_dump(Carbon::localeHasDiffOneDayWords('en')); // bool(true)
var_dump(Carbon::localeHasDiffOneDayWords('zh_TW')); // bool(false)
// Support 2-days diff words (before yesterday, after tomorrow)
var_dump(Carbon::localeHasDiffTwoDayWords('en')); // bool(true)
var_dump(Carbon::localeHasDiffTwoDayWords('zh_TW')); // bool(false)
// Support short units (1y = 1 year, 1mo = 1 month, etc.)
var_dump(Carbon::localeHasShortUnits('en')); // bool(true)
var_dump(Carbon::localeHasShortUnits('zh_TW')); // bool(false)
// Support period syntax (X times, every X, from X, to X)
var_dump(Carbon::localeHasPeriodSyntax('en')); // bool(true)
var_dump(Carbon::localeHasPeriodSyntax('zh_TW')); // bool(false)The following is an overview of the 73 regions supported by the last carbon version:
Note that if you use Laravel 5.5 +, the locale will be automatically set according to the current last App:setLocale execution. So the proliferation of humans will be transparent. You may still need to run setlocale in some middleware to make format localized working correct.
Testing Aids
The test method allows you to set the Carbon instance (real or mock) to return when creating the "now" instance. The instance provided will be returned under the following conditions:
A call to the static now() method, for example
:now()
When an empty (or empty string) is passed to the constructor or parse(), ex.new carbon (empty)
When the string "now" is passed to the constructor or parse(), ex. new Carbon('Now ')
The given instance will also be the default relative time for the diff method.
$knownDate = Carbon::create(2001, 5, 21, 12); // create testing date
Carbon::setTestNow($knownDate); // set the mock (of course this could be a real mock object)
echo Carbon::getTestNow(); // 2001-05-21 12:00:00
echo Carbon::now(); // 2001-05-21 12:00:00
echo new Carbon(); // 2001-05-21 12:00:00
echo Carbon::parse(); // 2001-05-21 12:00:00
echo new Carbon('now'); // 2001-05-21 12:00:00
echo Carbon::parse('now'); // 2001-05-21 12:00:00
echo Carbon::create(2001, 4, 21, 12)->diffForHumans(); // 1 month ago
var_dump(Carbon::hasTestNow()); // bool(true)
Carbon::setTestNow(); // clear the mock
var_dump(Carbon::hasTestNow()); // bool(false)
echo Carbon::now(); // 2018-07-05 03:37:12A more meaningful and complete example:
class SeasonalProduct
{
protected $price;
public function __construct($price)
{
$this->price = $price;
}
public function getPrice() {
$multiplier = 1;
if (Carbon::now()->month == 12) {
$multiplier = 2;
}
return $this->price * $multiplier;
}
}
$product = new SeasonalProduct(100);
Carbon::setTestNow(Carbon::parse('first day of March 2000'));
echo $product->getPrice(); //
Carbon::setTestNow(Carbon::parse('first day of December 2000'));
echo $product->getPrice(); //
Carbon::setTestNow(Carbon::parse('first day of May 2000'));
echo $product->getPrice(); //
Carbon::setTestNow();Depending on the given "now" instance, the relevant phrase can also be ridiculed.
$knownDate = Carbon::create(2001, 5, 21, 12); // create testing date
Carbon::setTestNow($knownDate); // set the mock
echo new Carbon('tomorrow'); // 2001-05-22 00:00:00 ... notice the time !
echo new Carbon('yesterday'); // 2001-05-20 00:00:00
echo new Carbon('next wednesday'); // 2001-05-23 00:00:00
echo new Carbon('last friday'); // 2001-05-18 00:00:00
echo new Carbon('this thursday'); // 2001-05-24 00:00:00
Carbon::setTestNow(); // always clear it !The list of words considered relative modifiers is as follows:
- +
- -
- ago
- first
- next
- last
- this
- today
- tomorrow
- yesterday
Note that, like the next(), previous(), and modify() methods, some of these relative modifiers will set the time to 00:00.
Carbon: parse($time， $tz)and new Carbon($time， $tz)You can use the time zone as the second parameter.
echo Carbon::parse('2012-9-5 23:26:11.223', 'Europe/Paris')->timezone->getName(); // Europe/ParisGetters
The getter method is implemented in PHP__ The get() method is implemented. This enables you to access values as if they were properties rather than function calls.
$dt = Carbon::parse('2012-10-5 23:26:11.123789');
// These getter methods will return int type
var_dump($dt->year); // int(2012)
var_dump($dt->month); // int(10)
var_dump($dt->day); // int(5)
var_dump($dt->hour); // int(23)
var_dump($dt->minute); // int(26)
var_dump($dt->second); // int(11)
var_dump($dt->micro); // int(123789)
// dayOfWeek returns a number from 0 (sunday) to 6 (saturday)
var_dump($dt->dayOfWeek); // int(5)
// dayOfWeekIso returns a number from 1 (monday) to 7 (sunday)
var_dump($dt->dayOfWeekIso); // int(5)
setlocale(LC_TIME, 'German');
var_dump($dt->englishDayOfWeek); // string(6) "Friday"
var_dump($dt->shortEnglishDayOfWeek); // string(3) "Fri"
var_dump($dt->localeDayOfWeek); // string(7) "Freitag"
var_dump($dt->shortLocaleDayOfWeek); // string(2) "Fr"
var_dump($dt->englishMonth); // string(7) "October"
var_dump($dt->shortEnglishMonth); // string(3) "Oct"
var_dump($dt->localeMonth); // string(7) "Oktober"
var_dump($dt->shortLocaleMonth); // string(3) "Okt"
setlocale(LC_TIME, '');
var_dump($dt->dayOfYear); // int(278)
var_dump($dt->weekNumberInMonth);
// weekNumberInMonth consider weeks from monday to sunday, so the week 1 will
// contain 1 day if the month start with a sunday, and up to 7 if it starts with a monday
var_dump($dt->weekOfMonth); // int(1)
// weekOfMonth will returns 1 for the 7 first days of the month, then 2 from the 8th to
// the 14th, 3 from the 15th to the 21st, 4 from 22nd to 28th and 5 above
var_dump($dt->weekOfYear); // int(40)
var_dump($dt->daysInMonth); // int(31)
var_dump($dt->timestamp); // int(1349493971)
var_dump(Carbon::createFromDate(1975, 5, 21)->age); // int(43) calculated vs now in the same tz
var_dump($dt->quarter); // int(4)
// Returns an int of seconds difference from UTC (+/- sign included)
var_dump(Carbon::createFromTimestampUTC(0)->offset); // int(0)
var_dump(Carbon::createFromTimestamp(0)->offset); // int(-18000)
// Returns an int of hours difference from UTC (+/- sign included)
var_dump(Carbon::createFromTimestamp(0)->offsetHours); // int(-5)
// Indicates if day light savings time is on
var_dump(Carbon::createFromDate(2012, 1, 1)->dst); // bool(false)
var_dump(Carbon::createFromDate(2012, 9, 1)->dst); // bool(true)
// Indicates if the instance is in the same timezone as the local timezone
var_dump(Carbon::now()->local); // bool(true)
var_dump(Carbon::now('America/Vancouver')->local); // bool(false)
// Indicates if the instance is in the UTC timezone
var_dump(Carbon::now()->utc); // bool(false)
var_dump(Carbon::now('Europe/London')->utc); // bool(false)
var_dump(Carbon::createFromTimestampUTC(0)->utc); // bool(true)
// Gets the DateTimeZone instance
echo get_class(Carbon::now()->timezone); // DateTimeZone
echo get_class(Carbon::now()->tz); // DateTimeZone
// Gets the DateTimeZone instance name, shortcut for ->timezone->getName()
echo Carbon::now()->timezoneName; // America/Toronto
echo Carbon::now()->tzName; // America/TorontoSetters
The following setter is through PHP__ Implemented by the set() method. It is worth noting that except for explicitly setting the time zone, no setter will change the time zone of the instance. Specifically, setting the timestamp does not set the corresponding time zone to UTC.
$dt = Carbon::now();
$dt->year = 1975;
$dt->month = 13; //Force year + + and then month = 1
$dt->month = 5;
$dt->day = 21;
$dt->hour = 22;
$dt->minute = 32;
$dt->second = 5;
$dt->timestamp = 169957925; // This does not change the time zone
// Set the time zone through a DateTimeZone instance or string
$dt->timezone = new DateTimeZone('Europe/London');
$dt->timezone = 'Europe/London';
$dt->tz = 'Europe/London';
Fluent Setters
There are no optional parameters for setters, but there is enough diversity in the function definition so they are not needed anyway. It is worth noting that except for explicitly setting the time zone, no setter will change the time zone of the instance. Specifically, setting the timestamp does not set the corresponding time zone to UTC.
$dt = Carbon::now();
$dt->year(1975)->month(5)->day(21)->hour(22)->minute(32)->second(5)->toDateTimeString();
$dt->setDate(1975, 5, 21)->setTime(22, 32, 5)->toDateTimeString();
$dt->setDate(1975, 5, 21)->setTimeFromTimeString('22:32:05')->toDateTimeString();
$dt->setDateTime(1975, 5, 21, 22, 32, 5)->toDateTimeString();
$dt->timestamp(169957925)->timezone('Europe/London');
$dt->tz('America/Toronto')->setTimezone('America/Vancouver');You can also set the date and time separately from other DateTime/Carbon objects:
$source1 = new Carbon('2010-05-16 22:40:10');
$dt = new Carbon('2001-01-01 01:01:01');
$dt->setTimeFrom($source1);
echo $dt; // 2001-01-01 22:40:10
$source2 = new DateTime('2013-09-01 09:22:56');
$dt->setDateFrom($source2);
echo $dt; // 2013-09-01 22:40:10IsSet
The PHP function isset() is implemented. This is done when some external systems (such as Twig) verify the existence of attributes before using attributes. This is done using the isset() or empty() methods. You can read more about these on the PHP site: isset(), isset(), empty().
var_dump(isset(Carbon::now()->iDoNotExist)); // bool(false) var_dump(isset(Carbon::now()->hour)); // bool(true) var_dump(empty(Carbon::now()->iDoNotExist)); // bool(true) var_dump(empty(Carbon::now()->year)); // bool(false)
String Formatting
All available toXXXString() methods depend on the base class method DateTime: format(). You will notice__ The toString() method allows a Carbon instance to be printed as a beautiful date time string when used in a string context.
$dt = Carbon::create(1975, 12, 25, 14, 15, 16);
var_dump($dt->toDateTimeString() == $dt); // bool(true) => uses __toString()
echo $dt->toDateString(); // 1975-12-25
echo $dt->toFormattedDateString(); // Dec 25, 1975
echo $dt->toTimeString(); // 14:15:16
echo $dt->toDateTimeString(); // 1975-12-25 14:15:16
echo $dt->toDayDateTimeString(); // Thu, Dec 25, 1975 2:15 PM
// ... of course format() is still available
echo $dt->format('l jS \\of F Y h:i:s A'); // Thursday 25th of December 1975 02:15:16 PM
// The reverse hasFormat method allows you to test if a string looks like a given format
var_dump($dt->hasFormat('Thursday 25th December 1975 02:15:16 PM', 'l jS F Y h:i:s A')); // bool(true)You can also set the default__ toString() format (y-m-d by default)
s) , this is the format used when type juggling occurs.
Carbon::setToStringFormat('jS \o\f F, Y g:i:s a');
echo $dt; // 25th of December, 1975 2:15:16 pm
Carbon::resetToStringFormat();
echo $dt; // 1975-12-25 14:15:16NOTE: for localization support, see the localization section.
Common Formats
The following is a wrapper for the common format provided in the DateTime class.
$dt = Carbon::createFromFormat('Y-m-d H:i:s.u', '2019-02-01 03:45:27.612584');
// $dt->toAtomString() is the same as $dt->format(DateTime::ATOM);
echo $dt->toAtomString(); // 2019-02-01T03:45:27-05:00
echo $dt->toCookieString(); // Friday, 01-Feb-2019 03:45:27 EST
echo $dt->toIso8601String(); // 2019-02-01T03:45:27-05:00
// Be aware we chose to use the full-extended format of the ISO 8601 norm
// Natively, DateTime::ISO8601 format is not compatible with ISO-8601 as it
// is explained here in the PHP documentation:
// https://php.net/manual/class.datetime.php#datetime.constants.iso8601
// We consider it as a PHP mistake and chose not to provide method for this
// format, but you still can use it this way:
echo $dt->format(DateTime::ISO8601); // 2019-02-01T03:45:27-0500
echo $dt->toIso8601ZuluString(); // 2019-02-01T08:45:27Z
echo $dt->toRfc822String(); // Fri, 01 Feb 19 03:45:27 -0500
echo $dt->toRfc850String(); // Friday, 01-Feb-19 03:45:27 EST
echo $dt->toRfc1036String(); // Fri, 01 Feb 19 03:45:27 -0500
echo $dt->toRfc1123String(); // Fri, 01 Feb 2019 03:45:27 -0500
echo $dt->toRfc2822String(); // Fri, 01 Feb 2019 03:45:27 -0500
echo $dt->toRfc3339String(); // 2019-02-01T03:45:27-05:00
echo $dt->toRfc7231String(); // Fri, 01 Feb 2019 08:45:27 GMT
echo $dt->toRssString(); // Fri, 01 Feb 2019 03:45:27 -0500
echo $dt->toW3cString(); // 2019-02-01T03:45:27-05:00
var_dump($dt->toArray());
/*
array(12) {
["year"]=>
int(2019)
["month"]=>
int(2)
["day"]=>
int(1)
["dayOfWeek"]=>
int(5)
["dayOfYear"]=>
int(31)
["hour"]=>
int(3)
["minute"]=>
int(45)
["second"]=>
int(27)
["micro"]=>
int(612584)
["timestamp"]=>
int(1549010727)
["formatted"]=>
string(19) "2019-02-01 03:45:27"
["timezone"]=>
object(DateTimeZone)#118 (2) {
["timezone_type"]=>
int(3)
["timezone"]=>
string(15) "America/Toronto"
}
}
*/Comparison
A simple comparison is provided by the following function. Remember, the comparison is done in the UTC time zone, so things are not always what they seem.
echo Carbon::now()->tzName; // America/Toronto $first = Carbon::create(2012, 9, 5, 23, 26, 11); $second = Carbon::create(2012, 9, 5, 20, 26, 11, 'America/Vancouver'); echo $first->toDateTimeString(); // 2012-09-05 23:26:11 echo $first->tzName; // America/Toronto echo $second->toDateTimeString(); // 2012-09-05 20:26:11 echo $second->tzName; // America/Vancouver var_dump($first->eq($second)); // bool(true) var_dump($first->ne($second)); // bool(false) var_dump($first->gt($second)); // bool(false) var_dump($first->gte($second)); // bool(true) var_dump($first->lt($second)); // bool(false) var_dump($first->lte($second)); // bool(true) $first->setDateTime(2012, 1, 1, 0, 0, 0); $second->setDateTime(2012, 1, 1, 0, 0, 0); // Remember tz is 'America/Vancouver' var_dump($first->eq($second)); // bool(false) var_dump($first->ne($second)); // bool(true) var_dump($first->gt($second)); // bool(false) var_dump($first->gte($second)); // bool(false) var_dump($first->lt($second)); // bool(true) var_dump($first->lte($second)); // bool(true) // All have verbose aliases and PHP equivalent code: var_dump($first->eq($second)); // bool(false) var_dump($first->equalTo($second)); // bool(false) var_dump($first == $second); // bool(false) var_dump($first->ne($second)); // bool(true) var_dump($first->notEqualTo($second)); // bool(true) var_dump($first != $second); // bool(true) var_dump($first->gt($second)); // bool(false) var_dump($first->greaterThan($second)); // bool(false) var_dump($first > $second); // bool(false) var_dump($first->gte($second)); // bool(false) var_dump($first->greaterThanOrEqualTo($second)); // bool(false) var_dump($first >= $second); // bool(false) var_dump($first->lt($second)); // bool(true) var_dump($first->lessThan($second)); // bool(true) var_dump($first < $second); // bool(true) var_dump($first->lte($second)); // bool(true) var_dump($first->lessThanOrEqualTo($second)); // bool(true) var_dump($first <= $second); // bool(true)
These methods use the natural comparison provided by PHP $date1 == $date2, so before PHP 7.1, all methods will ignore milli / micro seconds and consider them from 7.1.
To determine whether the current instance is between the other two instances, you can use the properly named between() method. The third parameter indicates whether an equal comparison should be made. The default value is true, which determines whether its intermediate value is equal to the boundary.
$first = Carbon::create(2012, 9, 5, 1); $second = Carbon::create(2012, 9, 5, 5); var_dump(Carbon::create(2012, 9, 5, 3)->between($first, $second)); // bool(true) var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second)); // bool(true) var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second, false)); // bool(false)
WOW! Have you forgotten min() and max()? no This is also overridden by appropriately named min() and max() methods or alias names of minimum() and maximum(). As usual, if null is specified, the default parameter is now.
$dt1 = Carbon::createMidnightDate(2012, 1, 1); $dt2 = Carbon::createMidnightDate(2014, 1, 30); echo $dt1->min($dt2); // 2012-01-01 00:00:00 echo $dt1->minimum($dt2); // 2012-01-01 00:00:00 $dt1 = Carbon::createMidnightDate(2012, 1, 1); $dt2 = Carbon::createMidnightDate(2014, 1, 30); echo $dt1->max($dt2); // 2014-01-30 00:00:00 echo $dt1->maximum($dt2); // 2014-01-30 00:00:00 // now is the default param $dt1 = Carbon::createMidnightDate(2000, 1, 1); echo $dt1->max(); // 2018-07-05 03:37:12 echo $dt1->maximum(); // 2018-07-05 03:37:12 $dt1 = Carbon::createMidnightDate(2010, 4, 1); $dt2 = Carbon::createMidnightDate(2010, 3, 28); $dt3 = Carbon::createMidnightDate(2010, 4, 16); // returns the closest of two date (no matter before or after) echo $dt1->closest($dt2, $dt3); // 2010-03-28 00:00:00 echo $dt2->closest($dt1, $dt3); // 2010-04-01 00:00:00 echo $dt3->closest($dt2, $dt1); // 2010-04-01 00:00:00 // returns the farthest of two date (no matter before or after) echo $dt1->farthest($dt2, $dt3); // 2010-04-16 00:00:00 echo $dt2->farthest($dt1, $dt3); // 2010-04-16 00:00:00 . echo $dt3->farthest($dt2, $dt1); // 2010-03-28 00:00:00
In order to handle the most common cases, here are some simple help functions. I hope their names can be clearly reflected. For a method that compares in some way with now() (ex.istoday ()), now() is created in the same time zone as the instance.
$dt = Carbon::now();
$dt2 = Carbon::createFromDate(1987, 4, 23);
$dt->isSameAs('w', $dt2); // w is the date of the week, so this will return true if $dt and $dt2
// the same day of week (both monday or both sunday, etc.)
// you can use any format and combine as much as you want.
$dt->isFuture();
$dt->isPast();
$dt->isSameYear($dt2);
$dt->isCurrentYear();
$dt->isNextYear();
$dt->isLastYear();
$dt->isLongYear(); // see https://en.wikipedia.org/wiki/ISO_8601#Week_dates
$dt->isLeapYear();
$dt->isSameQuarter($dt2); // same quarter (3 months) no matter the year of the given date
$dt->isSameQuarter($dt2, true); // same quarter of the same year of the given date
/*
Alternatively, you can run Carbon::compareYearWithMonth() to compare both quarter and year by default,
In this case you can use $dt->isSameQuarter($dt2, false) to compare ignoring the year
Run Carbon::compareYearWithMonth(false) to reset to the default behavior
Run Carbon::shouldCompareYearWithMonth() to get the current setting
*/
$dt->isCurrentQuarter();
$dt->isNextQuarter(); // date is in the next quarter
$dt->isLastQuarter(); // in previous quarter
$dt->isSameMonth($dt2); // same month no matter the year of the given date
$dt->isSameMonth($dt2, true); // same month of the same year of the given date
/*
As for isSameQuarter, you can run Carbon::compareYearWithMonth() to compare both month and year by default,
In this case you can use $dt->isSameMonth($dt2, false) to compare ignoring the year
Run Carbon::compareYearWithMonth(false) to reset to the default behavior
Run Carbon::shouldCompareYearWithMonth() to get the current setting
*/
$dt->isCurrentMonth();
$dt->isNextMonth();
$dt->isLastMonth();
$dt->isWeekday();
$dt->isWeekend();
$dt->isMonday();
$dt->isTuesday();
$dt->isWednesday();
$dt->isThursday();
$dt->isFriday();
$dt->isSaturday();
$dt->isSunday();
$dt->isDayOfWeek(Carbon::SATURDAY); // is a saturday
$dt->isLastOfMonth(); // is the last day of the month
$dt->isSameDay($dt2); // Same day of same month of same year
$dt->isCurrentDay();
$dt->isYesterday();
$dt->isToday();
$dt->isTomorrow();
$dt->isNextWeek();
$dt->isLastWeek();
$dt->isSameHour($dt2);
$dt->isCurrentHour();
$dt->isSameMinute($dt2);
$dt->isCurrentMinute();
$dt->isSameSecond($dt2);
$dt->isCurrentSecond();
$dt->isStartOfDay(); // check if hour is 00:00:00
$dt->isMidnight(); // check if hour is 00:00:00 (isStartOfDay alias)
$dt->isEndOfDay(); // check if hour is 23:59:59
$dt->isMidday(); // check if hour is 12:00:00 (or other midday hour set with Carbon::setMidDayAt())
$born = Carbon::createFromDate(1987, 4, 23);
$noCake = Carbon::createFromDate(2014, 9, 26);
$yesCake = Carbon::createFromDate(2014, 4, 23);
$overTheHill = Carbon::now()->subYears(50);
var_dump($born->isBirthday($noCake)); // bool(false)
var_dump($born->isBirthday($yesCake)); // bool(true)
var_dump($overTheHill->isBirthday()); // bool(true) -> default compare it to today!Addition and Subtraction
The default DateTime provides several different ways to easily add and reduce time. There are modify(), add() and sub(). Modify () uses a magic date/time format string "last day of next month", which parses and applies the modification, while add () and sub () expect a less obvious date interval instance (for example, the new \ date interval ('P6YT5M ') will mean 6 years and 5 minutes). Hopefully, using these smooth functions will be clearer and easier to read after not seeing your code for a few weeks. Of course, I won't let you choose, because the base class functions are still available.
$dt = Carbon::create(2012, 1, 31, 0); echo $dt->toDateTimeString(); // 2012-01-31 00:00:00 echo $dt->addCenturies(5); // 2512-01-31 00:00:00 echo $dt->addCentury(); // 2612-01-31 00:00:00 echo $dt->subCentury(); // 2512-01-31 00:00:00 echo $dt->subCenturies(5); // 2012-01-31 00:00:00 echo $dt->addYears(5); // 2017-01-31 00:00:00 echo $dt->addYear(); // 2018-01-31 00:00:00 echo $dt->subYear(); // 2017-01-31 00:00:00 echo $dt->subYears(5); // 2012-01-31 00:00:00 echo $dt->addQuarters(2); // 2012-07-31 00:00:00 echo $dt->addQuarter(); // 2012-10-31 00:00:00 echo $dt->subQuarter(); // 2012-07-31 00:00:00 echo $dt->subQuarters(2); // 2012-01-31 00:00:00 echo $dt->addMonths(60); // 2017-01-31 00:00:00 echo $dt->addMonth(); // 2017-03-03 00:00:00 equivalent of $dt->month($dt->month + 1); so it wraps echo $dt->subMonth(); // 2017-02-03 00:00:00 echo $dt->subMonths(60); // 2012-02-03 00:00:00 echo $dt->addDays(29); // 2012-03-03 00:00:00 echo $dt->addDay(); // 2012-03-04 00:00:00 echo $dt->subDay(); // 2012-03-03 00:00:00 echo $dt->subDays(29); // 2012-02-03 00:00:00 echo $dt->addWeekdays(4); // 2012-02-09 00:00:00 echo $dt->addWeekday(); // 2012-02-10 00:00:00 echo $dt->subWeekday(); // 2012-02-09 00:00:00 echo $dt->subWeekdays(4); // 2012-02-03 00:00:00 echo $dt->addWeeks(3); // 2012-02-24 00:00:00 echo $dt->addWeek(); // 2012-03-02 00:00:00 echo $dt->subWeek(); // 2012-02-24 00:00:00 echo $dt->subWeeks(3); // 2012-02-03 00:00:00 echo $dt->addHours(24); // 2012-02-04 00:00:00 echo $dt->addHour(); // 2012-02-04 01:00:00 echo $dt->subHour(); // 2012-02-04 00:00:00 echo $dt->subHours(24); // 2012-02-03 00:00:00 echo $dt->addMinutes(61); // 2012-02-03 01:01:00 echo $dt->addMinute(); // 2012-02-03 01:02:00 echo $dt->subMinute(); // 2012-02-03 01:01:00 echo $dt->subMinutes(61); // 2012-02-03 00:00:00 echo $dt->addSeconds(61); // 2012-02-03 00:01:01 echo $dt->addSecond(); // 2012-02-03 00:01:02 echo $dt->subSecond(); // 2012-02-03 00:01:01 echo $dt->subSeconds(61); // 2012-02-03 00:00:00
For fun, you can also pass a negative value to addXXX(), which is actually how subXXX() is implemented. Note: if you forget and use addDay(5) or subYear(3), I support you; By default, Carbon depends on the underlying parent PHP DateTime behavior. Therefore, increasing or decreasing months may overflow, for example:
$dt = Carbon::create(2017, 1, 31, 0); echo $dt->copy()->addMonth(); // 2017-03-03 00:00:00 echo $dt->copy()->subMonths(2); // 2016-12-01 00:00:00
To prevent overflow, Carbon:usemonthverflow (false)
Carbon::useMonthsOverflow(false); $dt = Carbon::createMidnightDate(2017, 1, 31); echo $dt->copy()->addMonth(); // 2017-02-28 00:00:00 echo $dt->copy()->subMonths(2); // 2016-11-30 00:00:00 // Call the method with true to allow overflow again Carbon::resetMonthsOverflow(); // same as Carbon::useMonthsOverflow(true);
The method Carbon:::shouldOverflowMonths() allows you to know whether overflow is currently enabled. You can also use - > addmonthsnooverflow, - > submonthsnooverflow, - > addmonthswithoverflow, - > submonth withoverflow (or singular method, excluding s to "month") to explicitly add/sub. you can add or not add overflow regardless of the current mode.
Carbon::useMonthsOverflow(false); $dt = Carbon::createMidnightDate(2017, 1, 31); echo $dt->copy()->addMonthWithOverflow(); // 2017-03-03 00:00:00 // plural addMonthsWithOverflow() method is also available echo $dt->copy()->subMonthsWithOverflow(2); // 2016-12-01 00:00:00 // singular subMonthWithOverflow() method is also available echo $dt->copy()->addMonthNoOverflow(); // 2017-02-28 00:00:00 // plural addMonthsNoOverflow() method is also available echo $dt->copy()->subMonthsNoOverflow(2); // 2016-11-30 00:00:00 // singular subMonthNoOverflow() method is also available echo $dt->copy()->addMonth(); // 2017-02-28 00:00:00 echo $dt->copy()->subMonths(2); // 2016-11-30 00:00:00 Carbon::useMonthsOverflow(true); $dt = Carbon::createMidnightDate(2017, 1, 31); echo $dt->copy()->addMonthWithOverflow(); // 2017-03-03 00:00:00 echo $dt->copy()->subMonthsWithOverflow(2); // 2016-12-01 00:00:00 echo $dt->copy()->addMonthNoOverflow(); // 2017-02-28 00:00:00 echo $dt->copy()->subMonthsNoOverflow(2); // 2016-11-30 00:00:00 echo $dt->copy()->addMonth(); // 2017-03-03 00:00:00 echo $dt->copy()->subMonths(2); // 2016-12-01 00:00:00 Carbon::resetMonthsOverflow();
Starting with version 1.23.0, overflow control can also be used in the following years:
Carbon::useYearsOverflow(false); $dt = Carbon::createMidnightDate(2020, 2, 29); var_dump(Carbon::shouldOverflowYears()); // bool(false) echo $dt->copy()->addYearWithOverflow(); // 2021-03-01 00:00:00 // plural addYearsWithOverflow() method is also available echo $dt->copy()->subYearsWithOverflow(2); // 2018-03-01 00:00:00 // singular subYearWithOverflow() method is also available echo $dt->copy()->addYearNoOverflow(); // 2021-02-28 00:00:00 // plural addYearsNoOverflow() method is also available echo $dt->copy()->subYearsNoOverflow(2); // 2018-02-28 00:00:00 // singular subYearNoOverflow() method is also available echo $dt->copy()->addYear(); // 2021-02-28 00:00:00 echo $dt->copy()->subYears(2); // 2018-02-28 00:00:00 Carbon::useYearsOverflow(true); $dt = Carbon::createMidnightDate(2020, 2, 29); var_dump(Carbon::shouldOverflowYears()); // bool(true) echo $dt->copy()->addYearWithOverflow(); // 2021-03-01 00:00:00 echo $dt->copy()->subYearsWithOverflow(2); // 2018-03-01 00:00:00 echo $dt->copy()->addYearNoOverflow(); // 2021-02-28 00:00:00 echo $dt->copy()->subYearsNoOverflow(2); // 2018-02-28 00:00:00 echo $dt->copy()->addYear(); // 2021-03-01 00:00:00 echo $dt->copy()->subYears(2); // 2018-03-01 00:00:00 Carbon::resetYearsOverflow();
Difference
Since Carbon inherits DateTime, it inherits its methods, such as diff(), which takes the second date object as a parameter and returns an instance of DateInterval.
We also provide diffAsCarbonInterval(), which is similar to diff(), but returns an instance of CarbonInterval. Check the CarbonInterval section for more information. Diff methods are added to the Carbon of each cell, such as diffInYears(), diffInMonths(). The diffAsCarbonInterval() and diffIn * () methods can use two optional parameters: date to compare with (if missing, now is the default value), and an absolute Boolean option (the default is true). No matter which date is greater than the other, the method returns an absolute value. If set to false, a negative value is returned when the instance of the calling method is greater than the comparison date (first parameter or now). Note that the diff () prototype is different: its first parameter (date) is mandatory, and its second parameter (absolute option) defaults to false.
These functions always return the total difference expressed in a specified time. This is different from the diff() function of the base class, which has a time interval of 122 seconds and returns 2 minutes and 2 seconds through the DateInterval instance. The diffInMinutes() function returns only 2, while diffInSeconds() returns 122. All values are truncated rather than rounded. Each of the following functions has a default first parameter, which is the Carbon instance to compare. If you want to use now(), it is null. The second parameter is also optional. If you want the return value to be an absolute value, or if the date passed is less than the current instance, the return value may have a relative value with a - (negative) sign. This defaults to true and returns an absolute value.
echo Carbon::now('America/Vancouver')->diffInSeconds(Carbon::now('Europe/London')); //
$dtOttawa = Carbon::createMidnightDate(2000, 1, 1, 'America/Toronto');
$dtVancouver = Carbon::createMidnightDate(2000, 1, 1, 'America/Vancouver');
echo $dtOttawa->diffInHours($dtVancouver); //
echo $dtVancouver->diffInHours($dtOttawa); //
echo $dtOttawa->diffInHours($dtVancouver, false); //
echo $dtVancouver->diffInHours($dtOttawa, false); // -3
$dt = Carbon::createMidnightDate(2012, 1, 31);
echo $dt->diffInDays($dt->copy()->addMonth()); //
echo $dt->diffInDays($dt->copy()->subMonth(), false); // -31
$dt = Carbon::createMidnightDate(2012, 4, 30);
echo $dt->diffInDays($dt->copy()->addMonth()); //
echo $dt->diffInDays($dt->copy()->addWeek()); //
$dt = Carbon::createMidnightDate(2012, 1, 1);
echo $dt->diffInMinutes($dt->copy()->addSeconds(59)); //
echo $dt->diffInMinutes($dt->copy()->addSeconds(60)); //
echo $dt->diffInMinutes($dt->copy()->addSeconds(119)); //
echo $dt->diffInMinutes($dt->copy()->addSeconds(120)); //
echo $dt->addSeconds(120)->secondsSinceMidnight(); //
$interval = $dt->diffAsCarbonInterval($dt->copy()->subYears(3), false);
echo ($interval->invert ? 'minus ' : 'plus ') . $interval->years; // minus 3Important note about daylight saving time (DST). By default, PHP DateTime does not consider DST, which means that a day with only 23 hours, such as March 30, 2014, will be calculated as 24 hours in London.
$date = new DateTime('2014-03-30 00:00:00', new DateTimeZone('Europe/London')); // DST off
echo $date->modify('+25 hours')->format('H:i'); // 01:00 (DST on, 24 hours only have been actually added)Carbon also follows this behavior, increasing / decreasing / decreasing seconds / minutes / hours. However, we provide a way to use timestamp for real-time work:
$date = new Carbon('2014-03-30 00:00:00', 'Europe/London'); // DST off
echo $date->addRealHours(25)->format('H:i'); // 02:00 (DST on)
echo $date->diffInRealHours('2014-03-30 00:00:00'); //
echo $date->diffInHours('2014-03-30 00:00:00'); //
echo $date->diffInRealMinutes('2014-03-30 00:00:00'); //
echo $date->diffInMinutes('2014-03-30 00:00:00'); //
echo $date->diffInRealSeconds('2014-03-30 00:00:00'); //
echo $date->diffInSeconds('2014-03-30 00:00:00'); //
echo $date->subRealHours(25)->format('H:i'); // 00:00 (DST off)The same method can use addRealMinutes(), subRealMinutes(), addRealSeconds(), subRealSeconds() and all their unique shortcuts: addRealHour(), subRealHour(), addrealmin(), subRealMinute(), addRealSecond(), subRealSecond().
There are also special filter functions diffindaysfilter(), diffinhoursfilter(), and difffilter(), to help you filter differences by days, hours, or custom intervals. For example, calculate the weekend days between two instances:
$dt = Carbon::create(2014, 1, 1);
$dt2 = Carbon::create(2014, 12, 31);
$daysForExtraCoding = $dt->diffInDaysFiltered(function(Carbon $date) {
return $date->isWeekend();
}, $dt2);
echo $daysForExtraCoding; //
$dt = Carbon::create(2014, 1, 1)->endOfDay();
$dt2 = $dt->copy()->startOfDay();
$littleHandRotations = $dt->diffFiltered(CarbonInterval::minute(), function(Carbon $date) {
return $date->minute === 0;
}, $dt2, true); // true as last parameter returns absolute value
echo $littleHandRotations; //
$date = Carbon::now()->addSeconds(3666);
echo $date->diffInSeconds(); //
echo $date->diffInMinutes(); //
echo $date->diffInHours(); //
echo $date->diffInDays(); //
$date = Carbon::create(2016, 1, 5, 22, 40, 32);
echo $date->secondsSinceMidnight(); //
echo $date->secondsUntilEndOfDay(); //
$date1 = Carbon::createMidnightDate(2016, 1, 5);
$date2 = Carbon::createMidnightDate(2017, 3, 15);
echo $date1->diffInDays($date2); //
echo $date1->diffInWeekdays($date2); //
echo $date1->diffInWeekendDays($date2); //
echo $date1->diffInWeeks($date2); //
echo $date1->diffInMonths($date2); //
echo $date1->diffInYears($date2); //All diffIn * filtering methods use a callable filter as the necessary parameter and a date object as the optional second parameter. If it is missing, use now. You can also pass true as the third parameter to get an absolute value.
For advanced processing of the week / weekend, use the following tools:
echo implode(', ', Carbon::getDays()); // Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
$saturday = new Carbon('first saturday of 2019');
$sunday = new Carbon('first sunday of 2019');
$monday = new Carbon('first monday of 2019');
echo implode(', ', Carbon::getWeekendDays()); // 6, 0
var_dump($saturday->isWeekend()); // bool(true)
var_dump($sunday->isWeekend()); // bool(true)
var_dump($monday->isWeekend()); // bool(false)
Carbon::setWeekendDays(array(
Carbon::SUNDAY,
Carbon::MONDAY,
)); //Customize weekend
echo implode(', ', Carbon::getWeekendDays()); // 0, 1
var_dump($saturday->isWeekend()); // bool(false), return false on Saturday
var_dump($sunday->isWeekend()); // bool(true)
var_dump($monday->isWeekend()); // bool(true), return true on Monday
Carbon::setWeekendDays(array(
Carbon::SATURDAY,
Carbon::SUNDAY,
));
// weekend days and start/end of week or not linked
Carbon::setWeekStartsAt(Carbon::FRIDAY);
Carbon::setWeekEndsAt(Carbon::WEDNESDAY); // and it does not need neither to precede the start
var_dump(Carbon::getWeekStartsAt() === Carbon::FRIDAY); // bool(true)
var_dump(Carbon::getWeekEndsAt() === Carbon::WEDNESDAY); // bool(true)
echo $saturday->copy()->startOfWeek()->toRfc850String(); // Friday, 06-Jul-18 00:00:00 EDT
echo $saturday->copy()->endOfWeek()->toRfc850String(); // Wednesday, 11-Jul-18 23:59:59 EDT
Carbon::setWeekStartsAt(Carbon::MONDAY);
Carbon::setWeekEndsAt(Carbon::SUNDAY);
echo $saturday->copy()->startOfWeek()->toRfc850String(); // Monday, 02-Jul-18 00:00:00 EDT
echo $saturday->copy()->endOfWeek()->toRfc850String(); // Sunday, 08-Jul-18 23:59:59 EDTDifference for Humans
For humans, it was easier to read a month ago than 30 days ago. This is a common function in most date libraries, so I also want to add it here. The only parameter of the function is another Carbon instance to diff. Of course, if it is not specified, it defaults to now().
This method adds a phrase after the difference relative to the instance and the difference passed in to the instance. There are four possibilities:
When comparing past values with current defaults:
1 hour ago
Five months ago
When comparing future values with current defaults:
One hour from now
Five months from now
When comparing one past value with another:
First 1 hour
Five months ago
When comparing a future value with another value:
After 1 hour
After 5 months
You can also pass true as the second parameter to remove modifiers from now on, and so on: diffforhuman ($other, true).
If available in your locale: diffforhuman ($other, false, true), you can pass true as the third parameter to it to use short syntax.
You can pass a number between 1 and 6 as the fourth parameter to diffforhuman ($other, false, false, 4).
$other instance can be DateTime, Carbon instance or any object that implements DateTimeInterface. If a string is passed, it will be resolved to obtain a Carbon instance. If null is passed, Carbon: now() will be used.
// The most typical usage is for comments
// The instance is the date the comment was created and its being compared to default now()
echo Carbon::now()->subDays(5)->diffForHumans(); // 5 days ago
echo Carbon::now()->diffForHumans(Carbon::now()->subYear()); // 1 year after
$dt = Carbon::createFromDate(2011, 8, 1);
echo $dt->diffForHumans($dt->copy()->addMonth()); // 1 month before
echo $dt->diffForHumans($dt->copy()->subMonth()); // 1 month after
echo Carbon::now()->addSeconds(5)->diffForHumans(); // 5 seconds from now
echo Carbon::now()->subDays(24)->diffForHumans(); // 3 weeks ago (21-27 all return this. The unit of a week is 7 days. If it is less than 7, it is directly rounded off)
echo Carbon::now()->subDays(24)->diffForHumans(null, true); // 3 weeks (21-27 all return this. The unit of a week is 7 days, which is directly rounded off if it is less than 7)
echo Carbon::parse('2019-08-03')->diffForHumans('2019-08-13'); // 1 week before (the interval is 7-13 days, and the unit of a week is 7 days, which is directly rounded off if it is less than 7)
echo Carbon::parse('2000-01-01 00:50:32')->diffForHumans('@946684800'); // 5 hours after
echo Carbon::create(2018, 2, 26, 4, 29, 43)->diffForHumans(Carbon::create(2016, 6, 21, 0, 0, 0), false, false, 6); // 1 year 8 months 5 days 4 hours 29 minutes 43 seconds afterYou can also use Carbon::setLocale('fr ') to change the locale of the string before calling diffforhuman(). See the localization section for more details.
The diffforhuman() option can be enabled / disabled in the following ways:
Carbon::enableHumanDiffOption(Carbon::NO_ZERO_DIFF); var_dump((bool) (Carbon::getHumanDiffOptions() & Carbon::NO_ZERO_DIFF)); // bool(true) Carbon::disableHumanDiffOption(Carbon::NO_ZERO_DIFF); var_dump((bool) (Carbon::getHumanDiffOptions() & Carbon::NO_ZERO_DIFF)); // bool(false)
The available options are:
Carbon::NO_ZERO_DIFF(Enabled by default):Will empty diff Change to 1 second Carbon::JUST_NOW It is disabled by default):From now on, it will become "just now" Carbon:ONE_DAY_WORDS(Disabled by default):"From now on"/"1 day before" becomes "yesterday"/"Tomorrow" Carbon::TWO_DAY_WORDS(Disabled by default):"From now on"/"2 days before" becomes "yesterday"/After "
Carbon::JUST_NOW，Carbon::ONE_DAY_WORDS and Carbon::TWO_DAY_WORDS can only use en and fr languages now. Other languages will revert to their previous behavior until the missing translation is added.
Use the pipe operator to enable / disable multiple options at once, such as:ONE_DAY_WORDS | Carbon::TWO_DAY_WORDS
You can also use setHumanDiffOptions($options) to disable all options and then activate only the options passed as parameters.
Modifiers
These method groups make useful modifications to the current instance. The names of most of them are self-evident... Or at least they should be. You will also notice that the startOfXXX(), next(), and previous() methods set the time to 00:00 and the endofxxx () method to 23:59:59.
The only slight difference is the average() function. It moves the instance to an intermediate date between itself and the carbon parameters provided.
$dt = Carbon::create(2012, 1, 31, 15, 32, 45);
echo $dt->startOfMinute(); // 2012-01-31 15:32:00
$dt = Carbon::create(2012, 1, 31, 15, 32, 45);
echo $dt->endOfMinute(); // 2012-01-31 15:32:59
$dt = Carbon::create(2012, 1, 31, 15, 32, 45);
echo $dt->startOfHour(); // 2012-01-31 15:00:00
$dt = Carbon::create(2012, 1, 31, 15, 32, 45);
echo $dt->endOfHour(); // 2012-01-31 15:59:59
$dt = Carbon::create(2012, 1, 31, 15, 32, 45);
echo Carbon::getMidDayAt(); // 12 get noon time
echo $dt->midDay(); // 2012-01-31 12:00:00
Carbon::setMidDayAt(13); //Set the noon time to 13 o'clock
echo Carbon::getMidDayAt(); //
echo $dt->midDay(); // 2012-01-31 13:00:00
Carbon::setMidDayAt(12);
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfDay(); // 2012-01-31 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfDay(); // 2012-01-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfMonth(); // 2012-01-01 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfMonth(); // 2012-01-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfYear(); // 2012-01-01 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfYear(); // 2012-12-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfDecade(); // 2010-01-01 00:00:00 the beginning of the decade ("age?") 199020000102010
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfDecade(); // 2019-12-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfCentury(); // 2001-01-01 00:00:00 the beginning of the century? Why not 2000-01-01 00:00:00??? Maybe this is the definition of foreigners
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfCentury(); // 2100-12-31 23:59:59 the end of the century? Why not 2099-12-31 23:59:59???
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfWeek(); // 2012-01-30 00:00:00
var_dump($dt->dayOfWeek == Carbon::MONDAY); // Bool (true): iso8601 week starts on Monday. According to the iso8601 standard, the beginning of each week is Monday. Foreigners seem to think that the beginning of each week is Sunday
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfWeek(); // 2012-02-05 23:59:59
var_dump($dt->dayOfWeek == Carbon::SUNDAY); // bool(true) : ISO8601 week ends on Sunday
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->next(Carbon::WEDNESDAY); // On February 1, 2012, at 00:00:00, the parameter passed means "next Wednesday", and the parameter not passed means "tomorrow"
var_dump($dt->dayOfWeek == Carbon::WEDNESDAY); // bool(true)
$dt = Carbon::create(2012, 1, 1, 12, 0, 0);
echo $dt->next(); // 2012-01-08 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->previous(Carbon::WEDNESDAY); // On January 25, 2012, at 00:00:00, the parameter passed means "last Wednesday", and the parameter not passed means "yesterday"
var_dump($dt->dayOfWeek == Carbon::WEDNESDAY); // bool(true)
$dt = Carbon::create(2012, 1, 1, 12, 0, 0);
echo $dt->previous(); // 2011-12-25 00:00:00
$start = Carbon::create(2014, 1, 1, 0, 0, 0);
$end = Carbon::create(2014, 1, 30, 0, 0, 0);
echo $start->average($end); // 2014-01-15 12:00:00 (1+30)/2 = 15 int operation
echo Carbon::create(2014, 5, 30, 0, 0, 0)->firstOfMonth(); // 2014-05-01 00:00:00 the first day of this month
echo Carbon::create(2014, 5, 30, 0, 0, 0)->firstOfMonth(Carbon::MONDAY); // 2014-05-05 00:00:00 the first Monday of this month
echo Carbon::create(2014, 5, 30, 0, 0, 0)->lastOfMonth(); // 2014-05-31 00:00:00 the last day of this month
echo Carbon::create(2014, 5, 30, 0, 0, 0)->lastOfMonth(Carbon::TUESDAY); // 2014-05-27 00:00:00 the last Tuesday of this month
echo Carbon::create(2014, 5, 30, 0, 0, 0)->nthOfMonth(2, Carbon::SATURDAY); // 2014-05-10 00:00:00 the "2nd" Saturday of this month. 2 and Saturday are parameters
echo Carbon::create(2014, 5, 30, 0, 0, 0)->firstOfQuarter(); // 2014-04-01 00:00:00 the first day of this quarter (May is the second quarter, so it is April 1)
echo Carbon::create(2014, 5, 30, 0, 0, 0)->firstOfQuarter(Carbon::MONDAY); // 2014-04-07 00:00:00 the first Monday of this quarter
echo Carbon::create(2014, 5, 30, 0, 0, 0)->lastOfQuarter(); // 2014-06-30 00:00:00 the last day of this quarter
echo Carbon::create(2014, 5, 30, 0, 0, 0)->lastOfQuarter(Carbon::TUESDAY); // 2014-06-24 00:00:00 the last Tuesday of this quarter
echo Carbon::create(2014, 5, 30, 0, 0, 0)->nthOfQuarter(2, Carbon::SATURDAY); // 2014-04-12 00:00:00 the "2nd" Saturday of this quarter, and Saturday and Saturday are parameters
echo Carbon::create(2014, 5, 30, 0, 0, 0)->startOfQuarter(); // 2014-04-01 00:00:00 the beginning of this quarter
echo Carbon::create(2014, 5, 30, 0, 0, 0)->endOfQuarter(); // 2014-06-30 23:59:59 end of the quarter
echo Carbon::create(2014, 5, 30, 0, 0, 0)->firstOfYear(); // 2014-01-01 00:00:00 ditto
echo Carbon::create(2014, 5, 30, 0, 0, 0)->firstOfYear(Carbon::MONDAY); // 2014-01-06 00:00:00
echo Carbon::create(2014, 5, 30, 0, 0, 0)->lastOfYear(); // 2014-12-31 00:00:00
echo Carbon::create(2014, 5, 30, 0, 0, 0)->lastOfYear(Carbon::TUESDAY); // 2014-12-30 00:00:00
echo Carbon::create(2014, 5, 30, 0, 0, 0)->nthOfYear(2, Carbon::SATURDAY); // 2014-01-11 00:00:00
echo Carbon::create(2018, 2, 23, 0, 0, 0)->nextWeekday(); // 2018-02-26 00:00:00 next Monday
echo Carbon::create(2018, 2, 23, 0, 0, 0)->previousWeekday(); // 2018-02-22 00:00:00 last working day of the week
echo Carbon::create(2018, 2, 21, 0, 0, 0)->nextWeekendDay(); // 2018-02-24 00:00:00 the first day of the upcoming weekend (i.e. Saturday of this week. If today is Saturday, the result is Sunday)
echo Carbon::create(2018, 2, 21, 0, 0, 0)->previousWeekendDay(); // 2018-02-18 00:00:00 the last weekend just passed (i.e. Sunday of the previous week. If today is Sunday, the result is Saturday)Constants
The following constants are defined in Carbon.
// These getters specifically return integers, ie intval()
var_dump(Carbon::SUNDAY); // int(0)
var_dump(Carbon::MONDAY); // int(1)
var_dump(Carbon::TUESDAY); // int(2)
var_dump(Carbon::WEDNESDAY); // int(3)
var_dump(Carbon::THURSDAY); // int(4)
var_dump(Carbon::FRIDAY); // int(5)
var_dump(Carbon::SATURDAY); // int(6)
var_dump(Carbon::YEARS_PER_CENTURY); // int(100)
var_dump(Carbon::YEARS_PER_DECADE); // int(10)
var_dump(Carbon::MONTHS_PER_YEAR); // int(12)
var_dump(Carbon::WEEKS_PER_YEAR); // int(52)
var_dump(Carbon::DAYS_PER_WEEK); // int(7)
var_dump(Carbon::HOURS_PER_DAY); // int(24)
var_dump(Carbon::MINUTES_PER_HOUR); // int(60)
var_dump(Carbon::SECONDS_PER_MINUTE); // int(60)
$dt = Carbon::createFromDate(2012, 10, 6);
if ($dt->dayOfWeek === Carbon::SATURDAY) {
echo 'Place bets on Ottawa Senators Winning!';
}Serialization
Carbon instances can be serialized.
$dt = Carbon::create(2012, 12, 25, 20, 30, 00, 'Europe/Moscow');
echo serialize($dt); // O:13:"Carbon\Carbon":3:{s:4:"date";s:26:"2012-12-25 20:30:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:13:"Europe/Moscow";}
// Equivalent to:
echo $dt->serialize(); // O:13:"Carbon\Carbon":3:{s:4:"date";s:26:"2012-12-25 20:30:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:13:"Europe/Moscow";}
$dt = 'O:13:"Carbon\Carbon":3:{s:4:"date";s:26:"2012-12-25 20:30:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:13:"Europe/Moscow";}';
echo unserialize($dt)->format('Y-m-d\TH:i:s.uP T'); // 2012-12-25T20:30:00.000000+04:00 MSK
// Equivalent to:
echo Carbon::fromSerialized($dt)->format('Y-m-d\TH:i:s.uP T'); // 2012-12-25T20:30:00.000000+04:00 MSKJSON
Carbon instances can be encoded and decoded from JSON (these features can only be obtained from PHP 5.4 +, see the notes on PHP 5.3 below).
$dt = Carbon::create(2012, 12, 25, 20, 30, 00, 'Europe/Moscow');
echo json_encode($dt);
// {"date":"2012-12-25 20:30:00.000000","timezone_type":3,"timezone":"Europe\/Moscow"}
$json = '{"date":"2012-12-25 20:30:00.000000","timezone_type":3,"timezone":"Europe\/Moscow"}';
$dt = Carbon::__set_state(json_decode($json, true));
echo $dt->format('Y-m-d\TH:i:s.uP T');
// 2012-12-25T20:30:00.000000+04:00 MSKYou can use serializeUsing() to customize serialization.
$dt = Carbon::create(2012, 12, 25, 20, 30, 00, 'Europe/Moscow');
Carbon::serializeUsing(function ($date) {
return $date->getTimestamp();
});
echo json_encode($dt);
/*
1356453000
*/
// Call serializeUsing with null to reset the serializer:
Carbon::serializeUsing(null);The jsonSerialize() method returns an intermediate, which is converted to a string through "json_encode", which also allows you to use PHP 5.3 compatibility.
$dt = Carbon::create(2012, 12, 25, 20, 30, 00, 'Europe/Moscow');
echo json_encode($dt->jsonSerialize());
// {"date":"2012-12-25 20:30:00.000000","timezone_type":3,"timezone":"Europe\/Moscow"}
// This is equivalent to the first json_encode example but works with PHP 5.3.
// And it can be used separately:
var_dump($dt->jsonSerialize());
// array(3) {
["date"]=>
string(26) "2012-12-25 20:30:00.000000"
["timezone_type"]=>
int(3)
["timezone"]=>
string(13) "Europe/Moscow"
}Macro
If you are used to using Laravel and objects (such as responses or collections), you may be familiar with this macro concept. Carbon macro() works in the same way as Laravel macro. It takes the method name as the first parameter and the closure as the second parameter. This allows the closure operation to be used as a method with a given name on all carbon instances (also as a Carbon static method).
In PHP 5.4, $this can be used to reference the current instance in closures. For PHP 5.3 compatibility, we also added a "$self" attribute to closures. example:
Carbon::macro('diffFromYear', function ($year, $self = null) {
// This block is designed to be compatible with PHP version < 5.4 and Laravel on a separate Carbon
if (!isset($self) && isset($this)) {
$self = $this;
}
//End of compatibility block.
return $self->diffForHumans(Carbon::create($year, 1, 1, 0, 0, 0), false, false, 3);
});
echo Carbon::parse('2020-01-12 12:00:00')->diffFromYear(2019); // 1 year 1 week 4 days afterThe compatibility block allows you to ensure full compatibility of macros. A macro about Illuminate\Support\Carbon (Laravel wrapper class) will not be defined. As mentioned above in PHP 5.3 $this, this will not be defined. To make the macro work anywhere, just paste the if statement to test if it is defined instead of $self, then copy it, and then use $self in the function body.
Whether you omit some optional parameters or not, as long as $self has this name and is the last parameter:
Carbon::macro('diffFromYear', function ($year, $absolute = false, $short = false, $parts = 1, $self = null) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
return $self->diffForHumans(Carbon::create($year, 1, 1, 0, 0, 0), $absolute, $short, $parts);
});
echo Carbon::parse('2020-01-12 12:00:00')->diffFromYear(2019); // 1 year after
echo Carbon::parse('2020-01-12 12:00:00')->diffFromYear(2019, true); // 1 year
echo Carbon::parse('2020-01-12 12:00:00')->diffFromYear(2019, true, true); // 1yr
echo Carbon::parse('2020-01-12 12:00:00')->diffFromYear(2019, true, true, 5); // 1yr 1w 4d 12hYou can also group macros into classes and apply them with mixin()
Class BeerDayCarbonMixin
{
public function nextBeerDay()
{
return function ($self = null) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
return $self->modify('next wednesday');
};
}
public function previousBeerDay()
{
return function ($self = null) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
return $self->modify('previous wednesday');
};
}
}
Carbon::mixin(new BeerDayCarbonMixin());
$date = Carbon::parse('First saturday of December 2018');
echo $date->previousBeerDay(); // 2018-11-28 00:00:00
echo $date->nextBeerDay(); // 2018-12-05 00:00:00You can use hasMacro() to check whether macros (including mixins) are available
var_dump(Carbon::hasMacro('previousBeerDay')); // bool(true)
var_dump(Carbon::hasMacro('diffFromYear')); // bool(true)
var_dump(Carbon::hasMacro('dontKnowWhat')); // bool(false)Guess what? All macro methods can also be used on CarbonInterval and CarbonPeriod classes.
CarbonInterval::macro('twice', function ($self = null) {
return $self->times(2);
});
echo CarbonInterval::day()->twice()->forHumans(); // 2 days
echo CarbonInterval::hours(2)->minutes(15)->twice()->forHumans(true); // 4h 30m
CarbonPeriod::macro('countWeekdays', function ($self = null) {
return $self->filter('isWeekday')->count();
});
echo CarbonPeriod::create('2017-11-01', '2017-11-30')->countWeekdays(); //
echo CarbonPeriod::create('2017-12-01', '2017-12-31')->countWeekdays(); //Here are some useful macros from the community:
Carbon::macro('isHoliday', function ($self = null) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
return in_array($self->format('d/m'), [
'25/12', // Christmas
'01/01', // New Year
// ...
]);
});
var_dump(Carbon::createMidnightDate(2012, 12, 25)->isHoliday()); // bool(true)
var_dump(Carbon::createMidnightDate(2017, 6, 25)->isHoliday()); // bool(false)
var_dump(Carbon::createMidnightDate(2021, 1, 1)->isHoliday()); // bool(true)
Check cmixin / business day for a more complete business day handler.
Class CurrentDaysCarbonMixin
{
/**
* Get the all dates of week
. *
* [[@return](https://learnku.com/users/31554)](https://learnku.com/users/31554) array
*/
public static function getCurrentWeekDays()
{
return function ($self = null) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
$startOfWeek = ($self ?: static::now())->startOfWeek()->subDay();
$weekDays = array();
for ($i = 0; $i < static::DAYS_PER_WEEK; $i++) {
$weekDays[] = $startOfWeek->addDay()->startOfDay()->copy();
}
return $weekDays;
};
}
/**
* Get the all dates of month
*
*/
public static function getCurrentMonthDays()
{
return function ($self = null) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
$startOfMonth = ($self ?: static::now())->startOfMonth()->subDay();
$endOfMonth = ($self ?: static::now())->endOfMonth()->format('d');
$monthDays = array();
for ($i = 0; $i < $endOfMonth; $i++)
{
$monthDays[] = $startOfMonth->addDay()->startOfDay()->copy();
}
return $monthDays;
};
}
}
Carbon::mixin(new CurrentDaysCarbonMixin());
function dumpDateList($dates) {
echo substr(implode(', ', $dates), 0, 100).'...';
}
dumpDateList(Carbon::getCurrentWeekDays()); // 2018-07-02 00:00:00, 2018-07-03 00:00:00, 2018-07-04 00:00:00, 2018-07-05 00:00:00, 2018-07-06 00:00...
dumpDateList(Carbon::getCurrentMonthDays()); // 2018-07-01 00:00:00, 2018-07-02 00:00:00, 2018-07-03 00:00:00, 2018-07-04 00:00:00, 2018-07-05 00:00...
dumpDateList(Carbon::now()->subMonth()->getCurrentWeekDays()); // 2018-06-04 00:00:00, 2018-06-05 00:00:00, 2018-06-06 00:00:00, 2018-06-07 00:00:00, 2018-06-08 00:00...
dumpDateList(Carbon::now()->subMonth()->getCurrentMonthDays()); // 2018-06-01 00:00:00, 2018-06-02 00:00:00, 2018-06-03 00:00:00, 2018-06-04 00:00:00, 2018-06-05 00:00...
Carbon::macro('toAtomStringWithNoTimezone', function ($self = null) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
return $self->format('Y-m-d\TH:i:s');
});
echo Carbon::parse('2021-06-16 20:08:34')->toAtomStringWithNoTimezone(); // 2021-06-16T20:08:34
*Credit: afrojuju1 (#1063).*
Carbon::macro('easterDate', function ($year) {
return Carbon::createMidnightDate($year, 3, 21)->addDays(easter_days($year));
});
echo Carbon::easterDate(2015)->format('d/m'); // 05/04
echo Carbon::easterDate(2016)->format('d/m'); // 27/03
echo Carbon::easterDate(2017)->format('d/m'); // 16/04
echo Carbon::easterDate(2018)->format('d/m'); // 01/04
echo Carbon::easterDate(2019)->format('d/m'); // 21/04
View cmixin / weekdays for a more complete holiday handler.
Carbon::macro('range', function ($startDate, $endDate) {
return new DatePeriod($startDate, new DateInterval('P1D'), $endDate);
});
foreach (Carbon::range(Carbon::createMidnightDate(2019, 3, 28), Carbon::createMidnightDate(2019, 4, 3)) as $date) {
echo "$date\n";
}
/*
2019-03-28 00:00:00
2019-03-29 00:00:00
2019-03-30 00:00:00
2019-03-31 00:00:00
. 2019-04-01 00:00:00
2019-04-02 00:00:00
*/
class UserTimezoneCarbonMixin
{
public $userTimeZone;
/**
* Set user timezone, will be used before format function to apply current user timezone
*
* @param $timezone
*/
public function setUserTimezone()
{
$mixin = $this;
return function ($timezone) use ($mixin) {
$mixin->userTimeZone = $timezone;
};
}
/**
* Returns date formatted according to given format.
*
* @param string $format
. *
*
* @link http://php.net/manual/en/datetime.format.php
*/
public function tzFormat()
{
$mixin = $this;
return function ($format, $self = null) use ($mixin) {
// compatibility chunk
if (!isset($self) && isset($this)) {
$self = $this;
}
if (!is_null($mixin->userTimeZone)) {
$self->timezone($mixin->userTimeZone);
}
return $self->format($format);
};
}
}
Carbon::mixin(new UserTimezoneCarbonMixin());
Carbon::setUserTimezone('Europe/Berlin');
echo Carbon::createFromTime(12, 0, 0, 'UTC')->tzFormat('H:i'); // 14:00
echo Carbon::createFromTime(15, 0, 0, 'UTC')->tzFormat('H:i'); // 17:00
Carbon::setUserTimezone('America/Toronto');
echo Carbon::createFromTime(12, 0, 0, 'UTC')->tzFormat('H:i'); // 08:00
echo Carbon::createFromTime(15, 0, 0, 'UTC')->tzFormat('H:i'); // 11:00
CarbonInterval
The CarbonInterval class inherits the PHP DateInterval class.
<?php
class CarbonInterval extends \DateInterval
{
// code here
}
You can create instances in the following ways
echo CarbonInterval::year(); // 1 year echo CarbonInterval::months(3); // 3 months echo CarbonInterval::days(3)->seconds(32); // 3 days 32 seconds echo CarbonInterval::weeks(3); // 3 weeks echo CarbonInterval::days(23); // 3 weeks 2 days echo CarbonInterval::create(2, 0, 5, 1, 1, 2, 7); // 2 years 5 weeks 1 day 1 hour 2 minutes 7 seconds
If you find yourself inheriting the \ DateInterval instance from another library, don't be afraid! You can create a CarbonInterval instance through a friendly instance() function.
$di = new \DateInterval('P1Y2M'); // <== instance from another API
$ci = CarbonInterval::instance($di);
echo get_class($ci); // 'Carbon\CarbonInterval'
echo $ci; // 1 year 2 monthsOther helpers, but note that the implementation provides helpers to process for a few weeks, but only a few days are saved. Weeks are calculated based on the total number of days for the current instance.
echo CarbonInterval::year()->years; //
echo CarbonInterval::year()->dayz; //
echo CarbonInterval::days(24)->dayz; //
echo CarbonInterval::days(24)->daysExcludeWeeks; //
echo CarbonInterval::weeks(3)->days(14)->weeks; // 2 <-- days setter overwrites the current value
echo CarbonInterval::weeks(3)->weeks; //
echo CarbonInterval::minutes(3)->weeksAndDays(2, 5); // 2 weeks 5 days 3 minutes
CarbonInterval extend DateInterval，You can use ISO-8601 The duration format of creates both formats:
$ci = CarbonInterval::create('P1Y2M3D');
$ci = new CarbonInterval('PT0S');With the fromString() method, you can create Carbon intervals from a friendly string.
CarbonInterval::fromString('2 minutes 15 seconds');
CarbonInterval::fromString('2m 15s'); // or abbreviatedNote that this month is abbreviated as "mo" to distinguish it from minutes and the whole syntax is case insensitive.
It also has a convenient for human(), which is mapped to__ toString() implementation, used to print intervals for humans.
CarbonInterval::setLocale('fr');
echo CarbonInterval::create(2, 1)->forHumans(); // 2 ans 1 mois
echo CarbonInterval::hour()->seconds(3); // 1 heure 3 secondes
CarbonInterval::setLocale('en');
As you can see, you can change the locale of a string using CarbonInterval::setLocale('fr ').
As for Carbon, you can use the make method to return a new CarbonInterval instance from another interval or string:
$dateInterval = new DateInterval('P2D');
$carbonInterval = CarbonInterval::month();
echo CarbonInterval::make($dateInterval)->forHumans(); // 2 days
echo CarbonInterval::make($carbonInterval)->forHumans(); // 1 month
echo CarbonInterval::make('PT3H')->forHumans(); // 3 hours
echo CarbonInterval::make('1h 15m')->forHumans(); // 1 hour 15 minutes
// Pass true to get short format
echo CarbonInterval::make('1h 15m')->forHumans(true); // 1h 15mThe local DateInterval is added and multiplied respectively, so:
$interval = CarbonInterval::make('7h 55m');
$interval->add(CarbonInterval::make('17h 35m'));
$interval->times(3);
echo $interval->forHumans(); // 72 hours 270 minutesPure calculation is obtained from unit to unit input. Cascade minutes into hours, hours into days, etc. Use cascading method:
echo $interval->forHumans(); // 72 hours 270 minutes echo $interval->cascade()->forHumans(); // 3 days 4 hours 30 minutes
The default factors are:
1 minute = 60 seconds
1 hour = 60 minutes
1 day = 24 hours
1 week = 7 days
1 month = 4 weeks
1 year = 12 months
CarbonIntervals have no context, so they cannot be more precise (no DST, no leap year, no actual month length or age). But you can completely customize these factors. For example, working time logs:
$cascades = CarbonInterval::getCascadeFactors(); // save initial factors
CarbonInterval::setCascadeFactors(array(
'minute' => array(60, 'seconds')
'hour' => array(60, 'minutes'),
'day' => array(8, 'hours'),
'week' => array(5, 'days'),
// in this example the cascade won't go farther than week unit
));
echo CarbonInterval::fromString('20h')->cascade()->forHumans(); // 2 days 4 hours
echo CarbonInterval::fromString('10d')->cascade()->forHumans(); // 2 weeks
echo CarbonInterval::fromString('3w 18d 53h 159m')->cascade()->forHumans(); // 7 weeks 4 days 7 hours 39 minutes
// You can see currently set factors with getFactor:
echo CarbonInterval::getFactor('minutes', /* per */ 'hour'); //
echo CarbonInterval::getFactor('days', 'week'); // 5
// And common factors can be get with short-cut methods:
echo CarbonInterval::getDaysPerWeek(); //
echo CarbonInterval::getHoursPerDay(); //
echo CarbonInterval::getMinutesPerHours(); //
echo CarbonInterval::getSecondsPerMinutes(); //
CarbonInterval::setCascadeFactors($cascades); // restore original factorsWhether it is possible to convert the interval to a given unit (using the provided cascade factor).
echo CarbonInterval::days(3)->hours(5)->total('hours'); //
echo CarbonInterval::days(3)->hours(5)->totalHours; //
echo CarbonInterval::months(6)->totalWeeks; //
echo CarbonInterval::year()->totalDays; //You can also use spec() to get the ISO 8601 specification for inversion
echo CarbonInterval::days(3)->hours(5)->spec(); // P3DT5H
You can also get it from the DateInterval object because it is a static helper:
echo CarbonInterval::getDateIntervalSpec(new DateInterval('P3DT6M10S')); // P3DT6M10SThe date interval list can be sorted by using the compare() and comparedateinterval() methods:
$halfDay = CarbonInterval::hours(12);
$oneDay = CarbonInterval::day();
$twoDay = CarbonInterval::days(2);
echo CarbonInterval::compareDateIntervals($oneDay, $oneDay); //
echo $oneDay->compare($oneDay); //
echo CarbonInterval::compareDateIntervals($oneDay, $halfDay); //
echo $oneDay->compare($halfDay); //
echo CarbonInterval::compareDateIntervals($oneDay, $twoDay); // -1
echo $oneDay->compare($twoDay); // -1
$list = array($twoDay, $halfDay, $oneDay);
usort($list, array('Carbon\CarbonInterval', 'compareDateIntervals'));
echo implode(', ', $list); // 12 hours, 1 day, 2 daysFinally, you can convert a CarbonInterval instance to a carbonseries instance by calling toPeriod() with complementary parameters.
I heard you ask what is the CarbonPeriod instance. oh Perfect transition to the next chapter.
CarbonPeriod
CarbonPeriod is a friendly DatePeriod version with many shortcuts.
// Create a new instance:
$period = new CarbonPeriod('2018-04-21', '3 days', '2018-04-27');
// Use static constructor:
$period = CarbonPeriod::create('2018-04-21', '3 days', '2018-04-27');
// Use the fluent setters:
$period = CarbonPeriod::since('2018-04-21')->days(3)->until('2018-04-27');
// Start from a CarbonInterval:
$period = CarbonInterval::days(3)->toPeriod('2018-04-21', '2018-04-27');CarbonPeriod can be built in a number of ways:
Start date, end date and optional interval (1 day by default),
Start date, number of recursions and optional interval,
ISO 8601 interval specification.
The date can be a DateTime/Carbon instance, an absolute string such as "2007-10-15 15:00" or a relative string such as "next monday". The Interval can be given as an instance of DateInterval/CarbonInterval, the Interval specification of ISO 8601 (such as "P4D") or a human readable string (such as "4 days").
The default constructor and create() method are easy to understand in terms of parameter types and order, so if you want to be more precise, it is recommended to use fluent syntax. On the other hand, you can pass a dynamic value array to createFromArray(), which will construct a new instance using the given array as a parameter list.
CarbonPeriod implements the iterator interface. It means that it can be passed directly to the foreach loop:
$period = CarbonPeriod::create('2018-04-21', '3 days', '2018-04-27');
foreach ($period as $key => $date) {
if ($key) {
echo ', ';
}
echo $date->format('m-d');
}
// 04-21, 04-24, 04-27
// Here is what happens under the hood:
$period->rewind(); // restart the iteration
while ($period->valid()) { // check if current item is valid
if ($period->key()) { // echo comma if current key is greater than 0
echo ', ';
}
echo $period->current()->format('m-d'); // echo current date
$period->next(); // move to the next item
}
// 04-21, 04-24, 04-27Parameters can be modified during iteration:
$period = CarbonPeriod::create('2018-04-29', 7);
$dates = array();
foreach ($period as $key => $date) {
if ($key === 3) {
$period->invert()->start($date); // invert() is an alias for invertDateInterval()
}
$dates[] = $date->format('m-d');
}
echo implode(', ', $dates); // 04-29, 04-30, 05-01, 05-02, 05-01, 04-30, 04-29Like DatePeriod, carbonseries supports the ISO 8601 time interval specification.
Note that native date periods are treated recursively as multiple repetition intervals. Therefore, when excluding the start date, it will reduce one result. The introduction of CarbonPeriod's custom filter makes it more difficult to know the number of results. For this reason, we changed the implementation slightly, and recursion is considered the overall limit of the return date.
// Possible options are: CarbonPeriod::EXCLUDE_START_DATE | CarbonPeriod::EXCLUDE_END_DATE
// Default value is 0 which will have the same effect as when no options are given.
$period = CarbonPeriod::createFromIso('R4/2012-07-01T00:00:00Z/P7D', CarbonPeriod::EXCLUDE_START_DATE);
$dates = array();
foreach ($period as $date) {
$dates[] = $date->format('m-d');
}
echo implode(', ', $dates); // 07-08, 07-15, 07-22, 07-29You can retrieve data from different getter s:
$period = CarbonPeriod::create('2010-05-06', '2010-05-25', CarbonPeriod::EXCLUDE_START_DATE);
$exclude = $period->getOptions() & CarbonPeriod::EXCLUDE_START_DATE;
echo $period->getStartDate(); // 2010-05-06 00:00:00
echo $period->getEndDate(); // 2010-05-25 00:00:00
echo $period->getDateInterval(); // 1 day
echo $exclude ? 'exclude' : 'include'; // exclude
var_dump($period->isStartExcluded()); // bool(true)
var_dump($period->isEndExcluded()); // bool(false)
echo $period->toString(); // Every 1 day from 2010-05-06 to 2010-05-25
echo $period; /*implicit toString*/ // Every 1 day from 2010-05-06 to 2010-05-25The attached getter allows you to access the results as an array:
$period = CarbonPeriod::create('2010-05-11', '2010-05-13');
echo $period->count(); // 3, equivalent to count($period)
echo implode(', ', $period->toArray()); // 2010-05-11 00:00:00, 2010-05-12 00:00:00, 2010-05-13 00:00:00
echo $period->first(); // 2010-05-11 00:00:00
echo $period->last(); // 2010-05-13 00:00:00Note that if you intend to use the above function, it is a good idea to store the result of the toArray() call as a variable and use it, because each call performs a complete iteration internally.
To change parameters, use the setter method:
$period = CarbonPeriod::create('2010-05-01', '2010-05-14', CarbonPeriod::EXCLUDE_END_DATE);
$period->setStartDate('2010-05-11');
echo implode(', ', $period->toArray()); // 2010-05-11 00:00:00, 2010-05-12 00:00:00, 2010-05-13 00:00:00
// Second argument can be optionally used to exclude the date from the results.
$period->setStartDate('2010-05-11', false);
$period->setEndDate('2010-05-14', true);
echo implode(', ', $period->toArray()); // 2010-05-12 00:00:00, 2010-05-13 00:00:00, 2010-05-14 00:00:00
$period->setRecurrences(2);
echo implode(', ', $period->toArray()); // 2010-05-12 00:00:00, 2010-05-13 00:00:00
$period->setDateInterval('PT12H');
echo implode(', ', $period->toArray()); // 2010-05-11 12:00:00, 2010-05-12 00:00:00You can use setOptions() to change options to replace all options, but you can also change them separately:
$period = CarbonPeriod::create('2010-05-06', '2010-05-25');
var_dump($period->isStartExcluded()); // bool(false)
var_dump($period->isEndExcluded()); // bool(false)
$period->toggleOptions(CarbonPeriod::EXCLUDE_START_DATE, true); // true, false or nothing to invert the option
var_dump($period->isStartExcluded()); // bool(true)
var_dump($period->isEndExcluded()); // bool(false) (unchanged)
$period->excludeEndDate(); // specify false to include, true or omit to exclude
var_dump($period->isStartExcluded()); // bool(true) (unchanged)
var_dump($period->isEndExcluded()); // bool(true)
$period->excludeStartDate(false); // specify false to include, true or omit to exclude
var_dump($period->isStartExcluded()); // bool(false)
var_dump($period->isEndExcluded()); // bool(true)As mentioned earlier, recursion is several times the repetition interval according to the ISO 8601 specification. Therefore, the native DatePeriod will change the number of return dates according to the exclusion of the start date. At the same time, carbonseries is more tolerant in terms of input and allowing custom filters, and takes recursion as the overall limit of return date:
$period = CarbonPeriod::createFromIso('R4/2012-07-01T00:00:00Z/P7D');
$days = array();
foreach ($period as $date) {
$days[] = $date->format('d');
}
echo $period->getRecurrences(); //
echo implode(', ', $days); // 01, 08, 15, 22
$days = array();
$period->setRecurrences(3)->excludeStartDate();
foreach ($period as $date) {
$days[] = $date->format('d');
}
echo $period->getRecurrences(); //
echo implode(', ', $days); // 08, 15, 22
$days = array();
$period = CarbonPeriod::recurrences(3)->sinceNow();
foreach ($period as $date) {
$days[] = $date->format('Y-m-d');
}
echo implode(', ', $days); // 2018-07-05, 2018-07-06, 2018-07-07The dates returned by DatePeriod can be easily filtered. For example, filters can be used to skip certain dates or iterate only on weekdays or weekends. The filter function should return true to accept the date, false to skip the date, but continue the search or carbonseries:: end_ Iteration to end the iteration.
$period = CarbonPeriod::between('2000-01-01', '2000-01-15');
$weekendFilter = function ($date) {
return $date->isWeekend();
};
$period->filter($weekendFilter);
$days = array();
foreach ($period as $date) {
$days[] = $date->format('m-d');
}
echo implode(', ', $days); // 01-01, 01-02, 01-08, 01-09, 01-15You can also skip one or more values in the loop.
$period = CarbonPeriod::between('2000-01-01', '2000-01-10');
$days = array();
foreach ($period as $date) {
$day = $date->format('m-d');
$days[] = $day;
if ($day === '01-04') {
$period->skip(3);
}
}
echo implode(', ', $days); // 01-01, 01-02, 01-03, 01-04, 01-08, 01-09, 01-10getFilters() allows you to retrieve all stored filters in one time period. Note, however, that recursive constraints and end dates will appear in the returned array because they are stored internally as filters.
$period = CarbonPeriod::end('2000-01-01')->recurrences(3);
var_export($period->getFilters());
/*
array (
0 =>
array (
0 => 'Carbon\\CarbonPeriod::filterEndDate',
1 => NULL,
),
1 =>
array (
0 => 'Carbon\\CarbonPeriod::filterRecurrences',
1 => NULL,
),
)
*/Filters are stored on the stack and can be managed using a special set of methods:
$period = CarbonPeriod::between('2000-01-01', '2000-01-15');
$weekendFilter = function ($date) {
return $date->isWeekend();
};
var_dump($period->hasFilter($weekendFilter)); // bool(false)
$period->addFilter($weekendFilter);
var_dump($period->hasFilter($weekendFilter)); // bool(true)
$period->removeFilter($weekendFilter);
var_dump($period->hasFilter($weekendFilter)); // bool(false)
// To avoid storing filters as variables you can name your filters:
$period->prependFilter(function ($date) {
return $date->isWeekend();
}, 'weekend');
var_dump($period->hasFilter('weekend')); // bool(true)
$period->removeFilter('weekend');
var_dump($period->hasFilter('weekend')); // bool(false)The order in which filters are added has an impact on performance and results, so you can use addFilter() to add filters at the end of the stack; You can use prependFilter() to add one at the beginning. You can even replace all filters with setfilter(). Note that you must keep the stack in the correct format and remember the internal filters for recursion limits and end dates. Alternatively, you can use the resetFilters() method and add new filters one by one.
For example, when you add a custom filter that limits the number of attempted dates, if you add it before or after the weekday filter, the results will be different.
// Note that you can pass a name of any Carbon method starting with "is", including macros
$period = CarbonPeriod::between('2018-05-03', '2018-05-25')->filter('isWeekday');
$attempts = 0;
$attemptsFilter = function () use (&$attempts) {
return ++$attempts <= 5 ? true : CarbonPeriod::END_ITERATION;
};
$period->prependFilter($attemptsFilter, 'attempts');
$days = array();
foreach ($period as $date) {
$days[] = $date->format('m-d');
}
echo implode(', ', $days); // 05-03, 05-04, 05-07
$attempts = 0;
$period->removeFilter($attemptsFilter)->addFilter($attemptsFilter, 'attempts');
$days = array();
foreach ($period as $date) {
$days[] = $date->format('m-d');
}
echo implode(', ', $days); // 05-03, 05-04, 05-07, 05-08, 05-09Note that the built-in recursive filter does not work like this. Instead, it increments each entry only once based on the current key, regardless of how many dates need to be checked before finding the effective date. If you put it at the beginning or end of the stack, this technique will make it work the same way.
In order to simplify the construction of CarbonPeriod, some aliases have been added:
// "start", "since", "sinceNow":
CarbonPeriod::start('2017-03-10') == CarbonPeriod::create()->setStartDate('2017-03-10');
// Same with optional boolean argument $inclusive to change the option about include/exclude start date:
CarbonPeriod::start('2017-03-10', true) == CarbonPeriod::create()->setStartDate('2017-03-10', true);
// "end", "until", "untilNow":
CarbonPeriod::end('2017-03-20') == CarbonPeriod::create()->setEndDate('2017-03-20');
// Same with optional boolean argument $inclusive to change the option about include/exclude end date:
CarbonPeriod::end('2017-03-20', true) == CarbonPeriod::create()->setEndDate('2017-03-20', true);
// "dates", "between":
CarbonPeriod::dates(..., ...) == CarbonPeriod::create()->setDates(..., ...);
// "recurrences", "times":
CarbonPeriod::recurrences(5) == CarbonPeriod::create()->setRecurrences(5);
// "options":
CarbonPeriod::options(...) == CarbonPeriod::create()->setOptions(...);
// "toggle":
CarbonPeriod::toggle(..., true) == CarbonPeriod::create()->toggleOptions(..., true);
// "filter", "push":
CarbonPeriod::filter(...) == CarbonPeriod::create()->addFilter(...);
// "prepend":
CarbonPeriod::prepend(...) == CarbonPeriod::create()->prependFilter(...);
// "filters":
CarbonPeriod::filters(...) == CarbonPeriod::create()->setFilters(...);
// "interval", "each", "every", "step", "stepBy":
CarbonPeriod::interval(...) == CarbonPeriod::create()->setDateInterval(...);
// "invert":
CarbonPeriod::invert() == CarbonPeriod::create()->invertDateInterval();
// "year", "months", "month", "weeks", "week", "days", "dayz", "day",
// "hours", "hour", "minutes", "minute", "seconds", "second":
CarbonPeriod::hours(5) == CarbonPeriod::create()->setDateInterval(new CarbonInterval::hours(5));CarbonPeriod can be easily converted to human readable strings and ISO 8601 specifications:
$period = CarbonPeriod::create('2000-01-01 12:00', '3 days 12 hours', '2000-01-15 12:00');
echo $period->toString(); // Every 3 days 12 hours from 2000-01-01 12:00:00 to 2000-01-15 12:00:00
echo $period->toIso8601String(); // 2000-01-01T12:00:00-05:00/P3DT12H/2000-01-15T12:00:00-05:00