CarbonCarbon

A simple API extension for DateTime.

Defined (1)

The class is defined in the following location(s).

/vendor/nesbot/carbon/src/Carbon/Carbon.php  
  1. class Carbon extends DateTime 
  2. /** 
  3. * The day constants 
  4. */ 
  5. const SUNDAY = 0; 
  6. const MONDAY = 1; 
  7. const TUESDAY = 2; 
  8. const WEDNESDAY = 3; 
  9. const THURSDAY = 4; 
  10. const FRIDAY = 5; 
  11. const SATURDAY = 6; 
  12.  
  13. /** 
  14. * Names of days of the week. 
  15. * @var array 
  16. */ 
  17. protected static $days = array( 
  18. self::SUNDAY => 'Sunday',  
  19. self::MONDAY => 'Monday',  
  20. self::TUESDAY => 'Tuesday',  
  21. self::WEDNESDAY => 'Wednesday',  
  22. self::THURSDAY => 'Thursday',  
  23. self::FRIDAY => 'Friday',  
  24. self::SATURDAY => 'Saturday',  
  25. ); 
  26.  
  27. /** 
  28. * Terms used to detect if a time passed is a relative date for testing purposes 
  29. * @var array 
  30. */ 
  31. protected static $relativeKeywords = array( 
  32. 'this',  
  33. 'next',  
  34. 'last',  
  35. 'tomorrow',  
  36. 'yesterday',  
  37. '+',  
  38. '-',  
  39. 'first',  
  40. 'last',  
  41. 'ago',  
  42. ); 
  43.  
  44. /** 
  45. * Number of X in Y 
  46. */ 
  47. const YEARS_PER_CENTURY = 100; 
  48. const YEARS_PER_DECADE = 10; 
  49. const MONTHS_PER_YEAR = 12; 
  50. const WEEKS_PER_YEAR = 52; 
  51. const DAYS_PER_WEEK = 7; 
  52. const HOURS_PER_DAY = 24; 
  53. const MINUTES_PER_HOUR = 60; 
  54. const SECONDS_PER_MINUTE = 60; 
  55.  
  56. /** 
  57. * Default format to use for __toString method when type juggling occurs. 
  58. * @var string 
  59. */ 
  60. const DEFAULT_TO_STRING_FORMAT = 'Y-m-d H:i:s'; 
  61.  
  62. /** 
  63. * Format to use for __toString method when type juggling occurs. 
  64. * @var string 
  65. */ 
  66. protected static $toStringFormat = self::DEFAULT_TO_STRING_FORMAT; 
  67.  
  68. /** 
  69. * First day of week 
  70. * @var int 
  71. */ 
  72. protected static $weekStartsAt = self::MONDAY; 
  73.  
  74. /** 
  75. * Last day of week 
  76. * @var int 
  77. */ 
  78. protected static $weekEndsAt = self::SUNDAY; 
  79.  
  80. /** 
  81. * Days of weekend 
  82. * @var array 
  83. */ 
  84. protected static $weekendDays = array(self::SATURDAY, self::SUNDAY); 
  85.  
  86. /** 
  87. * A test Carbon instance to be returned when now instances are created 
  88. * @var Carbon 
  89. */ 
  90. protected static $testNow; 
  91.  
  92. /** 
  93. * A translator to ... er ... translate stuff 
  94. * @var TranslatorInterface 
  95. */ 
  96. protected static $translator; 
  97.  
  98. /** 
  99. * Creates a DateTimeZone from a string or a DateTimeZone 
  100. * @param DateTimeZone|string|null $object 
  101. * @throws InvalidArgumentException 
  102. * @return DateTimeZone 
  103. */ 
  104. protected static function safeCreateDateTimeZone($object) 
  105. if ($object === null) { 
  106. // Don't return null... avoid Bug #52063 in PHP <5.3.6 
  107. return new DateTimeZone(date_default_timezone_get()); 
  108.  
  109. if ($object instanceof DateTimeZone) { 
  110. return $object; 
  111.  
  112. $tz = @timezone_open((string) $object); 
  113.  
  114. if ($tz === false) { 
  115. throw new InvalidArgumentException('Unknown or bad timezone ('.$object.')'); 
  116.  
  117. return $tz; 
  118.  
  119. /////////////////////////////////////////////////////////////////// 
  120. //////////////////////////// CONSTRUCTORS ///////////////////////// 
  121. /////////////////////////////////////////////////////////////////// 
  122.  
  123. /** 
  124. * Create a new Carbon instance. 
  125. * Please see the testing aids section (specifically static::setTestNow()) 
  126. * for more on the possibility of this constructor returning a test instance. 
  127. * @param string|null $time 
  128. * @param DateTimeZone|string|null $tz 
  129. */ 
  130. public function __construct($time = null, $tz = null) 
  131. // If the class has a test now set and we are trying to create a now() 
  132. // instance then override as required 
  133. if (static::hasTestNow() && (empty($time) || $time === 'now' || static::hasRelativeKeywords($time))) { 
  134. $testInstance = clone static::getTestNow(); 
  135. if (static::hasRelativeKeywords($time)) { 
  136. $testInstance->modify($time); 
  137.  
  138. //shift the time according to the given time zone 
  139. if ($tz !== null && $tz !== static::getTestNow()->tz) { 
  140. $testInstance->setTimezone($tz); 
  141. } else { 
  142. $tz = $testInstance->tz; 
  143.  
  144. $time = $testInstance->toDateTimeString(); 
  145.  
  146. parent::__construct($time, static::safeCreateDateTimeZone($tz)); 
  147.  
  148. /** 
  149. * Create a Carbon instance from a DateTime one 
  150. * @param DateTime $dt 
  151. * @return static 
  152. */ 
  153. public static function instance(DateTime $dt) 
  154. return new static($dt->format('Y-m-d H:i:s.u'), $dt->getTimeZone()); 
  155.  
  156. /** 
  157. * Create a carbon instance from a string. This is an alias for the 
  158. * constructor that allows better fluent syntax as it allows you to do 
  159. * Carbon::parse('Monday next week')->fn() rather than 
  160. * (new Carbon('Monday next week'))->fn() 
  161. * @param string|null $time 
  162. * @param DateTimeZone|string|null $tz 
  163. * @return static 
  164. */ 
  165. public static function parse($time = null, $tz = null) 
  166. return new static($time, $tz); 
  167.  
  168. /** 
  169. * Get a Carbon instance for the current date and time 
  170. * @param DateTimeZone|string|null $tz 
  171. * @return static 
  172. */ 
  173. public static function now($tz = null) 
  174. return new static(null, $tz); 
  175.  
  176. /** 
  177. * Create a Carbon instance for today 
  178. * @param DateTimeZone|string|null $tz 
  179. * @return static 
  180. */ 
  181. public static function today($tz = null) 
  182. return static::now($tz)->startOfDay(); 
  183.  
  184. /** 
  185. * Create a Carbon instance for tomorrow 
  186. * @param DateTimeZone|string|null $tz 
  187. * @return static 
  188. */ 
  189. public static function tomorrow($tz = null) 
  190. return static::today($tz)->addDay(); 
  191.  
  192. /** 
  193. * Create a Carbon instance for yesterday 
  194. * @param DateTimeZone|string|null $tz 
  195. * @return static 
  196. */ 
  197. public static function yesterday($tz = null) 
  198. return static::today($tz)->subDay(); 
  199.  
  200. /** 
  201. * Create a Carbon instance for the greatest supported date. 
  202. * @return Carbon 
  203. */ 
  204. public static function maxValue() 
  205. if (PHP_INT_SIZE === 4) { 
  206. // 32 bit (and additionally Windows 64 bit) 
  207. return static::createFromTimestamp(PHP_INT_MAX); 
  208.  
  209. // 64 bit 
  210. return static::create(9999, 12, 31, 23, 59, 59); 
  211.  
  212. /** 
  213. * Create a Carbon instance for the lowest supported date. 
  214. * @return Carbon 
  215. */ 
  216. public static function minValue() 
  217. if (PHP_INT_SIZE === 4) { 
  218. // 32 bit (and additionally Windows 64 bit) 
  219. return static::createFromTimestamp(~PHP_INT_MAX); 
  220.  
  221. // 64 bit 
  222. return static::create(1, 1, 1, 0, 0, 0); 
  223.  
  224. /** 
  225. * Create a new Carbon instance from a specific date and time. 
  226. * If any of $year, $month or $day are set to null their now() values 
  227. * will be used. 
  228. * If $hour is null it will be set to its now() value and the default values 
  229. * for $minute and $second will be their now() values. 
  230. * If $hour is not null then the default values for $minute and $second 
  231. * will be 0. 
  232. * @param int|null $year 
  233. * @param int|null $month 
  234. * @param int|null $day 
  235. * @param int|null $hour 
  236. * @param int|null $minute 
  237. * @param int|null $second 
  238. * @param DateTimeZone|string|null $tz 
  239. * @return static 
  240. */ 
  241. public static function create($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null, $tz = null) 
  242. $year = $year === null ? date('Y') : $year; 
  243. $month = $month === null ? date('n') : $month; 
  244. $day = $day === null ? date('j') : $day; 
  245.  
  246. if ($hour === null) { 
  247. $hour = date('G'); 
  248. $minute = $minute === null ? date('i') : $minute; 
  249. $second = $second === null ? date('s') : $second; 
  250. } else { 
  251. $minute = $minute === null ? 0 : $minute; 
  252. $second = $second === null ? 0 : $second; 
  253.  
  254. return static::createFromFormat('Y-n-j G:i:s', sprintf('%s-%s-%s %s:%02s:%02s', $year, $month, $day, $hour, $minute, $second), $tz); 
  255.  
  256. /** 
  257. * Create a Carbon instance from just a date. The time portion is set to now. 
  258. * @param int|null $year 
  259. * @param int|null $month 
  260. * @param int|null $day 
  261. * @param DateTimeZone|string|null $tz 
  262. * @return static 
  263. */ 
  264. public static function createFromDate($year = null, $month = null, $day = null, $tz = null) 
  265. return static::create($year, $month, $day, null, null, null, $tz); 
  266.  
  267. /** 
  268. * Create a Carbon instance from just a time. The date portion is set to today. 
  269. * @param int|null $hour 
  270. * @param int|null $minute 
  271. * @param int|null $second 
  272. * @param DateTimeZone|string|null $tz 
  273. * @return static 
  274. */ 
  275. public static function createFromTime($hour = null, $minute = null, $second = null, $tz = null) 
  276. return static::create(null, null, null, $hour, $minute, $second, $tz); 
  277.  
  278. /** 
  279. * Create a Carbon instance from a specific format 
  280. * @param string $format 
  281. * @param string $time 
  282. * @param DateTimeZone|string|null $tz 
  283. * @throws InvalidArgumentException 
  284. * @return static 
  285. */ 
  286. public static function createFromFormat($format, $time, $tz = null) 
  287. if ($tz !== null) { 
  288. $dt = parent::createFromFormat($format, $time, static::safeCreateDateTimeZone($tz)); 
  289. } else { 
  290. $dt = parent::createFromFormat($format, $time); 
  291.  
  292. if ($dt instanceof DateTime) { 
  293. return static::instance($dt); 
  294.  
  295. $errors = static::getLastErrors(); 
  296. throw new InvalidArgumentException(implode(PHP_EOL, $errors['errors'])); 
  297.  
  298. /** 
  299. * Create a Carbon instance from a timestamp 
  300. * @param int $timestamp 
  301. * @param DateTimeZone|string|null $tz 
  302. * @return static 
  303. */ 
  304. public static function createFromTimestamp($timestamp, $tz = null) 
  305. return static::now($tz)->setTimestamp($timestamp); 
  306.  
  307. /** 
  308. * Create a Carbon instance from an UTC timestamp 
  309. * @param int $timestamp 
  310. * @return static 
  311. */ 
  312. public static function createFromTimestampUTC($timestamp) 
  313. return new static('@'.$timestamp); 
  314.  
  315. /** 
  316. * Get a copy of the instance 
  317. * @return static 
  318. */ 
  319. public function copy() 
  320. return static::instance($this); 
  321.  
  322. /////////////////////////////////////////////////////////////////// 
  323. ///////////////////////// GETTERS AND SETTERS ///////////////////// 
  324. /////////////////////////////////////////////////////////////////// 
  325.  
  326. /** 
  327. * Get a part of the Carbon object 
  328. * @param string $name 
  329. * @throws InvalidArgumentException 
  330. * @return string|int|DateTimeZone 
  331. */ 
  332. public function __get($name) 
  333. switch (true) { 
  334. case array_key_exists($name, $formats = array( 
  335. 'year' => 'Y',  
  336. 'yearIso' => 'o',  
  337. 'month' => 'n',  
  338. 'day' => 'j',  
  339. 'hour' => 'G',  
  340. 'minute' => 'i',  
  341. 'second' => 's',  
  342. 'micro' => 'u',  
  343. 'dayOfWeek' => 'w',  
  344. 'dayOfYear' => 'z',  
  345. 'weekOfYear' => 'W',  
  346. 'daysInMonth' => 't',  
  347. 'timestamp' => 'U',  
  348. )): 
  349. return (int) $this->format($formats[$name]); 
  350.  
  351. case $name === 'weekOfMonth': 
  352. return (int) ceil($this->day / static::DAYS_PER_WEEK); 
  353.  
  354. case $name === 'age': 
  355. return (int) $this->diffInYears(); 
  356.  
  357. case $name === 'quarter': 
  358. return (int) ceil($this->month / 3); 
  359.  
  360. case $name === 'offset': 
  361. return $this->getOffset(); 
  362.  
  363. case $name === 'offsetHours': 
  364. return $this->getOffset() / static::SECONDS_PER_MINUTE / static::MINUTES_PER_HOUR; 
  365.  
  366. case $name === 'dst': 
  367. return $this->format('I') === '1'; 
  368.  
  369. case $name === 'local': 
  370. return $this->offset === $this->copy()->setTimezone(date_default_timezone_get())->offset; 
  371.  
  372. case $name === 'utc': 
  373. return $this->offset === 0; 
  374.  
  375. case $name === 'timezone' || $name === 'tz': 
  376. return $this->getTimezone(); 
  377.  
  378. case $name === 'timezoneName' || $name === 'tzName': 
  379. return $this->getTimezone()->getName(); 
  380.  
  381. default: 
  382. throw new InvalidArgumentException(sprintf("Unknown getter '%s'", $name)); 
  383.  
  384. /** 
  385. * Check if an attribute exists on the object 
  386. * @param string $name 
  387. * @return bool 
  388. */ 
  389. public function __isset($name) 
  390. try { 
  391. $this->__get($name); 
  392. } catch (InvalidArgumentException $e) { 
  393. return false; 
  394.  
  395. return true; 
  396.  
  397. /** 
  398. * Set a part of the Carbon object 
  399. * @param string $name 
  400. * @param string|int|DateTimeZone $value 
  401. * @throws InvalidArgumentException 
  402. */ 
  403. public function __set($name, $value) 
  404. switch ($name) { 
  405. case 'year': 
  406. $this->setDate($value, $this->month, $this->day); 
  407. break; 
  408.  
  409. case 'month': 
  410. $this->setDate($this->year, $value, $this->day); 
  411. break; 
  412.  
  413. case 'day': 
  414. $this->setDate($this->year, $this->month, $value); 
  415. break; 
  416.  
  417. case 'hour': 
  418. $this->setTime($value, $this->minute, $this->second); 
  419. break; 
  420.  
  421. case 'minute': 
  422. $this->setTime($this->hour, $value, $this->second); 
  423. break; 
  424.  
  425. case 'second': 
  426. $this->setTime($this->hour, $this->minute, $value); 
  427. break; 
  428.  
  429. case 'timestamp': 
  430. parent::setTimestamp($value); 
  431. break; 
  432.  
  433. case 'timezone': 
  434. case 'tz': 
  435. $this->setTimezone($value); 
  436. break; 
  437.  
  438. default: 
  439. throw new InvalidArgumentException(sprintf("Unknown setter '%s'", $name)); 
  440.  
  441. /** 
  442. * Set the instance's year 
  443. * @param int $value 
  444. * @return static 
  445. */ 
  446. public function year($value) 
  447. $this->year = $value; 
  448.  
  449. return $this; 
  450.  
  451. /** 
  452. * Set the instance's month 
  453. * @param int $value 
  454. * @return static 
  455. */ 
  456. public function month($value) 
  457. $this->month = $value; 
  458.  
  459. return $this; 
  460.  
  461. /** 
  462. * Set the instance's day 
  463. * @param int $value 
  464. * @return static 
  465. */ 
  466. public function day($value) 
  467. $this->day = $value; 
  468.  
  469. return $this; 
  470.  
  471. /** 
  472. * Set the instance's hour 
  473. * @param int $value 
  474. * @return static 
  475. */ 
  476. public function hour($value) 
  477. $this->hour = $value; 
  478.  
  479. return $this; 
  480.  
  481. /** 
  482. * Set the instance's minute 
  483. * @param int $value 
  484. * @return static 
  485. */ 
  486. public function minute($value) 
  487. $this->minute = $value; 
  488.  
  489. return $this; 
  490.  
  491. /** 
  492. * Set the instance's second 
  493. * @param int $value 
  494. * @return static 
  495. */ 
  496. public function second($value) 
  497. $this->second = $value; 
  498.  
  499. return $this; 
  500.  
  501. /** 
  502. * Set the date and time all together 
  503. * @param int $year 
  504. * @param int $month 
  505. * @param int $day 
  506. * @param int $hour 
  507. * @param int $minute 
  508. * @param int $second 
  509. * @return static 
  510. */ 
  511. public function setDateTime($year, $month, $day, $hour, $minute, $second = 0) 
  512. return $this->setDate($year, $month, $day)->setTime($hour, $minute, $second); 
  513.  
  514. /** 
  515. * Set the time by time string 
  516. * @param string $time 
  517. * @return static 
  518. */ 
  519. public function setTimeFromTimeString($time) 
  520. $time = explode(":", $time); 
  521.  
  522. $hour = $time[0]; 
  523. $minute = isset($time[1]) ? $time[1] : 0; 
  524. $second = isset($time[2]) ? $time[2] : 0; 
  525.  
  526. return $this->setTime($hour, $minute, $second); 
  527.  
  528. /** 
  529. * Set the instance's timestamp 
  530. * @param int $value 
  531. * @return static 
  532. */ 
  533. public function timestamp($value) 
  534. $this->timestamp = $value; 
  535.  
  536. return $this; 
  537.  
  538. /** 
  539. * Alias for setTimezone() 
  540. * @param DateTimeZone|string $value 
  541. * @return static 
  542. */ 
  543. public function timezone($value) 
  544. return $this->setTimezone($value); 
  545.  
  546. /** 
  547. * Alias for setTimezone() 
  548. * @param DateTimeZone|string $value 
  549. * @return static 
  550. */ 
  551. public function tz($value) 
  552. return $this->setTimezone($value); 
  553.  
  554. /** 
  555. * Set the instance's timezone from a string or object 
  556. * @param DateTimeZone|string $value 
  557. * @return static 
  558. */ 
  559. public function setTimezone($value) 
  560. parent::setTimezone(static::safeCreateDateTimeZone($value)); 
  561.  
  562. return $this; 
  563.  
  564. /////////////////////////////////////////////////////////////////// 
  565. /////////////////////// WEEK SPECIAL DAYS ///////////////////////// 
  566. /////////////////////////////////////////////////////////////////// 
  567.  
  568. /** 
  569. * Get the first day of week 
  570. * @return int 
  571. */ 
  572. public static function getWeekStartsAt() 
  573. return static::$weekStartsAt; 
  574.  
  575. /** 
  576. * Set the first day of week 
  577. * @param int 
  578. */ 
  579. public static function setWeekStartsAt($day) 
  580. static::$weekStartsAt = $day; 
  581.  
  582. /** 
  583. * Get the last day of week 
  584. * @return int 
  585. */ 
  586. public static function getWeekEndsAt() 
  587. return static::$weekEndsAt; 
  588.  
  589. /** 
  590. * Set the first day of week 
  591. * @param int 
  592. */ 
  593. public static function setWeekEndsAt($day) 
  594. static::$weekEndsAt = $day; 
  595.  
  596. /** 
  597. * Get weekend days 
  598. * @return array 
  599. */ 
  600. public static function getWeekendDays() 
  601. return static::$weekendDays; 
  602.  
  603. /** 
  604. * Set weekend days 
  605. * @param array 
  606. */ 
  607. public static function setWeekendDays($days) 
  608. static::$weekendDays = $days; 
  609.  
  610. /////////////////////////////////////////////////////////////////// 
  611. ///////////////////////// TESTING AIDS //////////////////////////// 
  612. /////////////////////////////////////////////////////////////////// 
  613.  
  614. /** 
  615. * Set a Carbon instance (real or mock) to be returned when a "now" 
  616. * instance is created. The provided instance will be returned 
  617. * specifically under the following conditions: 
  618. * - A call to the static now() method, ex. Carbon::now() 
  619. * - When a null (or blank string) is passed to the constructor or parse(), ex. new Carbon(null) 
  620. * - When the string "now" is passed to the constructor or parse(), ex. new Carbon('now') 
  621. * Note the timezone parameter was left out of the examples above and 
  622. * has no affect as the mock value will be returned regardless of its value. 
  623. * To clear the test instance call this method using the default 
  624. * parameter of null. 
  625. * @param Carbon|null $testNow 
  626. */ 
  627. public static function setTestNow(Carbon $testNow = null) 
  628. static::$testNow = $testNow; 
  629.  
  630. /** 
  631. * Get the Carbon instance (real or mock) to be returned when a "now" 
  632. * instance is created. 
  633. * @return static the current instance used for testing 
  634. */ 
  635. public static function getTestNow() 
  636. return static::$testNow; 
  637.  
  638. /** 
  639. * Determine if there is a valid test instance set. A valid test instance 
  640. * is anything that is not null. 
  641. * @return bool true if there is a test instance, otherwise false 
  642. */ 
  643. public static function hasTestNow() 
  644. return static::getTestNow() !== null; 
  645.  
  646. /** 
  647. * Determine if there is a relative keyword in the time string, this is to 
  648. * create dates relative to now for test instances. e.g.: next tuesday 
  649. * @param string $time 
  650. * @return bool true if there is a keyword, otherwise false 
  651. */ 
  652. public static function hasRelativeKeywords($time) 
  653. // skip common format with a '-' in it 
  654. if (preg_match('/[0-9]{4}-[0-9]{1, 2}-[0-9]{1, 2}/', $time) !== 1) { 
  655. foreach (static::$relativeKeywords as $keyword) { 
  656. if (stripos($time, $keyword) !== false) { 
  657. return true; 
  658.  
  659. return false; 
  660.  
  661. /////////////////////////////////////////////////////////////////// 
  662. /////////////////////// LOCALIZATION ////////////////////////////// 
  663. /////////////////////////////////////////////////////////////////// 
  664.  
  665. /** 
  666. * Intialize the translator instance if necessary. 
  667. * @return TranslatorInterface 
  668. */ 
  669. protected static function translator() 
  670. if (static::$translator === null) { 
  671. static::$translator = new Translator('en'); 
  672. static::$translator->addLoader('array', new ArrayLoader()); 
  673. static::setLocale('en'); 
  674.  
  675. return static::$translator; 
  676.  
  677. /** 
  678. * Get the translator instance in use 
  679. * @return TranslatorInterface 
  680. */ 
  681. public static function getTranslator() 
  682. return static::translator(); 
  683.  
  684. /** 
  685. * Set the translator instance to use 
  686. * @param TranslatorInterface $translator 
  687. */ 
  688. public static function setTranslator(TranslatorInterface $translator) 
  689. static::$translator = $translator; 
  690.  
  691. /** 
  692. * Get the current translator locale 
  693. * @return string 
  694. */ 
  695. public static function getLocale() 
  696. return static::translator()->getLocale(); 
  697.  
  698. /** 
  699. * Set the current translator locale 
  700. * @param string $locale 
  701. */ 
  702. public static function setLocale($locale) 
  703. static::translator()->setLocale($locale); 
  704.  
  705. // Ensure the locale has been loaded. 
  706. static::translator()->addResource('array', require __DIR__.'/Lang/'.$locale.'.php', $locale); 
  707.  
  708. /////////////////////////////////////////////////////////////////// 
  709. /////////////////////// STRING FORMATTING ///////////////////////// 
  710. /////////////////////////////////////////////////////////////////// 
  711.  
  712. /** 
  713. * Format the instance with the current locale. You can set the current 
  714. * locale using setlocale() http://php.net/setlocale. 
  715. * @param string $format 
  716. * @return string 
  717. */ 
  718. public function formatLocalized($format) 
  719. // Check for Windows to find and replace the %e 
  720. // modifier correctly 
  721. if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') { 
  722. $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format); 
  723.  
  724. return strftime($format, strtotime($this)); 
  725.  
  726. /** 
  727. * Reset the format used to the default when type juggling a Carbon instance to a string 
  728. */ 
  729. public static function resetToStringFormat() 
  730. static::setToStringFormat(static::DEFAULT_TO_STRING_FORMAT); 
  731.  
  732. /** 
  733. * Set the default format used when type juggling a Carbon instance to a string 
  734. * @param string $format 
  735. */ 
  736. public static function setToStringFormat($format) 
  737. static::$toStringFormat = $format; 
  738.  
  739. /** 
  740. * Format the instance as a string using the set format 
  741. * @return string 
  742. */ 
  743. public function __toString() 
  744. return $this->format(static::$toStringFormat); 
  745.  
  746. /** 
  747. * Format the instance as date 
  748. * @return string 
  749. */ 
  750. public function toDateString() 
  751. return $this->format('Y-m-d'); 
  752.  
  753. /** 
  754. * Format the instance as a readable date 
  755. * @return string 
  756. */ 
  757. public function toFormattedDateString() 
  758. return $this->format('M j, Y'); 
  759.  
  760. /** 
  761. * Format the instance as time 
  762. * @return string 
  763. */ 
  764. public function toTimeString() 
  765. return $this->format('H:i:s'); 
  766.  
  767. /** 
  768. * Format the instance as date and time 
  769. * @return string 
  770. */ 
  771. public function toDateTimeString() 
  772. return $this->format('Y-m-d H:i:s'); 
  773.  
  774. /** 
  775. * Format the instance with day, date and time 
  776. * @return string 
  777. */ 
  778. public function toDayDateTimeString() 
  779. return $this->format('D, M j, Y g:i A'); 
  780.  
  781. /** 
  782. * Format the instance as ATOM 
  783. * @return string 
  784. */ 
  785. public function toAtomString() 
  786. return $this->format(static::ATOM); 
  787.  
  788. /** 
  789. * Format the instance as COOKIE 
  790. * @return string 
  791. */ 
  792. public function toCookieString() 
  793. return $this->format(static::COOKIE); 
  794.  
  795. /** 
  796. * Format the instance as ISO8601 
  797. * @return string 
  798. */ 
  799. public function toIso8601String() 
  800. return $this->format(static::ISO8601); 
  801.  
  802. /** 
  803. * Format the instance as RFC822 
  804. * @return string 
  805. */ 
  806. public function toRfc822String() 
  807. return $this->format(static::RFC822); 
  808.  
  809. /** 
  810. * Format the instance as RFC850 
  811. * @return string 
  812. */ 
  813. public function toRfc850String() 
  814. return $this->format(static::RFC850); 
  815.  
  816. /** 
  817. * Format the instance as RFC1036 
  818. * @return string 
  819. */ 
  820. public function toRfc1036String() 
  821. return $this->format(static::RFC1036); 
  822.  
  823. /** 
  824. * Format the instance as RFC1123 
  825. * @return string 
  826. */ 
  827. public function toRfc1123String() 
  828. return $this->format(static::RFC1123); 
  829.  
  830. /** 
  831. * Format the instance as RFC2822 
  832. * @return string 
  833. */ 
  834. public function toRfc2822String() 
  835. return $this->format(static::RFC2822); 
  836.  
  837. /** 
  838. * Format the instance as RFC3339 
  839. * @return string 
  840. */ 
  841. public function toRfc3339String() 
  842. return $this->format(static::RFC3339); 
  843.  
  844. /** 
  845. * Format the instance as RSS 
  846. * @return string 
  847. */ 
  848. public function toRssString() 
  849. return $this->format(static::RSS); 
  850.  
  851. /** 
  852. * Format the instance as W3C 
  853. * @return string 
  854. */ 
  855. public function toW3cString() 
  856. return $this->format(static::W3C); 
  857.  
  858. /////////////////////////////////////////////////////////////////// 
  859. ////////////////////////// COMPARISONS //////////////////////////// 
  860. /////////////////////////////////////////////////////////////////// 
  861.  
  862. /** 
  863. * Determines if the instance is equal to another 
  864. * @param Carbon $dt 
  865. * @return bool 
  866. */ 
  867. public function eq(Carbon $dt) 
  868. return $this == $dt; 
  869.  
  870. /** 
  871. * Determines if the instance is not equal to another 
  872. * @param Carbon $dt 
  873. * @return bool 
  874. */ 
  875. public function ne(Carbon $dt) 
  876. return !$this->eq($dt); 
  877.  
  878. /** 
  879. * Determines if the instance is greater (after) than another 
  880. * @param Carbon $dt 
  881. * @return bool 
  882. */ 
  883. public function gt(Carbon $dt) 
  884. return $this > $dt; 
  885.  
  886. /** 
  887. * Determines if the instance is greater (after) than or equal to another 
  888. * @param Carbon $dt 
  889. * @return bool 
  890. */ 
  891. public function gte(Carbon $dt) 
  892. return $this >= $dt; 
  893.  
  894. /** 
  895. * Determines if the instance is less (before) than another 
  896. * @param Carbon $dt 
  897. * @return bool 
  898. */ 
  899. public function lt(Carbon $dt) 
  900. return $this < $dt; 
  901.  
  902. /** 
  903. * Determines if the instance is less (before) or equal to another 
  904. * @param Carbon $dt 
  905. * @return bool 
  906. */ 
  907. public function lte(Carbon $dt) 
  908. return $this <= $dt; 
  909.  
  910. /** 
  911. * Determines if the instance is between two others 
  912. * @param Carbon $dt1 
  913. * @param Carbon $dt2 
  914. * @param bool $equal Indicates if a > and < comparison should be used or <= or >= 
  915. * @return bool 
  916. */ 
  917. public function between(Carbon $dt1, Carbon $dt2, $equal = true) 
  918. if ($dt1->gt($dt2)) { 
  919. $temp = $dt1; 
  920. $dt1 = $dt2; 
  921. $dt2 = $temp; 
  922.  
  923. if ($equal) { 
  924. return $this->gte($dt1) && $this->lte($dt2); 
  925.  
  926. return $this->gt($dt1) && $this->lt($dt2); 
  927.  
  928. /** 
  929. * Get the closest date from the instance. 
  930. * @param Carbon $dt1 
  931. * @param Carbon $dt2 
  932. * @return static 
  933. */ 
  934. public function closest(Carbon $dt1, Carbon $dt2) 
  935. return $this->diffInSeconds($dt1) < $this->diffInSeconds($dt2) ? $dt1 : $dt2; 
  936.  
  937. /** 
  938. * Get the farthest date from the instance. 
  939. * @param Carbon $dt1 
  940. * @param Carbon $dt2 
  941. * @return static 
  942. */ 
  943. public function farthest(Carbon $dt1, Carbon $dt2) 
  944. return $this->diffInSeconds($dt1) > $this->diffInSeconds($dt2) ? $dt1 : $dt2; 
  945.  
  946. /** 
  947. * Get the minimum instance between a given instance (default now) and the current instance. 
  948. * @param Carbon|null $dt 
  949. * @return static 
  950. */ 
  951. public function min(Carbon $dt = null) 
  952. $dt = $dt ?: static::now($this->tz); 
  953.  
  954. return $this->lt($dt) ? $this : $dt; 
  955.  
  956. /** 
  957. * Get the maximum instance between a given instance (default now) and the current instance. 
  958. * @param Carbon|null $dt 
  959. * @return static 
  960. */ 
  961. public function max(Carbon $dt = null) 
  962. $dt = $dt ?: static::now($this->tz); 
  963.  
  964. return $this->gt($dt) ? $this : $dt; 
  965.  
  966. /** 
  967. * Determines if the instance is a weekday 
  968. * @return bool 
  969. */ 
  970. public function isWeekday() 
  971. return !$this->isWeekend(); 
  972.  
  973. /** 
  974. * Determines if the instance is a weekend day 
  975. * @return bool 
  976. */ 
  977. public function isWeekend() 
  978. return in_array($this->dayOfWeek, self::$weekendDays); 
  979.  
  980. /** 
  981. * Determines if the instance is yesterday 
  982. * @return bool 
  983. */ 
  984. public function isYesterday() 
  985. return $this->toDateString() === static::yesterday($this->tz)->toDateString(); 
  986.  
  987. /** 
  988. * Determines if the instance is today 
  989. * @return bool 
  990. */ 
  991. public function isToday() 
  992. return $this->toDateString() === static::now($this->tz)->toDateString(); 
  993.  
  994. /** 
  995. * Determines if the instance is tomorrow 
  996. * @return bool 
  997. */ 
  998. public function isTomorrow() 
  999. return $this->toDateString() === static::tomorrow($this->tz)->toDateString(); 
  1000.  
  1001. /** 
  1002. * Determines if the instance is in the future, ie. greater (after) than now 
  1003. * @return bool 
  1004. */ 
  1005. public function isFuture() 
  1006. return $this->gt(static::now($this->tz)); 
  1007.  
  1008. /** 
  1009. * Determines if the instance is in the past, ie. less (before) than now 
  1010. * @return bool 
  1011. */ 
  1012. public function isPast() 
  1013. return $this->lt(static::now($this->tz)); 
  1014.  
  1015. /** 
  1016. * Determines if the instance is a leap year 
  1017. * @return bool 
  1018. */ 
  1019. public function isLeapYear() 
  1020. return $this->format('L') === '1'; 
  1021.  
  1022. /** 
  1023. * Checks if the passed in date is the same day as the instance current day. 
  1024. * @param Carbon $dt 
  1025. * @return bool 
  1026. */ 
  1027. public function isSameDay(Carbon $dt) 
  1028. return $this->toDateString() === $dt->toDateString(); 
  1029.  
  1030. /** 
  1031. * Checks if this day is a Sunday. 
  1032. * @return bool 
  1033. */ 
  1034. public function isSunday() 
  1035. return $this->dayOfWeek === static::SUNDAY; 
  1036.  
  1037. /** 
  1038. * Checks if this day is a Monday. 
  1039. * @return bool 
  1040. */ 
  1041. public function isMonday() 
  1042. return $this->dayOfWeek === static::MONDAY; 
  1043.  
  1044. /** 
  1045. * Checks if this day is a Tuesday. 
  1046. * @return bool 
  1047. */ 
  1048. public function isTuesday() 
  1049. return $this->dayOfWeek === static::TUESDAY; 
  1050.  
  1051. /** 
  1052. * Checks if this day is a Wednesday. 
  1053. * @return bool 
  1054. */ 
  1055. public function isWednesday() 
  1056. return $this->dayOfWeek === static::WEDNESDAY; 
  1057.  
  1058. /** 
  1059. * Checks if this day is a Thursday. 
  1060. * @return bool 
  1061. */ 
  1062. public function isThursday() 
  1063. return $this->dayOfWeek === static::THURSDAY; 
  1064.  
  1065. /** 
  1066. * Checks if this day is a Friday. 
  1067. * @return bool 
  1068. */ 
  1069. public function isFriday() 
  1070. return $this->dayOfWeek === static::FRIDAY; 
  1071.  
  1072. /** 
  1073. * Checks if this day is a Saturday. 
  1074. * @return bool 
  1075. */ 
  1076. public function isSaturday() 
  1077. return $this->dayOfWeek === static::SATURDAY; 
  1078.  
  1079. /////////////////////////////////////////////////////////////////// 
  1080. /////////////////// ADDITIONS AND SUBTRACTIONS //////////////////// 
  1081. /////////////////////////////////////////////////////////////////// 
  1082.  
  1083. /** 
  1084. * Add years to the instance. Positive $value travel forward while 
  1085. * negative $value travel into the past. 
  1086. * @param int $value 
  1087. * @return static 
  1088. */ 
  1089. public function addYears($value) 
  1090. return $this->modify((int) $value.' year'); 
  1091.  
  1092. /** 
  1093. * Add a year to the instance 
  1094. * @param int $value 
  1095. * @return static 
  1096. */ 
  1097. public function addYear($value = 1) 
  1098. return $this->addYears($value); 
  1099.  
  1100. /** 
  1101. * Remove a year from the instance 
  1102. * @param int $value 
  1103. * @return static 
  1104. */ 
  1105. public function subYear($value = 1) 
  1106. return $this->subYears($value); 
  1107.  
  1108. /** 
  1109. * Remove years from the instance. 
  1110. * @param int $value 
  1111. * @return static 
  1112. */ 
  1113. public function subYears($value) 
  1114. return $this->addYears(-1 * $value); 
  1115.  
  1116. /** 
  1117. * Add months to the instance. Positive $value travels forward while 
  1118. * negative $value travels into the past. 
  1119. * @param int $value 
  1120. * @return static 
  1121. */ 
  1122. public function addMonths($value) 
  1123. return $this->modify((int) $value.' month'); 
  1124.  
  1125. /** 
  1126. * Add a month to the instance 
  1127. * @param int $value 
  1128. * @return static 
  1129. */ 
  1130. public function addMonth($value = 1) 
  1131. return $this->addMonths($value); 
  1132.  
  1133. /** 
  1134. * Remove a month from the instance 
  1135. * @param int $value 
  1136. * @return static 
  1137. */ 
  1138. public function subMonth($value = 1) 
  1139. return $this->subMonths($value); 
  1140.  
  1141. /** 
  1142. * Remove months from the instance 
  1143. * @param int $value 
  1144. * @return static 
  1145. */ 
  1146. public function subMonths($value) 
  1147. return $this->addMonths(-1 * $value); 
  1148.  
  1149. /** 
  1150. * Add months without overflowing to the instance. Positive $value 
  1151. * travels forward while negative $value travels into the past. 
  1152. * @param int $value 
  1153. * @return static 
  1154. */ 
  1155. public function addMonthsNoOverflow($value) 
  1156. $date = $this->copy()->addMonths($value); 
  1157.  
  1158. if ($date->day !== $this->day) { 
  1159. $date->day(1)->subMonth()->day($date->daysInMonth); 
  1160.  
  1161. return $date; 
  1162.  
  1163. /** 
  1164. * Add a month with no overflow to the instance 
  1165. * @param int $value 
  1166. * @return static 
  1167. */ 
  1168. public function addMonthNoOverflow($value = 1) 
  1169. return $this->addMonthsNoOverflow($value); 
  1170.  
  1171. /** 
  1172. * Remove a month with no overflow from the instance 
  1173. * @param int $value 
  1174. * @return static 
  1175. */ 
  1176. public function subMonthNoOverflow($value = 1) 
  1177. return $this->subMonthsNoOverflow($value); 
  1178.  
  1179. /** 
  1180. * Remove months with no overflow from the instance 
  1181. * @param int $value 
  1182. * @return static 
  1183. */ 
  1184. public function subMonthsNoOverflow($value) 
  1185. return $this->addMonthsNoOverflow(-1 * $value); 
  1186.  
  1187. /** 
  1188. * Add days to the instance. Positive $value travels forward while 
  1189. * negative $value travels into the past. 
  1190. * @param int $value 
  1191. * @return static 
  1192. */ 
  1193. public function addDays($value) 
  1194. return $this->modify((int) $value.' day'); 
  1195.  
  1196. /** 
  1197. * Add a day to the instance 
  1198. * @param int $value 
  1199. * @return static 
  1200. */ 
  1201. public function addDay($value = 1) 
  1202. return $this->addDays($value); 
  1203.  
  1204. /** 
  1205. * Remove a day from the instance 
  1206. * @param int $value 
  1207. * @return static 
  1208. */ 
  1209. public function subDay($value = 1) 
  1210. return $this->subDays($value); 
  1211.  
  1212. /** 
  1213. * Remove days from the instance 
  1214. * @param int $value 
  1215. * @return static 
  1216. */ 
  1217. public function subDays($value) 
  1218. return $this->addDays(-1 * $value); 
  1219.  
  1220. /** 
  1221. * Add weekdays to the instance. Positive $value travels forward while 
  1222. * negative $value travels into the past. 
  1223. * @param int $value 
  1224. * @return static 
  1225. */ 
  1226. public function addWeekdays($value) 
  1227. return $this->modify((int) $value.' weekday'); 
  1228.  
  1229. /** 
  1230. * Add a weekday to the instance 
  1231. * @param int $value 
  1232. * @return static 
  1233. */ 
  1234. public function addWeekday($value = 1) 
  1235. return $this->addWeekdays($value); 
  1236.  
  1237. /** 
  1238. * Remove a weekday from the instance 
  1239. * @param int $value 
  1240. * @return static 
  1241. */ 
  1242. public function subWeekday($value = 1) 
  1243. return $this->subWeekdays($value); 
  1244.  
  1245. /** 
  1246. * Remove weekdays from the instance 
  1247. * @param int $value 
  1248. * @return static 
  1249. */ 
  1250. public function subWeekdays($value) 
  1251. return $this->addWeekdays(-1 * $value); 
  1252.  
  1253. /** 
  1254. * Add weeks to the instance. Positive $value travels forward while 
  1255. * negative $value travels into the past. 
  1256. * @param int $value 
  1257. * @return static 
  1258. */ 
  1259. public function addWeeks($value) 
  1260. return $this->modify((int) $value.' week'); 
  1261.  
  1262. /** 
  1263. * Add a week to the instance 
  1264. * @param int $value 
  1265. * @return static 
  1266. */ 
  1267. public function addWeek($value = 1) 
  1268. return $this->addWeeks($value); 
  1269.  
  1270. /** 
  1271. * Remove a week from the instance 
  1272. * @param int $value 
  1273. * @return static 
  1274. */ 
  1275. public function subWeek($value = 1) 
  1276. return $this->subWeeks($value); 
  1277.  
  1278. /** 
  1279. * Remove weeks to the instance 
  1280. * @param int $value 
  1281. * @return static 
  1282. */ 
  1283. public function subWeeks($value) 
  1284. return $this->addWeeks(-1 * $value); 
  1285.  
  1286. /** 
  1287. * Add hours to the instance. Positive $value travels forward while 
  1288. * negative $value travels into the past. 
  1289. * @param int $value 
  1290. * @return static 
  1291. */ 
  1292. public function addHours($value) 
  1293. return $this->modify((int) $value.' hour'); 
  1294.  
  1295. /** 
  1296. * Add an hour to the instance 
  1297. * @param int $value 
  1298. * @return static 
  1299. */ 
  1300. public function addHour($value = 1) 
  1301. return $this->addHours($value); 
  1302.  
  1303. /** 
  1304. * Remove an hour from the instance 
  1305. * @param int $value 
  1306. * @return static 
  1307. */ 
  1308. public function subHour($value = 1) 
  1309. return $this->subHours($value); 
  1310.  
  1311. /** 
  1312. * Remove hours from the instance 
  1313. * @param int $value 
  1314. * @return static 
  1315. */ 
  1316. public function subHours($value) 
  1317. return $this->addHours(-1 * $value); 
  1318.  
  1319. /** 
  1320. * Add minutes to the instance. Positive $value travels forward while 
  1321. * negative $value travels into the past. 
  1322. * @param int $value 
  1323. * @return static 
  1324. */ 
  1325. public function addMinutes($value) 
  1326. return $this->modify((int) $value.' minute'); 
  1327.  
  1328. /** 
  1329. * Add a minute to the instance 
  1330. * @param int $value 
  1331. * @return static 
  1332. */ 
  1333. public function addMinute($value = 1) 
  1334. return $this->addMinutes($value); 
  1335.  
  1336. /** 
  1337. * Remove a minute from the instance 
  1338. * @param int $value 
  1339. * @return static 
  1340. */ 
  1341. public function subMinute($value = 1) 
  1342. return $this->subMinutes($value); 
  1343.  
  1344. /** 
  1345. * Remove minutes from the instance 
  1346. * @param int $value 
  1347. * @return static 
  1348. */ 
  1349. public function subMinutes($value) 
  1350. return $this->addMinutes(-1 * $value); 
  1351.  
  1352. /** 
  1353. * Add seconds to the instance. Positive $value travels forward while 
  1354. * negative $value travels into the past. 
  1355. * @param int $value 
  1356. * @return static 
  1357. */ 
  1358. public function addSeconds($value) 
  1359. return $this->modify((int) $value.' second'); 
  1360.  
  1361. /** 
  1362. * Add a second to the instance 
  1363. * @param int $value 
  1364. * @return static 
  1365. */ 
  1366. public function addSecond($value = 1) 
  1367. return $this->addSeconds($value); 
  1368.  
  1369. /** 
  1370. * Remove a second from the instance 
  1371. * @param int $value 
  1372. * @return static 
  1373. */ 
  1374. public function subSecond($value = 1) 
  1375. return $this->subSeconds($value); 
  1376.  
  1377. /** 
  1378. * Remove seconds from the instance 
  1379. * @param int $value 
  1380. * @return static 
  1381. */ 
  1382. public function subSeconds($value) 
  1383. return $this->addSeconds(-1 * $value); 
  1384.  
  1385. /////////////////////////////////////////////////////////////////// 
  1386. /////////////////////////// DIFFERENCES /////////////////////////// 
  1387. /////////////////////////////////////////////////////////////////// 
  1388.  
  1389. /** 
  1390. * Get the difference in years 
  1391. * @param Carbon|null $dt 
  1392. * @param bool $abs Get the absolute of the difference 
  1393. * @return int 
  1394. */ 
  1395. public function diffInYears(Carbon $dt = null, $abs = true) 
  1396. $dt = $dt ?: static::now($this->tz); 
  1397.  
  1398. return (int) $this->diff($dt, $abs)->format('%r%y'); 
  1399.  
  1400. /** 
  1401. * Get the difference in months 
  1402. * @param Carbon|null $dt 
  1403. * @param bool $abs Get the absolute of the difference 
  1404. * @return int 
  1405. */ 
  1406. public function diffInMonths(Carbon $dt = null, $abs = true) 
  1407. $dt = $dt ?: static::now($this->tz); 
  1408.  
  1409. return $this->diffInYears($dt, $abs) * static::MONTHS_PER_YEAR + (int) $this->diff($dt, $abs)->format('%r%m'); 
  1410.  
  1411. /** 
  1412. * Get the difference in weeks 
  1413. * @param Carbon|null $dt 
  1414. * @param bool $abs Get the absolute of the difference 
  1415. * @return int 
  1416. */ 
  1417. public function diffInWeeks(Carbon $dt = null, $abs = true) 
  1418. return (int) ($this->diffInDays($dt, $abs) / static::DAYS_PER_WEEK); 
  1419.  
  1420. /** 
  1421. * Get the difference in days 
  1422. * @param Carbon|null $dt 
  1423. * @param bool $abs Get the absolute of the difference 
  1424. * @return int 
  1425. */ 
  1426. public function diffInDays(Carbon $dt = null, $abs = true) 
  1427. $dt = $dt ?: static::now($this->tz); 
  1428.  
  1429. return (int) $this->diff($dt, $abs)->format('%r%a'); 
  1430.  
  1431. /** 
  1432. * Get the difference in days using a filter closure 
  1433. * @param Closure $callback 
  1434. * @param Carbon|null $dt 
  1435. * @param bool $abs Get the absolute of the difference 
  1436. * @return int 
  1437. */ 
  1438. public function diffInDaysFiltered(Closure $callback, Carbon $dt = null, $abs = true) 
  1439. return $this->diffFiltered(CarbonInterval::day(), $callback, $dt, $abs); 
  1440.  
  1441. /** 
  1442. * Get the difference in hours using a filter closure 
  1443. * @param Closure $callback 
  1444. * @param Carbon|null $dt 
  1445. * @param bool $abs Get the absolute of the difference 
  1446. * @return int 
  1447. */ 
  1448. public function diffInHoursFiltered(Closure $callback, Carbon $dt = null, $abs = true) 
  1449. return $this->diffFiltered(CarbonInterval::hour(), $callback, $dt, $abs); 
  1450.  
  1451. /** 
  1452. * Get the difference by the given interval using a filter closure 
  1453. * @param CarbonInterval $ci An interval to traverse by 
  1454. * @param Closure $callback 
  1455. * @param Carbon|null $dt 
  1456. * @param bool $abs Get the absolute of the difference 
  1457. * @return int 
  1458. */ 
  1459. public function diffFiltered(CarbonInterval $ci, Closure $callback, Carbon $dt = null, $abs = true) 
  1460. $start = $this; 
  1461. $end = $dt ?: static::now($this->tz); 
  1462. $inverse = false; 
  1463.  
  1464. if ($end < $start) { 
  1465. $start = $end; 
  1466. $end = $this; 
  1467. $inverse = true; 
  1468.  
  1469. $period = new DatePeriod($start, $ci, $end); 
  1470. $vals = array_filter(iterator_to_array($period), function (DateTime $date) use ($callback) { 
  1471. return call_user_func($callback, Carbon::instance($date)); 
  1472. }); 
  1473.  
  1474. $diff = count($vals); 
  1475.  
  1476. return $inverse && !$abs ? -$diff : $diff; 
  1477.  
  1478. /** 
  1479. * Get the difference in weekdays 
  1480. * @param Carbon|null $dt 
  1481. * @param bool $abs Get the absolute of the difference 
  1482. * @return int 
  1483. */ 
  1484. public function diffInWeekdays(Carbon $dt = null, $abs = true) 
  1485. return $this->diffInDaysFiltered(function (Carbon $date) { 
  1486. return $date->isWeekday(); 
  1487. }, $dt, $abs); 
  1488.  
  1489. /** 
  1490. * Get the difference in weekend days using a filter 
  1491. * @param Carbon|null $dt 
  1492. * @param bool $abs Get the absolute of the difference 
  1493. * @return int 
  1494. */ 
  1495. public function diffInWeekendDays(Carbon $dt = null, $abs = true) 
  1496. return $this->diffInDaysFiltered(function (Carbon $date) { 
  1497. return $date->isWeekend(); 
  1498. }, $dt, $abs); 
  1499.  
  1500. /** 
  1501. * Get the difference in hours 
  1502. * @param Carbon|null $dt 
  1503. * @param bool $abs Get the absolute of the difference 
  1504. * @return int 
  1505. */ 
  1506. public function diffInHours(Carbon $dt = null, $abs = true) 
  1507. return (int) ($this->diffInSeconds($dt, $abs) / static::SECONDS_PER_MINUTE / static::MINUTES_PER_HOUR); 
  1508.  
  1509. /** 
  1510. * Get the difference in minutes 
  1511. * @param Carbon|null $dt 
  1512. * @param bool $abs Get the absolute of the difference 
  1513. * @return int 
  1514. */ 
  1515. public function diffInMinutes(Carbon $dt = null, $abs = true) 
  1516. return (int) ($this->diffInSeconds($dt, $abs) / static::SECONDS_PER_MINUTE); 
  1517.  
  1518. /** 
  1519. * Get the difference in seconds 
  1520. * @param Carbon|null $dt 
  1521. * @param bool $abs Get the absolute of the difference 
  1522. * @return int 
  1523. */ 
  1524. public function diffInSeconds(Carbon $dt = null, $abs = true) 
  1525. $dt = $dt ?: static::now($this->tz); 
  1526. $value = $dt->getTimestamp() - $this->getTimestamp(); 
  1527.  
  1528. return $abs ? abs($value) : $value; 
  1529.  
  1530. /** 
  1531. * The number of seconds since midnight. 
  1532. * @return int 
  1533. */ 
  1534. public function secondsSinceMidnight() 
  1535. return $this->diffInSeconds($this->copy()->startOfDay()); 
  1536.  
  1537. /** 
  1538. * The number of seconds until 23:23:59. 
  1539. * @return int 
  1540. */ 
  1541. public function secondsUntilEndOfDay() 
  1542. return $this->diffInSeconds($this->copy()->endOfDay()); 
  1543.  
  1544. /** 
  1545. * Get the difference in a human readable format in the current locale. 
  1546. * When comparing a value in the past to default now: 
  1547. * 1 hour ago 
  1548. * 5 months ago 
  1549. * When comparing a value in the future to default now: 
  1550. * 1 hour from now 
  1551. * 5 months from now 
  1552. * When comparing a value in the past to another value: 
  1553. * 1 hour before 
  1554. * 5 months before 
  1555. * When comparing a value in the future to another value: 
  1556. * 1 hour after 
  1557. * 5 months after 
  1558. * @param Carbon|null $other 
  1559. * @param bool $absolute removes time difference modifiers ago, after, etc 
  1560. * @return string 
  1561. */ 
  1562. public function diffForHumans(Carbon $other = null, $absolute = false) 
  1563. $isNow = $other === null; 
  1564.  
  1565. if ($isNow) { 
  1566. $other = static::now($this->tz); 
  1567.  
  1568. $diffInterval = $this->diff($other); 
  1569.  
  1570. switch (true) { 
  1571. case ($diffInterval->y > 0): 
  1572. $unit = 'year'; 
  1573. $count = $diffInterval->y; 
  1574. break; 
  1575.  
  1576. case ($diffInterval->m > 0): 
  1577. $unit = 'month'; 
  1578. $count = $diffInterval->m; 
  1579. break; 
  1580.  
  1581. case ($diffInterval->d > 0): 
  1582. $unit = 'day'; 
  1583. $count = $diffInterval->d; 
  1584. if ($count >= self::DAYS_PER_WEEK) { 
  1585. $unit = 'week'; 
  1586. $count = (int) ($count / self::DAYS_PER_WEEK); 
  1587. break; 
  1588.  
  1589. case ($diffInterval->h > 0): 
  1590. $unit = 'hour'; 
  1591. $count = $diffInterval->h; 
  1592. break; 
  1593.  
  1594. case ($diffInterval->i > 0): 
  1595. $unit = 'minute'; 
  1596. $count = $diffInterval->i; 
  1597. break; 
  1598.  
  1599. default: 
  1600. $count = $diffInterval->s; 
  1601. $unit = 'second'; 
  1602. break; 
  1603.  
  1604. if ($count === 0) { 
  1605. $count = 1; 
  1606.  
  1607. $time = static::translator()->transChoice($unit, $count, array(':count' => $count)); 
  1608.  
  1609. if ($absolute) { 
  1610. return $time; 
  1611.  
  1612. $isFuture = $diffInterval->invert === 1; 
  1613.  
  1614. $transId = $isNow ? ($isFuture ? 'from_now' : 'ago') : ($isFuture ? 'after' : 'before'); 
  1615.  
  1616. // Some langs have special pluralization for past and future tense. 
  1617. $tryKeyExists = $unit.'_'.$transId; 
  1618. if ($tryKeyExists !== static::translator()->transChoice($tryKeyExists, $count)) { 
  1619. $time = static::translator()->transChoice($tryKeyExists, $count, array(':count' => $count)); 
  1620.  
  1621. return static::translator()->trans($transId, array(':time' => $time)); 
  1622.  
  1623. /////////////////////////////////////////////////////////////////// 
  1624. //////////////////////////// MODIFIERS //////////////////////////// 
  1625. /////////////////////////////////////////////////////////////////// 
  1626.  
  1627. /** 
  1628. * Resets the time to 00:00:00 
  1629. * @return static 
  1630. */ 
  1631. public function startOfDay() 
  1632. return $this->hour(0)->minute(0)->second(0); 
  1633.  
  1634. /** 
  1635. * Resets the time to 23:59:59 
  1636. * @return static 
  1637. */ 
  1638. public function endOfDay() 
  1639. return $this->hour(23)->minute(59)->second(59); 
  1640.  
  1641. /** 
  1642. * Resets the date to the first day of the month and the time to 00:00:00 
  1643. * @return static 
  1644. */ 
  1645. public function startOfMonth() 
  1646. return $this->startOfDay()->day(1); 
  1647.  
  1648. /** 
  1649. * Resets the date to end of the month and time to 23:59:59 
  1650. * @return static 
  1651. */ 
  1652. public function endOfMonth() 
  1653. return $this->day($this->daysInMonth)->endOfDay(); 
  1654.  
  1655. /** 
  1656. * Resets the date to the first day of the year and the time to 00:00:00 
  1657. * @return static 
  1658. */ 
  1659. public function startOfYear() 
  1660. return $this->month(1)->startOfMonth(); 
  1661.  
  1662. /** 
  1663. * Resets the date to end of the year and time to 23:59:59 
  1664. * @return static 
  1665. */ 
  1666. public function endOfYear() 
  1667. return $this->month(static::MONTHS_PER_YEAR)->endOfMonth(); 
  1668.  
  1669. /** 
  1670. * Resets the date to the first day of the decade and the time to 00:00:00 
  1671. * @return static 
  1672. */ 
  1673. public function startOfDecade() 
  1674. return $this->startOfYear()->year($this->year - $this->year % static::YEARS_PER_DECADE); 
  1675.  
  1676. /** 
  1677. * Resets the date to end of the decade and time to 23:59:59 
  1678. * @return static 
  1679. */ 
  1680. public function endOfDecade() 
  1681. return $this->endOfYear()->year($this->year - $this->year % static::YEARS_PER_DECADE + static::YEARS_PER_DECADE - 1); 
  1682.  
  1683. /** 
  1684. * Resets the date to the first day of the century and the time to 00:00:00 
  1685. * @return static 
  1686. */ 
  1687. public function startOfCentury() 
  1688. return $this->startOfYear()->year($this->year - $this->year % static::YEARS_PER_CENTURY); 
  1689.  
  1690. /** 
  1691. * Resets the date to end of the century and time to 23:59:59 
  1692. * @return static 
  1693. */ 
  1694. public function endOfCentury() 
  1695. return $this->endOfYear()->year($this->year - $this->year % static::YEARS_PER_CENTURY + static::YEARS_PER_CENTURY - 1); 
  1696.  
  1697. /** 
  1698. * Resets the date to the first day of week (defined in $weekStartsAt) and the time to 00:00:00 
  1699. * @return static 
  1700. */ 
  1701. public function startOfWeek() 
  1702. if ($this->dayOfWeek !== static::$weekStartsAt) { 
  1703. $this->previous(static::$weekStartsAt); 
  1704.  
  1705. return $this->startOfDay(); 
  1706.  
  1707. /** 
  1708. * Resets the date to end of week (defined in $weekEndsAt) and time to 23:59:59 
  1709. * @return static 
  1710. */ 
  1711. public function endOfWeek() 
  1712. if ($this->dayOfWeek !== static::$weekEndsAt) { 
  1713. $this->next(static::$weekEndsAt); 
  1714.  
  1715. return $this->endOfDay(); 
  1716.  
  1717. /** 
  1718. * Modify to the next occurrence of a given day of the week. 
  1719. * If no dayOfWeek is provided, modify to the next occurrence 
  1720. * of the current day of the week. Use the supplied consts 
  1721. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1722. * @param int|null $dayOfWeek 
  1723. * @return static 
  1724. */ 
  1725. public function next($dayOfWeek = null) 
  1726. if ($dayOfWeek === null) { 
  1727. $dayOfWeek = $this->dayOfWeek; 
  1728.  
  1729. return $this->startOfDay()->modify('next '.static::$days[$dayOfWeek]); 
  1730.  
  1731. /** 
  1732. * Modify to the previous occurrence of a given day of the week. 
  1733. * If no dayOfWeek is provided, modify to the previous occurrence 
  1734. * of the current day of the week. Use the supplied consts 
  1735. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1736. * @param int|null $dayOfWeek 
  1737. * @return static 
  1738. */ 
  1739. public function previous($dayOfWeek = null) 
  1740. if ($dayOfWeek === null) { 
  1741. $dayOfWeek = $this->dayOfWeek; 
  1742.  
  1743. return $this->startOfDay()->modify('last '.static::$days[$dayOfWeek]); 
  1744.  
  1745. /** 
  1746. * Modify to the first occurrence of a given day of the week 
  1747. * in the current month. If no dayOfWeek is provided, modify to the 
  1748. * first day of the current month. Use the supplied consts 
  1749. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1750. * @param int|null $dayOfWeek 
  1751. * @return static 
  1752. */ 
  1753. public function firstOfMonth($dayOfWeek = null) 
  1754. $this->startOfDay(); 
  1755.  
  1756. if ($dayOfWeek === null) { 
  1757. return $this->day(1); 
  1758.  
  1759. return $this->modify('first '.static::$days[$dayOfWeek].' of '.$this->format('F').' '.$this->year); 
  1760.  
  1761. /** 
  1762. * Modify to the last occurrence of a given day of the week 
  1763. * in the current month. If no dayOfWeek is provided, modify to the 
  1764. * last day of the current month. Use the supplied consts 
  1765. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1766. * @param int|null $dayOfWeek 
  1767. * @return static 
  1768. */ 
  1769. public function lastOfMonth($dayOfWeek = null) 
  1770. $this->startOfDay(); 
  1771.  
  1772. if ($dayOfWeek === null) { 
  1773. return $this->day($this->daysInMonth); 
  1774.  
  1775. return $this->modify('last '.static::$days[$dayOfWeek].' of '.$this->format('F').' '.$this->year); 
  1776.  
  1777. /** 
  1778. * Modify to the given occurrence of a given day of the week 
  1779. * in the current month. If the calculated occurrence is outside the scope 
  1780. * of the current month, then return false and no modifications are made. 
  1781. * Use the supplied consts to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1782. * @param int $nth 
  1783. * @param int $dayOfWeek 
  1784. * @return mixed 
  1785. */ 
  1786. public function nthOfMonth($nth, $dayOfWeek) 
  1787. $dt = $this->copy()->firstOfMonth(); 
  1788. $check = $dt->format('Y-m'); 
  1789. $dt->modify('+'.$nth.' '.static::$days[$dayOfWeek]); 
  1790.  
  1791. return $dt->format('Y-m') === $check ? $this->modify($dt) : false; 
  1792.  
  1793. /** 
  1794. * Modify to the first occurrence of a given day of the week 
  1795. * in the current quarter. If no dayOfWeek is provided, modify to the 
  1796. * first day of the current quarter. Use the supplied consts 
  1797. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1798. * @param int|null $dayOfWeek 
  1799. * @return static 
  1800. */ 
  1801. public function firstOfQuarter($dayOfWeek = null) 
  1802. return $this->day(1)->month($this->quarter * 3 - 2)->firstOfMonth($dayOfWeek); 
  1803.  
  1804. /** 
  1805. * Modify to the last occurrence of a given day of the week 
  1806. * in the current quarter. If no dayOfWeek is provided, modify to the 
  1807. * last day of the current quarter. Use the supplied consts 
  1808. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1809. * @param int|null $dayOfWeek 
  1810. * @return static 
  1811. */ 
  1812. public function lastOfQuarter($dayOfWeek = null) 
  1813. return $this->day(1)->month($this->quarter * 3)->lastOfMonth($dayOfWeek); 
  1814.  
  1815. /** 
  1816. * Modify to the given occurrence of a given day of the week 
  1817. * in the current quarter. If the calculated occurrence is outside the scope 
  1818. * of the current quarter, then return false and no modifications are made. 
  1819. * Use the supplied consts to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1820. * @param int $nth 
  1821. * @param int $dayOfWeek 
  1822. * @return mixed 
  1823. */ 
  1824. public function nthOfQuarter($nth, $dayOfWeek) 
  1825. $dt = $this->copy()->day(1)->month($this->quarter * 3); 
  1826. $lastMonth = $dt->month; 
  1827. $year = $dt->year; 
  1828. $dt->firstOfQuarter()->modify('+'.$nth.' '.static::$days[$dayOfWeek]); 
  1829.  
  1830. return ($lastMonth < $dt->month || $year !== $dt->year) ? false : $this->modify($dt); 
  1831.  
  1832. /** 
  1833. * Modify to the first occurrence of a given day of the week 
  1834. * in the current year. If no dayOfWeek is provided, modify to the 
  1835. * first day of the current year. Use the supplied consts 
  1836. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1837. * @param int|null $dayOfWeek 
  1838. * @return static 
  1839. */ 
  1840. public function firstOfYear($dayOfWeek = null) 
  1841. return $this->month(1)->firstOfMonth($dayOfWeek); 
  1842.  
  1843. /** 
  1844. * Modify to the last occurrence of a given day of the week 
  1845. * in the current year. If no dayOfWeek is provided, modify to the 
  1846. * last day of the current year. Use the supplied consts 
  1847. * to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1848. * @param int|null $dayOfWeek 
  1849. * @return static 
  1850. */ 
  1851. public function lastOfYear($dayOfWeek = null) 
  1852. return $this->month(static::MONTHS_PER_YEAR)->lastOfMonth($dayOfWeek); 
  1853.  
  1854. /** 
  1855. * Modify to the given occurrence of a given day of the week 
  1856. * in the current year. If the calculated occurrence is outside the scope 
  1857. * of the current year, then return false and no modifications are made. 
  1858. * Use the supplied consts to indicate the desired dayOfWeek, ex. static::MONDAY. 
  1859. * @param int $nth 
  1860. * @param int $dayOfWeek 
  1861. * @return mixed 
  1862. */ 
  1863. public function nthOfYear($nth, $dayOfWeek) 
  1864. $dt = $this->copy()->firstOfYear()->modify('+'.$nth.' '.static::$days[$dayOfWeek]); 
  1865.  
  1866. return $this->year === $dt->year ? $this->modify($dt) : false; 
  1867.  
  1868. /** 
  1869. * Modify the current instance to the average of a given instance (default now) and the current instance. 
  1870. * @param Carbon|null $dt 
  1871. * @return static 
  1872. */ 
  1873. public function average(Carbon $dt = null) 
  1874. $dt = $dt ?: static::now($this->tz); 
  1875.  
  1876. return $this->addSeconds((int) ($this->diffInSeconds($dt, false) / 2)); 
  1877.  
  1878. /** 
  1879. * Check if its the birthday. Compares the date/month values of the two dates. 
  1880. * @param Carbon|null $dt The instance to compare with or null to use current day. 
  1881. * @return bool 
  1882. */ 
  1883. public function isBirthday(Carbon $dt = null) 
  1884. $dt = $dt ?: static::now($this->tz); 
  1885.  
  1886. return $this->format('md') === $dt->format('md');