CarbonCarbonInterval

A simple API extension for DateInterval.

Defined (1)

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

/vendor/nesbot/carbon/src/Carbon/CarbonInterval.php  
  1. class CarbonInterval extends DateInterval 
  2. /** 
  3. * Interval spec period designators 
  4. */ 
  5. const PERIOD_PREFIX = 'P'; 
  6. const PERIOD_YEARS = 'Y'; 
  7. const PERIOD_MONTHS = 'M'; 
  8. const PERIOD_DAYS = 'D'; 
  9. const PERIOD_TIME_PREFIX = 'T'; 
  10. const PERIOD_HOURS = 'H'; 
  11. const PERIOD_MINUTES = 'M'; 
  12. const PERIOD_SECONDS = 'S'; 
  13.  
  14. /** 
  15. * A translator to ... er ... translate stuff 
  16. * @var TranslatorInterface 
  17. */ 
  18. protected static $translator; 
  19.  
  20. /** 
  21. * Before PHP 5.4.20/5.5.4 instead of FALSE days will be set to -99999 when the interval instance 
  22. * was created by DateTime:diff(). 
  23. */ 
  24. const PHP_DAYS_FALSE = -99999; 
  25.  
  26. /** 
  27. * Determine if the interval was created via DateTime:diff() or not. 
  28. * @param DateInterval $interval 
  29. * @return bool 
  30. */ 
  31. private static function wasCreatedFromDiff(DateInterval $interval) 
  32. return $interval->days !== false && $interval->days !== static::PHP_DAYS_FALSE; 
  33.  
  34. /////////////////////////////////////////////////////////////////// 
  35. //////////////////////////// CONSTRUCTORS ///////////////////////// 
  36. /////////////////////////////////////////////////////////////////// 
  37.  
  38. /** 
  39. * Create a new CarbonInterval instance. 
  40. * @param int $years 
  41. * @param int $months 
  42. * @param int $weeks 
  43. * @param int $days 
  44. * @param int $hours 
  45. * @param int $minutes 
  46. * @param int $seconds 
  47. */ 
  48. public function __construct($years = 1, $months = null, $weeks = null, $days = null, $hours = null, $minutes = null, $seconds = null) 
  49. $spec = static::PERIOD_PREFIX; 
  50.  
  51. $spec .= $years > 0 ? $years.static::PERIOD_YEARS : ''; 
  52. $spec .= $months > 0 ? $months.static::PERIOD_MONTHS : ''; 
  53.  
  54. $specDays = 0; 
  55. $specDays += $weeks > 0 ? $weeks * Carbon::DAYS_PER_WEEK : 0; 
  56. $specDays += $days > 0 ? $days : 0; 
  57.  
  58. $spec .= $specDays > 0 ? $specDays.static::PERIOD_DAYS : ''; 
  59.  
  60. if ($hours > 0 || $minutes > 0 || $seconds > 0) { 
  61. $spec .= static::PERIOD_TIME_PREFIX; 
  62. $spec .= $hours > 0 ? $hours.static::PERIOD_HOURS : ''; 
  63. $spec .= $minutes > 0 ? $minutes.static::PERIOD_MINUTES : ''; 
  64. $spec .= $seconds > 0 ? $seconds.static::PERIOD_SECONDS : ''; 
  65.  
  66. if ($spec === static::PERIOD_PREFIX) { 
  67. // Allow the zero interval. 
  68. $spec .= '0'.static::PERIOD_YEARS; 
  69.  
  70. parent::__construct($spec); 
  71.  
  72. /** 
  73. * Create a new CarbonInterval instance from specific values. 
  74. * This is an alias for the constructor that allows better fluent 
  75. * syntax as it allows you to do CarbonInterval::create(1)->fn() rather than 
  76. * (new CarbonInterval(1))->fn(). 
  77. * @param int $years 
  78. * @param int $months 
  79. * @param int $weeks 
  80. * @param int $days 
  81. * @param int $hours 
  82. * @param int $minutes 
  83. * @param int $seconds 
  84. * @return static 
  85. */ 
  86. public static function create($years = 1, $months = null, $weeks = null, $days = null, $hours = null, $minutes = null, $seconds = null) 
  87. return new static($years, $months, $weeks, $days, $hours, $minutes, $seconds); 
  88.  
  89. /** 
  90. * Provide static helpers to create instances. Allows CarbonInterval::years(3). 
  91. * Note: This is done using the magic method to allow static and instance methods to 
  92. * have the same names. 
  93. * @param string $name 
  94. * @param array $args 
  95. * @return static 
  96. */ 
  97. public static function __callStatic($name, $args) 
  98. $arg = count($args) === 0 ? 1 : $args[0]; 
  99.  
  100. switch ($name) { 
  101. case 'years': 
  102. case 'year': 
  103. return new static($arg); 
  104.  
  105. case 'months': 
  106. case 'month': 
  107. return new static(null, $arg); 
  108.  
  109. case 'weeks': 
  110. case 'week': 
  111. return new static(null, null, $arg); 
  112.  
  113. case 'days': 
  114. case 'dayz': 
  115. case 'day': 
  116. return new static(null, null, null, $arg); 
  117.  
  118. case 'hours': 
  119. case 'hour': 
  120. return new static(null, null, null, null, $arg); 
  121.  
  122. case 'minutes': 
  123. case 'minute': 
  124. return new static(null, null, null, null, null, $arg); 
  125.  
  126. case 'seconds': 
  127. case 'second': 
  128. return new static(null, null, null, null, null, null, $arg); 
  129.  
  130. /** 
  131. * Create a CarbonInterval instance from a DateInterval one. Can not instance 
  132. * DateInterval objects created from DateTime::diff() as you can't externally 
  133. * set the $days field. 
  134. * @param DateInterval $di 
  135. * @throws InvalidArgumentException 
  136. * @return static 
  137. */ 
  138. public static function instance(DateInterval $di) 
  139. if (static::wasCreatedFromDiff($di)) { 
  140. throw new InvalidArgumentException("Can not instance a DateInterval object created from DateTime::diff()."); 
  141.  
  142. $instance = new static($di->y, $di->m, 0, $di->d, $di->h, $di->i, $di->s); 
  143. $instance->invert = $di->invert; 
  144. $instance->days = $di->days; 
  145.  
  146. return $instance; 
  147.  
  148. /////////////////////////////////////////////////////////////////// 
  149. /////////////////////// LOCALIZATION ////////////////////////////// 
  150. /////////////////////////////////////////////////////////////////// 
  151.  
  152. /** 
  153. * Intialize the translator instance if necessary. 
  154. * @return TranslatorInterface 
  155. */ 
  156. protected static function translator() 
  157. if (static::$translator === null) { 
  158. static::$translator = new Translator('en'); 
  159. static::$translator->addLoader('array', new ArrayLoader()); 
  160. static::setLocale('en'); 
  161.  
  162. return static::$translator; 
  163.  
  164. /** 
  165. * Get the translator instance in use 
  166. * @return TranslatorInterface 
  167. */ 
  168. public static function getTranslator() 
  169. return static::translator(); 
  170.  
  171. /** 
  172. * Set the translator instance to use 
  173. * @param TranslatorInterface $translator 
  174. */ 
  175. public static function setTranslator(TranslatorInterface $translator) 
  176. static::$translator = $translator; 
  177.  
  178. /** 
  179. * Get the current translator locale 
  180. * @return string 
  181. */ 
  182. public static function getLocale() 
  183. return static::translator()->getLocale(); 
  184.  
  185. /** 
  186. * Set the current translator locale 
  187. * @param string $locale 
  188. */ 
  189. public static function setLocale($locale) 
  190. static::translator()->setLocale($locale); 
  191.  
  192. // Ensure the locale has been loaded. 
  193. static::translator()->addResource('array', require __DIR__.'/Lang/'.$locale.'.php', $locale); 
  194.  
  195. /////////////////////////////////////////////////////////////////// 
  196. ///////////////////////// GETTERS AND SETTERS ///////////////////// 
  197. /////////////////////////////////////////////////////////////////// 
  198.  
  199. /** 
  200. * Get a part of the CarbonInterval object 
  201. * @param string $name 
  202. * @throws InvalidArgumentException 
  203. * @return int 
  204. */ 
  205. public function __get($name) 
  206. switch ($name) { 
  207. case 'years': 
  208. return $this->y; 
  209.  
  210. case 'months': 
  211. return $this->m; 
  212.  
  213. case 'dayz': 
  214. return $this->d; 
  215.  
  216. case 'hours': 
  217. return $this->h; 
  218.  
  219. case 'minutes': 
  220. return $this->i; 
  221.  
  222. case 'seconds': 
  223. return $this->s; 
  224.  
  225. case 'weeks': 
  226. return (int)floor($this->d / Carbon::DAYS_PER_WEEK); 
  227.  
  228. case 'daysExcludeWeeks': 
  229. case 'dayzExcludeWeeks': 
  230. return $this->d % Carbon::DAYS_PER_WEEK; 
  231.  
  232. default: 
  233. throw new InvalidArgumentException(sprintf("Unknown getter '%s'", $name)); 
  234.  
  235. /** 
  236. * Set a part of the CarbonInterval object 
  237. * @param string $name 
  238. * @param int $val 
  239. * @throws InvalidArgumentException 
  240. */ 
  241. public function __set($name, $val) 
  242. switch ($name) { 
  243. case 'years': 
  244. $this->y = $val; 
  245. break; 
  246.  
  247. case 'months': 
  248. $this->m = $val; 
  249. break; 
  250.  
  251. case 'weeks': 
  252. $this->d = $val * Carbon::DAYS_PER_WEEK; 
  253. break; 
  254.  
  255. case 'dayz': 
  256. $this->d = $val; 
  257. break; 
  258.  
  259. case 'hours': 
  260. $this->h = $val; 
  261. break; 
  262.  
  263. case 'minutes': 
  264. $this->i = $val; 
  265. break; 
  266.  
  267. case 'seconds': 
  268. $this->s = $val; 
  269. break; 
  270.  
  271. /** 
  272. * Allow setting of weeks and days to be cumulative. 
  273. * @param int $weeks Number of weeks to set 
  274. * @param int $days Number of days to set 
  275. * @return static 
  276. */ 
  277. public function weeksAndDays($weeks, $days) 
  278. $this->dayz = ($weeks * Carbon::DAYS_PER_WEEK) + $days; 
  279.  
  280. return $this; 
  281.  
  282. /** 
  283. * Allow fluent calls on the setters... CarbonInterval::years(3)->months(5)->day(). 
  284. * Note: This is done using the magic method to allow static and instance methods to 
  285. * have the same names. 
  286. * @param string $name 
  287. * @param array $args 
  288. * @return static 
  289. */ 
  290. public function __call($name, $args) 
  291. $arg = count($args) === 0 ? 1 : $args[0]; 
  292.  
  293. switch ($name) { 
  294. case 'years': 
  295. case 'year': 
  296. $this->years = $arg; 
  297. break; 
  298.  
  299. case 'months': 
  300. case 'month': 
  301. $this->months = $arg; 
  302. break; 
  303.  
  304. case 'weeks': 
  305. case 'week': 
  306. $this->dayz = $arg * Carbon::DAYS_PER_WEEK; 
  307. break; 
  308.  
  309. case 'days': 
  310. case 'dayz': 
  311. case 'day': 
  312. $this->dayz = $arg; 
  313. break; 
  314.  
  315. case 'hours': 
  316. case 'hour': 
  317. $this->hours = $arg; 
  318. break; 
  319.  
  320. case 'minutes': 
  321. case 'minute': 
  322. $this->minutes = $arg; 
  323. break; 
  324.  
  325. case 'seconds': 
  326. case 'second': 
  327. $this->seconds = $arg; 
  328. break; 
  329.  
  330. return $this; 
  331.  
  332. /** 
  333. * Get the current interval in a human readable format in the current locale. 
  334. * @return string 
  335. */ 
  336. public function forHumans() 
  337. $periods = array( 
  338. 'year' => $this->years,  
  339. 'month' => $this->months,  
  340. 'week' => $this->weeks,  
  341. 'day' => $this->daysExcludeWeeks,  
  342. 'hour' => $this->hours,  
  343. 'minute' => $this->minutes,  
  344. 'second' => $this->seconds,  
  345. ); 
  346.  
  347. $parts = array(); 
  348. foreach ($periods as $unit => $count) { 
  349. if ($count > 0) { 
  350. array_push($parts, static::translator()->transChoice($unit, $count, array(':count' => $count))); 
  351.  
  352. return implode(' ', $parts); 
  353.  
  354. /** 
  355. * Format the instance as a string using the forHumans() function. 
  356. * @return string 
  357. */ 
  358. public function __toString() 
  359. return $this->forHumans(); 
  360.  
  361. /** 
  362. * Add the passed interval to the current instance 
  363. * @param DateInterval $interval 
  364. * @return static 
  365. */ 
  366. public function add(DateInterval $interval) 
  367. $sign = $interval->invert === 1 ? -1 : 1; 
  368.  
  369. if (static::wasCreatedFromDiff($interval)) { 
  370. $this->dayz = $this->dayz + $interval->days * $sign; 
  371. } else { 
  372. $this->years = $this->years + $interval->y * $sign; 
  373. $this->months = $this->months + $interval->m * $sign; 
  374. $this->dayz = $this->dayz + $interval->d * $sign; 
  375. $this->hours = $this->hours + $interval->h * $sign; 
  376. $this->minutes = $this->minutes + $interval->i * $sign; 
  377. $this->seconds = $this->seconds + $interval->s * $sign; 
  378.  
  379. return $this;