PageRenderTime 51ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 0ms

/vendor/nesbot/carbon/readme.md

https://gitlab.com/hecto932/mejorandolaravel_america
Markdown | 865 lines | 641 code | 224 blank | 0 comment | 0 complexity | 8ec7d9bd69bad989ddbd2ef7819a6fa9 MD5 | raw file
Possible License(s): MIT, BSD-3-Clause
  1. > **This file is autogenerated. Please see the [Contributing](#about-contributing) section from more information.**
  2. # Carbon
  3. [![Latest Stable Version](https://poser.pugx.org/nesbot/carbon/v/stable.png)](https://packagist.org/packages/nesbot/carbon) [![Total Downloads](https://poser.pugx.org/nesbot/carbon/downloads.png)](https://packagist.org/packages/nesbot/carbon) [![Build Status](https://secure.travis-ci.org/briannesbitt/Carbon.png)](http://travis-ci.org/briannesbitt/Carbon)
  4. A simple API extension for DateTime with PHP 5.3+
  5. ```php
  6. printf("Right now is %s", Carbon::now()->toDateTimeString());
  7. printf("Right now in Vancouver is %s", Carbon::now('America/Vancouver')); //implicit __toString()
  8. $tomorrow = Carbon::now()->addDay();
  9. $lastWeek = Carbon::now()->subWeek();
  10. $nextSummerOlympics = Carbon::createFromDate(2012)->addYears(4);
  11. $officialDate = Carbon::now()->toRFC2822String();
  12. $howOldAmI = Carbon::createFromDate(1975, 5, 21)->age;
  13. $noonTodayLondonTime = Carbon::createFromTime(12, 0, 0, 'Europe/London');
  14. $worldWillEnd = Carbon::createFromDate(2012, 12, 21, 'GMT');
  15. // Don't really want to die so mock now
  16. Carbon::setTestNow(Carbon::createFromDate(2000, 1, 1));
  17. // comparisons are always done in UTC
  18. if (Carbon::now()->gte($worldWillEnd)) {
  19. die();
  20. }
  21. // Phew! Return to normal behaviour
  22. Carbon::setTestNow();
  23. if (Carbon::now()->isWeekend()) {
  24. echo 'Party!';
  25. }
  26. echo Carbon::now()->subMinutes(2)->diffForHumans(); // '2 minutes ago'
  27. // ... but also does 'from now', 'after' and 'before'
  28. // rolling up to seconds, minutes, hours, days, months, years
  29. $daysSinceEpoch = Carbon::createFromTimeStamp(0)->diffInDays();
  30. ```
  31. ## README Contents
  32. * [Installation](#install)
  33. * [Requirements](#requirements)
  34. * [With composer](#install-composer)
  35. * [Without composer](#install-nocomposer)
  36. * [API](#api)
  37. * [Instantiation](#api-instantiation)
  38. * [Testing Aids](#api-testing)
  39. * [Getters](#api-getters)
  40. * [Setters](#api-setters)
  41. * [Fluent Setters](#api-settersfluent)
  42. * [IsSet](#api-isset)
  43. * [String Formatting and Localization](#api-formatting)
  44. * [Common Formats](#api-commonformats)
  45. * [Comparison](#api-comparison)
  46. * [Addition and Subtraction](#api-addsub)
  47. * [Difference](#api-difference)
  48. * [Difference for Humans](#api-humandiff)
  49. * [Modifiers](#api-modifiers)
  50. * [Constants](#api-constants)
  51. * [About](#about)
  52. * [Contributing](#about-contributing)
  53. * [Author](#about-author)
  54. * [License](#about-license)
  55. * [History](#about-history)
  56. * [Why the name Carbon?](#about-whyname)
  57. <a name="install"/>
  58. ## Installation
  59. <a name="requirements"/>
  60. ### Requirements
  61. - Any flavour of PHP 5.3+ should do
  62. - [optional] PHPUnit to execute the test suite
  63. <a name="install-composer"/>
  64. ### With Composer
  65. The easiest way to install Carbon is via [composer](http://getcomposer.org/). Create the following `composer.json` file and run the `php composer.phar install` command to install it.
  66. ```json
  67. {
  68. "require": {
  69. "nesbot/Carbon": "*"
  70. }
  71. }
  72. ```
  73. ```php
  74. <?php
  75. require 'vendor/autoload.php';
  76. use Carbon\Carbon;
  77. printf("Now: %s", Carbon::now());
  78. ```
  79. <a name="install-nocomposer"/>
  80. ### Without Composer
  81. Why are you not using [composer](http://getcomposer.org/)? Download [Carbon.php](https://github.com/briannesbitt/Carbon/blob/master/Carbon/Carbon.php) from the repo and save the file into your project path somewhere.
  82. ```php
  83. <?php
  84. require 'path/to/Carbon.php';
  85. use Carbon\Carbon;
  86. printf("Now: %s", Carbon::now());
  87. ```
  88. <a name="api"/>
  89. ## API
  90. The Carbon class is [inherited](http://php.net/manual/en/keyword.extends.php) from the PHP [DateTime](http://www.php.net/manual/en/class.datetime.php) class.
  91. ```php
  92. <?php
  93. class Carbon extends \DateTime
  94. {
  95. // code here
  96. }
  97. ```
  98. Carbon has all of the functions inherited from the base DateTime class. This approach allows you to access the base functionality if you see anything missing in Carbon but is there in DateTime.
  99. > **Note: I live in Ottawa, Ontario, Canada and if the timezone is not specified in the examples then the default of 'America/Toronto' is to be assumed. Typically Ottawa is -0500 but when daylight savings time is on we are -0400.**
  100. Special care has been taken to ensure timezones are handled correctly, and where appropriate are based on the underlying DateTime implementation. For example all comparisons are done in UTC or in the timezone of the datetime being used.
  101. ```php
  102. $dtToronto = Carbon::createFromDate(2012, 1, 1, 'America/Toronto');
  103. $dtVancouver = Carbon::createFromDate(2012, 1, 1, 'America/Vancouver');
  104. echo $dtVancouver->diffInHours($dtToronto); // 3
  105. ```
  106. Also `is` comparisons are done in the timezone of the provided Carbon instance. For example my current timezone is -13 hours from Tokyo. So `Carbon::now('Asia/Tokyo')->isToday()` would only return false for any time past 1 PM my time. This doesn't make sense since `now()` in tokyo is always today in Tokyo. Thus the comparison to `now()` is done in the same timezone as the current instance.
  107. <a name="api-instantiation"/>
  108. ### Instantiation
  109. There are several different methods available to create a new instance of Carbon. First there is a constructor. It overrides the [parent constructor](http://www.php.net/manual/en/datetime.construct.php) and you are best to read about the first parameter from the PHP manual and understand the date/time string formats it accepts. You'll hopefully find yourself rarely using the constructor but rather relying on the explicit static methods for improved readability.
  110. ```php
  111. $carbon = new Carbon(); // equivalent to Carbon::now()
  112. $carbon = new Carbon('first day of January 2008', 'America/Vancouver');
  113. echo get_class($carbon); // 'Carbon\Carbon'
  114. ```
  115. You'll notice above that the timezone (2nd) parameter was passed as a string rather than a `\DateTimeZone` instance. All DateTimeZone parameters have been augmented so you can pass a DateTimeZone instance or a string and the timezone will be created for you. This is again shown in the next example which also introduces the `now()` function.
  116. ```php
  117. $now = Carbon::now();
  118. $nowInLondonTz = Carbon::now(new DateTimeZone('Europe/London'));
  119. // or just pass the timezone as a string
  120. $nowInLondonTz = Carbon::now('Europe/London');
  121. ```
  122. If you really love your fluid method calls and get frustrated by the extra line or ugly pair of brackets necessary when using the constructor you'll enjoy the `parse` method.
  123. ```php
  124. echo (new Carbon('first day of December 2008'))->addWeeks(2); // 2008-12-15 00:00:00
  125. echo Carbon::parse('first day of December 2008')->addWeeks(2); // 2008-12-15 00:00:00
  126. ```
  127. To accompany `now()`, a few other static instantiation helpers exist to create widely known instances. The only thing to really notice here is that `today()`, `tomorrow()` and `yesterday()`, besides behaving as expected, all accept a timezone parameter and each has their time value set to `00:00:00`.
  128. ```php
  129. $now = Carbon::now();
  130. echo $now; // 2014-01-06 22:52:03
  131. $today = Carbon::today();
  132. echo $today; // 2014-01-06 00:00:00
  133. $tomorrow = Carbon::tomorrow('Europe/London');
  134. echo $tomorrow; // 2014-01-08 00:00:00
  135. $yesterday = Carbon::yesterday();
  136. echo $yesterday; // 2014-01-05 00:00:00
  137. ```
  138. The next group of static helpers are the `createXXX()` helpers. Most of the static `create` functions allow you to provide as many or as few arguments as you want and will provide default values for all others. Generally default values are the current date, time or timezone. Higher values will wrap appropriately but invalid values will throw an `InvalidArgumentException` with an informative message. The message is obtained from an [DateTime::getLastErrors()](http://php.net/manual/en/datetime.getlasterrors.php) call.
  139. ```php
  140. Carbon::createFromDate($year, $month, $day, $tz);
  141. Carbon::createFromTime($hour, $minute, $second, $tz);
  142. Carbon::create($year, $month, $day, $hour, $minute, $second, $tz);
  143. ```
  144. `createFromDate()` will default the time to now. `createFromTime()` will default the date to today. `create()` will default any null parameter to the current respective value. As before, the `$tz` defaults to the current timezone and otherwise can be a DateTimeZone instance or simply a string timezone value. The only special case for default values (mimicking the underlying PHP library) occurs when an hour value is specified but no minutes or seconds, they will get defaulted to 0.
  145. ```php
  146. $xmasThisYear = Carbon::createFromDate(null, 12, 25); // Year defaults to current year
  147. $Y2K = Carbon::create(2000, 1, 1, 0, 0, 0);
  148. $alsoY2K = Carbon::create(1999, 12, 31, 24);
  149. $noonLondonTz = Carbon::createFromTime(12, 0, 0, 'Europe/London');
  150. // A two digit minute could not be found
  151. try { Carbon::create(1975, 5, 21, 22, -2, 0); } catch(InvalidArgumentException $x) { echo $x->getMessage(); }
  152. ```
  153. ```php
  154. Carbon::createFromFormat($format, $time, $tz);
  155. ```
  156. `createFromFormat()` is mostly a wrapper for the base php function [DateTime::createFromFormat](http://php.net/manual/en/datetime.createfromformat.php). The difference being again the `$tz` argument can be a DateTimeZone instance or a string timezone value. Also, if there are errors with the format this function will call the `DateTime::getLastErrors()` method and then throw a `InvalidArgumentException` with the errors as the message. If you look at the source for the `createXX()` functions above, they all make a call to `createFromFormat()`.
  157. ```php
  158. echo Carbon::createFromFormat('Y-m-d H', '1975-05-21 22')->toDateTimeString(); // 1975-05-21 22:00:00
  159. ```
  160. The final two create functions are for working with [unix timestamps](http://en.wikipedia.org/wiki/Unix_time). The first will create a Carbon instance equal to the given timestamp and will set the timezone as well or default it to the current timezone. The second, `createFromTimestampUTC()`, is different in that the timezone will remain UTC (GMT). The second acts the same as `Carbon::createFromFormat('@'.$timestamp)` but I have just made it a little more explicit. Negative timestamps are also allowed.
  161. ```php
  162. echo Carbon::createFromTimeStamp(-1)->toDateTimeString(); // 1969-12-31 18:59:59
  163. echo Carbon::createFromTimeStamp(-1, 'Europe/London')->toDateTimeString(); // 1970-01-01 00:59:59
  164. echo Carbon::createFromTimeStampUTC(-1)->toDateTimeString(); // 1969-12-31 23:59:59
  165. ```
  166. You can also create a `copy()` of an existing Carbon instance. As expected the date, time and timezone values are all copied to the new instance.
  167. ```php
  168. $dt = Carbon::now();
  169. echo $dt->diffInYears($dt->copy()->addYear()); // 1
  170. // $dt was unchanged and still holds the value of Carbon:now()
  171. ```
  172. Finally, if you find yourself inheriting a `\DateTime` instance from another library, fear not! You can create a `Carbon` instance via a friendly `instance()` function.
  173. ```php
  174. $dt = new \DateTime('first day of January 2008'); // <== instance from another API
  175. $carbon = Carbon::instance($dt);
  176. echo get_class($carbon); // 'Carbon\Carbon'
  177. echo $carbon->toDateTimeString(); // 2008-01-01 00:00:00
  178. ```
  179. <a name="api-testing"/>
  180. ### Testing Aids
  181. The testing methods allow you to set a Carbon instance (real or mock) to be returned when a "now" instance is created. The provided instance will be returned specifically under the following conditions:
  182. - A call to the static now() method, ex. Carbon::now()
  183. - When a null (or blank string) is passed to the constructor or parse(), ex. new Carbon(null)
  184. - When the string "now" is passed to the constructor or parse(), ex. new Carbon('now')
  185. ```php
  186. $knownDate = Carbon::create(2001, 5, 21, 12); // create testing date
  187. Carbon::setTestNow($knownDate); // set the mock (of course this could be a real mock object)
  188. echo Carbon::now(); // 2001-05-21 12:00:00
  189. echo new Carbon(); // 2001-05-21 12:00:00
  190. echo Carbon::parse(); // 2001-05-21 12:00:00
  191. echo new Carbon('now'); // 2001-05-21 12:00:00
  192. echo Carbon::parse('now'); // 2001-05-21 12:00:00
  193. var_dump(Carbon::hasTestNow()); // bool(true)
  194. Carbon::setTestNow(); // clear the mock
  195. var_dump(Carbon::hasTestNow()); // bool(false)
  196. echo Carbon::now(); // 2014-01-06 22:52:03
  197. ```
  198. A more meaning full example:
  199. ```php
  200. class SeasonalProduct
  201. {
  202. protected $price;
  203. public function __construct($price)
  204. {
  205. $this->price = $price;
  206. }
  207. public function getPrice() {
  208. $multiplier = 1;
  209. if (Carbon::now()->month == 12) {
  210. $multiplier = 2;
  211. }
  212. return $this->price * $multiplier;
  213. }
  214. }
  215. $product = new SeasonalProduct(100);
  216. Carbon::setTestNow(Carbon::parse('first day of March 2000'));
  217. echo $product->getPrice(); // 100
  218. Carbon::setTestNow(Carbon::parse('first day of December 2000'));
  219. echo $product->getPrice(); // 200
  220. Carbon::setTestNow(Carbon::parse('first day of May 2000'));
  221. echo $product->getPrice(); // 100
  222. Carbon::setTestNow();
  223. ```
  224. Relative phrases are also mocked according to the given "now" instance.
  225. ```php
  226. $knownDate = Carbon::create(2001, 5, 21, 12); // create testing date
  227. Carbon::setTestNow($knownDate); // set the mock
  228. echo new Carbon('tomorrow'); // 2001-05-22 00:00:00
  229. echo new Carbon('yesterday'); // 2001-05-20 00:00:00
  230. echo new Carbon('next wednesday'); // 2001-05-23 00:00:00
  231. echo new Carbon('last friday'); // 2001-05-18 00:00:00
  232. echo new Carbon('this thursday'); // 2001-05-24 00:00:00
  233. Carbon::setTestNow(); // always clear it !
  234. ```
  235. The list of words that are considered to be relative modifiers are:
  236. - this
  237. - next
  238. - last
  239. - tomorrow
  240. - yesterday
  241. - +
  242. - -
  243. - first
  244. - last
  245. - ago
  246. Be aware that similar to the next(), previous() and modify() methods some of these relative modifiers will set the time to 00:00:00.
  247. <a name="api-getters"/>
  248. ### Getters
  249. The getters are implemented via PHP's `__get()` method. This enables you to access the value as if it was a property rather than a function call.
  250. ```php
  251. $dt = Carbon::create(2012, 9, 5, 23, 26, 11);
  252. // These getters specifically return integers, ie intval()
  253. var_dump($dt->year); // int(2012)
  254. var_dump($dt->month); // int(9)
  255. var_dump($dt->day); // int(5)
  256. var_dump($dt->hour); // int(23)
  257. var_dump($dt->minute); // int(26)
  258. var_dump($dt->second); // int(11)
  259. var_dump($dt->dayOfWeek); // int(3)
  260. var_dump($dt->dayOfYear); // int(248)
  261. var_dump($dt->weekOfYear); // int(36)
  262. var_dump($dt->daysInMonth); // int(30)
  263. var_dump($dt->timestamp); // int(1346901971)
  264. var_dump(Carbon::createFromDate(1975, 5, 21)->age); // int(38) calculated vs now in the same tz
  265. var_dump($dt->quarter); // int(3)
  266. // Returns an int of seconds difference from UTC (+/- sign included)
  267. var_dump(Carbon::createFromTimestampUTC(0)->offset); // int(0)
  268. var_dump(Carbon::createFromTimestamp(0)->offset); // int(-18000)
  269. // Returns an int of hours difference from UTC (+/- sign included)
  270. var_dump(Carbon::createFromTimestamp(0)->offsetHours); // int(-5)
  271. // Indicates if day light savings time is on
  272. var_dump(Carbon::createFromDate(2012, 1, 1)->dst); // bool(false)
  273. var_dump(Carbon::createFromDate(2012, 9, 1)->dst); // bool(true)
  274. // Indicates if the instance is in the same timezone as the local timzezone
  275. var_dump(Carbon::now()->local); // bool(true)
  276. var_dump(Carbon::now('America/Vancouver')->local); // bool(false)
  277. // Indicates if the instance is in the UTC timezone
  278. var_dump(Carbon::now()->utc); // bool(false)
  279. var_dump(Carbon::now('Europe/London')->utc); // bool(true)
  280. var_dump(Carbon::createFromTimestampUTC(0)->utc); // bool(true)
  281. // Gets the DateTimeZone instance
  282. echo get_class(Carbon::now()->timezone); // DateTimeZone
  283. echo get_class(Carbon::now()->tz); // DateTimeZone
  284. // Gets the DateTimeZone instance name, shortcut for ->timezone->getName()
  285. echo Carbon::now()->timezoneName; // America/Toronto
  286. echo Carbon::now()->tzName; // America/Toronto
  287. ```
  288. <a name="api-setters"/>
  289. ### Setters
  290. The following setters are implemented via PHP's `__set()` method. Its good to take note here that none of the setters, with the obvious exception of explicitly setting the timezone, will change the timezone of the instance. Specifically, setting the timestamp will not set the corresponding timezone to UTC.
  291. ```php
  292. $dt = Carbon::now();
  293. $dt->year = 1975;
  294. $dt->month = 13; // would force year++ and month = 1
  295. $dt->month = 5;
  296. $dt->day = 21;
  297. $dt->hour = 22;
  298. $dt->minute = 32;
  299. $dt->second = 5;
  300. $dt->timestamp = 169957925; // This will not change the timezone
  301. // Set the timezone via DateTimeZone instance or string
  302. $dt->timezone = new DateTimeZone('Europe/London');
  303. $dt->timezone = 'Europe/London';
  304. $dt->tz = 'Europe/London';
  305. ```
  306. <a name="api-settersfluent"/>
  307. ### Fluent Setters
  308. No arguments are optional for the setters, but there are enough variety in the function definitions that you shouldn't need them anyway. Its good to take note here that none of the setters, with the obvious exception of explicitly setting the timezone, will change the timezone of the instance. Specifically, setting the timestamp will not set the corresponding timezone to UTC.
  309. ```php
  310. $dt = Carbon::now();
  311. $dt->year(1975)->month(5)->day(21)->hour(22)->minute(32)->second(5)->toDateTimeString();
  312. $dt->setDate(1975, 5, 21)->setTime(22, 32, 5)->toDateTimeString();
  313. $dt->setDateTime(1975, 5, 21, 22, 32, 5)->toDateTimeString();
  314. $dt->timestamp(169957925)->timezone('Europe/London');
  315. $dt->tz('America/Toronto')->setTimezone('America/Vancouver');
  316. ```
  317. <a name="api-isset"/>
  318. ### IsSet
  319. The PHP function `__isset()` is implemented. This was done as some external systems (ex. [Twig](http://twig.sensiolabs.org/doc/recipes.html#using-dynamic-object-properties)) validate the existence of a property before using it. This is done using the `isset()` or `empty()` method. You can read more about these on the PHP site: [__isset()](http://www.php.net/manual/en/language.oop5.overloading.php#object.isset), [isset()](http://www.php.net/manual/en/function.isset.php), [empty()](http://www.php.net/manual/en/function.empty.php).
  320. ```php
  321. var_dump(isset(Carbon::now()->iDoNotExist)); // bool(false)
  322. var_dump(isset(Carbon::now()->hour)); // bool(true)
  323. var_dump(empty(Carbon::now()->iDoNotExist)); // bool(true)
  324. var_dump(empty(Carbon::now()->year)); // bool(false)
  325. ```
  326. <a name="api-formatting"/>
  327. ### String Formatting and Localization
  328. All of the available `toXXXString()` methods rely on the base class method [DateTime::format()](http://php.net/manual/en/datetime.format.php). You'll notice the `__toString()` method is defined which allows a Carbon instance to be printed as a pretty date time string when used in a string context.
  329. ```php
  330. $dt = Carbon::create(1975, 12, 25, 14, 15, 16);
  331. var_dump($dt->toDateTimeString() == $dt); // bool(true) => uses __toString()
  332. echo $dt->toDateString(); // 1975-12-25
  333. echo $dt->toFormattedDateString(); // Dec 25, 1975
  334. echo $dt->toTimeString(); // 14:15:16
  335. echo $dt->toDateTimeString(); // 1975-12-25 14:15:16
  336. echo $dt->toDayDateTimeString(); // Thu, Dec 25, 1975 2:15 PM
  337. // ... of course format() is still available
  338. echo $dt->format('l jS \\of F Y h:i:s A'); // Thursday 25th of December 1975 02:15:16 PM
  339. ```
  340. You can also set the default __toString() format (which defaults to `Y-m-d H:i:s`) thats used when [type juggling](http://php.net/manual/en/language.types.type-juggling.php) occurs.
  341. ```php
  342. Carbon::setToStringFormat('jS \o\f F, Y g:i:s a');
  343. echo $dt; // 25th of December, 1975 2:15:16 pm
  344. Carbon::resetToStringFormat();
  345. echo $dt; // 1975-12-25 14:15:16
  346. ```
  347. Unfortunately the base class DateTime does not have any localization support. To begin localization support a `formatLocalized($format)` method has been added. The implementation makes a call to [strftime](http://www.php.net/strftime) using the current instance timestamp. If you first set the current locale with [setlocale()](http://www.php.net/setlocale) then the string returned will be formatted in the correct locale.
  348. ```php
  349. setlocale(LC_TIME, 'German');
  350. echo $dt->formatLocalized('%A %d %B %Y'); // Donnerstag 25 Dezember 1975
  351. setlocale(LC_TIME, '');
  352. echo $dt->formatLocalized('%A %d %B %Y'); // Thursday 25 December 1975
  353. ```
  354. <a name="api-commonformats"/>
  355. ## Common Formats
  356. The following are wrappers for the common formats provided in the [DateTime class](http://www.php.net/manual/en/class.datetime.php).
  357. ```php
  358. $dt = Carbon::now();
  359. echo $dt->toATOMString(); // same as $dt->format(DateTime::ATOM);
  360. echo $dt->toCOOKIEString();
  361. echo $dt->toISO8601String();
  362. echo $dt->toRFC822String();
  363. echo $dt->toRFC850String();
  364. echo $dt->toRFC1036String();
  365. echo $dt->toRFC1123String();
  366. echo $dt->toRFC2822String();
  367. echo $dt->toRFC3339String();
  368. echo $dt->toRSSString();
  369. echo $dt->toW3CString();
  370. ```
  371. <a name="api-comparison"/>
  372. ### Comparison
  373. Simple comparison is offered up via the following functions. Remember that the comparison is done in the UTC timezone so things aren't always as they seem.
  374. ```php
  375. echo Carbon::now()->tzName; // America/Toronto
  376. $first = Carbon::create(2012, 9, 5, 23, 26, 11);
  377. $second = Carbon::create(2012, 9, 5, 20, 26, 11, 'America/Vancouver');
  378. echo $first->toDateTimeString(); // 2012-09-05 23:26:11
  379. echo $first->tzName; // America/Toronto
  380. echo $second->toDateTimeString(); // 2012-09-05 20:26:11
  381. echo $second->tzName; // America/Vancouver
  382. var_dump($first->eq($second)); // bool(true)
  383. var_dump($first->ne($second)); // bool(false)
  384. var_dump($first->gt($second)); // bool(false)
  385. var_dump($first->gte($second)); // bool(true)
  386. var_dump($first->lt($second)); // bool(false)
  387. var_dump($first->lte($second)); // bool(true)
  388. $first->setDateTime(2012, 1, 1, 0, 0, 0);
  389. $second->setDateTime(2012, 1, 1, 0, 0, 0); // Remember tz is 'America/Vancouver'
  390. var_dump($first->eq($second)); // bool(false)
  391. var_dump($first->ne($second)); // bool(true)
  392. var_dump($first->gt($second)); // bool(false)
  393. var_dump($first->gte($second)); // bool(false)
  394. var_dump($first->lt($second)); // bool(true)
  395. var_dump($first->lte($second)); // bool(true)
  396. ```
  397. To determine if the current instance is between two other instances you can use the aptly named `between()` method. The third parameter indicates if an equal to comparison should be done. The default is true which determines if its between or equal to the boundaries.
  398. ```php
  399. $first = Carbon::create(2012, 9, 5, 1);
  400. $second = Carbon::create(2012, 9, 5, 5);
  401. var_dump(Carbon::create(2012, 9, 5, 3)->between($first, $second)); // bool(true)
  402. var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second)); // bool(true)
  403. var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second, false)); // bool(false)
  404. ```
  405. Woah! Did you forget min() and max() ? Nope. That is covered as well by the suitably named `min()` and `max()` methods. As usual the default parameter is now if null is specified.
  406. ```php
  407. $dt1 = Carbon::create(2012, 1, 1, 0, 0, 0);
  408. $dt2 = Carbon::create(2014, 1, 30, 0, 0, 0);
  409. echo $dt1->min($dt2); // 2012-01-01 00:00:00
  410. $dt1 = Carbon::create(2012, 1, 1, 0, 0, 0);
  411. $dt2 = Carbon::create(2014, 1, 30, 0, 0, 0);
  412. echo $dt1->max($dt2); // 2014-01-30 00:00:00
  413. // now is the default param
  414. $dt1 = Carbon::create(2000, 1, 1, 0, 0, 0);
  415. echo $dt1->max(); // 2014-01-06 22:52:03
  416. ```
  417. To handle the most used cases there are some simple helper functions that hopefully are obvious from their names. For the methods that compare to `now()` (ex. isToday()) in some manner the `now()` is created in the same timezone as the instance.
  418. ```php
  419. $dt = Carbon::now();
  420. $dt->isWeekday();
  421. $dt->isWeekend();
  422. $dt->isYesterday();
  423. $dt->isToday();
  424. $dt->isTomorrow();
  425. $dt->isFuture();
  426. $dt->isPast();
  427. $dt->isLeapYear();
  428. ```
  429. <a name="api-addsub"/>
  430. ### Addition and Subtraction
  431. The default DateTime provides a couple of different methods for easily adding and subtracting time. There is `modify()`, `add()` and `sub()`. `modify()` takes a *magical* date/time format string, 'last day of next month', that it parses and applies the modification while `add()` and `sub()` use a `DateInterval` class thats not so obvious, `new \DateInterval('P6YT5M')`. Hopefully using these fluent functions will be more clear and easier to read after not seeing your code for a few weeks. But of course I don't make you choose since the base class functions are still available.
  432. ```php
  433. $dt = Carbon::create(2012, 1, 31, 0);
  434. echo $dt->toDateTimeString(); // 2012-01-31 00:00:00
  435. echo $dt->addYears(5); // 2017-01-31 00:00:00
  436. echo $dt->addYear(); // 2018-01-31 00:00:00
  437. echo $dt->subYear(); // 2017-01-31 00:00:00
  438. echo $dt->subYears(5); // 2012-01-31 00:00:00
  439. echo $dt->addMonths(60); // 2017-01-31 00:00:00
  440. echo $dt->addMonth(); // 2017-03-03 00:00:00 equivalent of $dt->month($dt->month + 1); so it wraps
  441. echo $dt->subMonth(); // 2017-02-03 00:00:00
  442. echo $dt->subMonths(60); // 2012-02-03 00:00:00
  443. echo $dt->addDays(29); // 2012-03-03 00:00:00
  444. echo $dt->addDay(); // 2012-03-04 00:00:00
  445. echo $dt->subDay(); // 2012-03-03 00:00:00
  446. echo $dt->subDays(29); // 2012-02-03 00:00:00
  447. echo $dt->addWeekdays(4); // 2012-02-09 00:00:00
  448. echo $dt->addWeekday(); // 2012-02-10 00:00:00
  449. echo $dt->subWeekday(); // 2012-02-09 00:00:00
  450. echo $dt->subWeekdays(4); // 2012-02-03 00:00:00
  451. echo $dt->addWeeks(3); // 2012-02-24 00:00:00
  452. echo $dt->addWeek(); // 2012-03-02 00:00:00
  453. echo $dt->subWeek(); // 2012-02-24 00:00:00
  454. echo $dt->subWeeks(3); // 2012-02-03 00:00:00
  455. echo $dt->addHours(24); // 2012-02-04 00:00:00
  456. echo $dt->addHour(); // 2012-02-04 01:00:00
  457. echo $dt->subHour(); // 2012-02-04 00:00:00
  458. echo $dt->subHours(24); // 2012-02-03 00:00:00
  459. echo $dt->addMinutes(61); // 2012-02-03 01:01:00
  460. echo $dt->addMinute(); // 2012-02-03 01:02:00
  461. echo $dt->subMinute(); // 2012-02-03 01:01:00
  462. echo $dt->subMinutes(61); // 2012-02-03 00:00:00
  463. echo $dt->addSeconds(61); // 2012-02-03 00:01:01
  464. echo $dt->addSecond(); // 2012-02-03 00:01:02
  465. echo $dt->subSecond(); // 2012-02-03 00:01:01
  466. echo $dt->subSeconds(61); // 2012-02-03 00:00:00
  467. ```
  468. For fun you can also pass negative values to `addXXX()`, in fact that's how `subXXX()` is implemented.
  469. <a name="api-difference"/>
  470. ### Difference
  471. These functions always return the **total difference** expressed in the specified time requested. This differs from the base class `diff()` function where an interval of 61 seconds would be returned as 1 minute and 1 second via a `DateInterval` instance. The `diffInMinutes()` function would simply return 1. All values are truncated and not rounded. Each function below has a default first parameter which is the Carbon instance to compare to, or null if you want to use `now()`. The 2nd parameter again is optional and indicates if you want the return value to be the absolute value or a relative value that might have a `-` (negative) sign if the passed in date is less than the current instance. This will default to true, return the absolute value. The comparisons are done in UTC.
  472. ```php
  473. // Carbon::diffInYears(Carbon $dt = null, $abs = true)
  474. echo Carbon::now('America/Vancouver')->diffInSeconds(Carbon::now('Europe/London')); // 0
  475. $dtOttawa = Carbon::createFromDate(2000, 1, 1, 'America/Toronto');
  476. $dtVancouver = Carbon::createFromDate(2000, 1, 1, 'America/Vancouver');
  477. echo $dtOttawa->diffInHours($dtVancouver); // 3
  478. echo $dtOttawa->diffInHours($dtVancouver, false); // 3
  479. echo $dtVancouver->diffInHours($dtOttawa, false); // -3
  480. $dt = Carbon::create(2012, 1, 31, 0);
  481. echo $dt->diffInDays($dt->copy()->addMonth()); // 31
  482. echo $dt->diffInDays($dt->copy()->subMonth(), false); // -31
  483. $dt = Carbon::create(2012, 4, 30, 0);
  484. echo $dt->diffInDays($dt->copy()->addMonth()); // 30
  485. echo $dt->diffInDays($dt->copy()->addWeek()); // 7
  486. $dt = Carbon::create(2012, 1, 1, 0);
  487. echo $dt->diffInMinutes($dt->copy()->addSeconds(59)); // 0
  488. echo $dt->diffInMinutes($dt->copy()->addSeconds(60)); // 1
  489. echo $dt->diffInMinutes($dt->copy()->addSeconds(119)); // 1
  490. echo $dt->diffInMinutes($dt->copy()->addSeconds(120)); // 2
  491. // others that are defined
  492. // diffInYears(), diffInMonths(), diffInDays()
  493. // diffInHours(), diffInMinutes(), diffInSeconds()
  494. ```
  495. ```php
  496. // Carbon::average(Carbon $dt = null)
  497. ```
  498. <a name="api-humandiff"/>
  499. ### Difference for Humans
  500. It is easier for humans to read `1 month ago` compared to 30 days ago. This is a common function seen in most date libraries so I thought I would add it here as well. It uses approximations for a month being 4 weeks. The lone argument for the function is the other Carbon instance to diff against, and of course it defaults to `now()` if not specified.
  501. This method will add a phrase after the difference value relative to the instance and the passed in instance. There are 4 possibilities:
  502. * When comparing a value in the past to default now:
  503. * 1 hour ago
  504. * 5 months ago
  505. * When comparing a value in the future to default now:
  506. * 1 hour from now
  507. * 5 months from now
  508. * When comparing a value in the past to another value:
  509. * 1 hour before
  510. * 5 months before
  511. * When comparing a value in the future to another value:
  512. * 1 hour after
  513. * 5 months after
  514. ```php
  515. // The most typical usage is for comments
  516. // The instance is the date the comment was created and its being compared to default now()
  517. echo Carbon::now()->subDays(5)->diffForHumans(); // 5 days ago
  518. echo Carbon::now()->diffForHumans(Carbon::now()->subYear()); // 1 year after
  519. $dt = Carbon::createFromDate(2011, 2, 1);
  520. echo $dt->diffForHumans($dt->copy()->addMonth()); // 1 month before
  521. echo $dt->diffForHumans($dt->copy()->subMonth()); // 1 month after
  522. echo Carbon::now()->addSeconds(5)->diffForHumans(); // 5 seconds from now
  523. echo Carbon::now()->subDays(24)->diffForHumans(); // 3 weeks ago
  524. ```
  525. <a name="api-modifiers"/>
  526. ### Modifiers
  527. These group of methods perform helpful modifications to the current instance. Most of them are self explanatory from their names... or at least should be. You'll also notice that the startOfXXX(), next() and previous() methods set the time to 00:00:00 and the endOfXXX() methods set the time to 23:59:59.
  528. The only one slightly different is the `average()` function. It moves your instance to the middle date between itself and the provided Carbon argument.
  529. ```php
  530. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  531. echo $dt->startOfDay(); // 2012-01-31 00:00:00
  532. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  533. echo $dt->endOfDay(); // 2012-01-31 23:59:59
  534. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  535. echo $dt->startOfMonth(); // 2012-01-01 00:00:00
  536. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  537. echo $dt->endOfMonth(); // 2012-01-31 23:59:59
  538. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  539. echo $dt->startOfYear(); // 2012-01-01 00:00:00
  540. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  541. echo $dt->endOfYear(); // 2012-12-31 23:59:59
  542. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  543. echo $dt->startOfDecade(); // 2010-01-01 00:00:00
  544. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  545. echo $dt->endOfDecade(); // 2019-12-31 23:59:59
  546. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  547. echo $dt->startOfCentury(); // 2000-01-01 00:00:00
  548. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  549. echo $dt->endOfCentury(); // 2099-12-31 23:59:59
  550. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  551. echo $dt->startOfWeek(); // 2012-01-30 00:00:00
  552. var_dump($dt->dayOfWeek == Carbon::MONDAY); // bool(true) : ISO8601 week starts on Monday
  553. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  554. echo $dt->endOfWeek(); // 2012-02-05 23:59:59
  555. var_dump($dt->dayOfWeek == Carbon::SUNDAY); // bool(true) : ISO8601 week ends on Sunday
  556. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  557. echo $dt->next(Carbon::WEDNESDAY); // 2012-02-01 00:00:00
  558. var_dump($dt->dayOfWeek == Carbon::WEDNESDAY); // bool(true)
  559. $dt = Carbon::create(2012, 1, 1, 12, 0, 0);
  560. echo $dt->next(); // 2012-01-08 00:00:00
  561. $dt = Carbon::create(2012, 1, 31, 12, 0, 0);
  562. echo $dt->previous(Carbon::WEDNESDAY); // 2012-01-25 00:00:00
  563. var_dump($dt->dayOfWeek == Carbon::WEDNESDAY); // bool(true)
  564. $dt = Carbon::create(2012, 1, 1, 12, 0, 0);
  565. echo $dt->previous(); // 2011-12-25 00:00:00
  566. $start = Carbon::create(2014, 1, 1, 0, 0, 0);
  567. $end = Carbon::create(2014, 1, 30, 0, 0, 0);
  568. echo $start->average($end); // 2014-01-15 12:00:00
  569. // others that are defined that are similar
  570. // firstOfMonth(), lastOfMonth(), nthOfMonth()
  571. // firstOfQuarter(), lastOfQuarter(), nthOfQuarter()
  572. // firstOfYear(), lastOfYear(), nthOfYear()
  573. ```
  574. <a name="api-constants"/>
  575. ### Constants
  576. The following constants are defined in the Carbon class.
  577. * SUNDAY = 0
  578. * MONDAY = 1
  579. * TUESDAY = 2
  580. * WEDNESDAY = 3
  581. * THURSDAY = 4
  582. * FRIDAY = 5
  583. * SATURDAY = 6
  584. * MONTHS_PER_YEAR = 12
  585. * HOURS_PER_DAY = 24
  586. * MINUTES_PER_HOUR = 60
  587. * SECONDS_PER_MINUTE = 60
  588. ```php
  589. $dt = Carbon::createFromDate(2012, 10, 6);
  590. if ($dt->dayOfWeek === Carbon::SATURDAY) {
  591. echo 'Place bets on Ottawa Senators Winning!';
  592. }
  593. ```
  594. <a name="about"/>
  595. ## About
  596. <a name="about-contributing"/>
  597. ### Contributing
  598. I hate reading a readme.md file that has code errors and/or sample output that is incorrect. I tried something new with this project and wrote a quick readme parser that can **lint** sample source code or **execute** and inject the actual result into a generated readme.
  599. > **Don't make changes to the `readme.md` directly!!**
  600. Change the `readme.src.md` and then use the `readme.php` to generate the new `readme.md` file. It can be run at the command line using `php readme.php` from the project root. Maybe someday I'll extract this out to another project or at least run it with a post receive hook, but for now its just a local tool, deal with it.
  601. The commands are quickly explained below. To see some examples you can view the raw `readme.src.md` file in this repo.
  602. `{{::lint()}}`
  603. The `lint` command is meant for confirming the code is valid and will `eval()` the code passed into the function. Assuming there were no errors, the executed source code will then be injected back into the text replacing out the `{{::lint()}}`. When you look at the raw `readme.src.md` you will see that the code can span several lines. Remember the code is executed in the context of the running script so any variables will be available for the rest of the file.
  604. {{::lint($var = 'brian nesbitt';)}} => $var = 'brian nesbitt';
  605. > As mentioned the `$var` can later be echo'd and you would get 'brian nesbitt' as all of the source is executed in the same scope.
  606. `{{varName::exec()}}` and `{{varName_eval}}`
  607. The `exec` command begins by performing an `eval()` on the code passed into the function. The executed source code will then be injected back into the text replacing out the `{{varName::exec()}}`. This will also create a variable named `varName_eval` that you can then place anywhere in the file and it will get replaced with the output of the `eval()`. You can use any type of output (`echo`, `printf`, `var_dump` etc) statement to return the result value as an output buffer is setup to capture the output.
  608. {{exVarName::exec(echo $var;)}} => echo $var;
  609. {{exVarName_eval}} => brian nesbitt // $var is still set from above
  610. `/*pad()*/`
  611. The `pad()` is a special source modifier. This will pad the code block to the indicated number of characters using spaces. Its particularly handy for aligning `//` comments when showing results.
  612. {{exVarName1::exec(echo 12345;/*pad(20)*/)}} // {{exVarName1_eval}}
  613. {{exVarName2::exec(echo 6;/*pad(20)*/)}} // {{exVarName2_eval}}
  614. ... would generate to:
  615. echo 12345; // 12345
  616. echo 6; // 6
  617. Apart from the readme the typical steps can be used to contribute your own improvements.
  618. * Fork
  619. * Clone
  620. * PHPUnit
  621. * Branch
  622. * PHPUnit
  623. * Code
  624. * PHPUnit
  625. * Commit
  626. * Push
  627. * Pull request
  628. * Relax and play Castle Crashers
  629. <a name="about-author"/>
  630. ### Author
  631. Brian Nesbitt - <brian@nesbot.com> - <http://twitter.com/NesbittBrian>
  632. <a name="about-license"/>
  633. ### License
  634. Carbon is licensed under the MIT License - see the `LICENSE` file for details
  635. <a name="about-history"/>
  636. ### History
  637. You can view the history of the Carbon project in the [history file](https://github.com/briannesbitt/Carbon/blob/master/history.md).
  638. <a name="about-whyname"/>
  639. ### Why the name Carbon?
  640. Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)
  641. ![](https://cruel-carlota.pagodabox.com/55ce479cc1edc5e0cc5b4b6f9a7a9200)