Skip to content

Commit

Permalink
Merge pull request #1385 from kylekatarnls/version-2.0
Browse files Browse the repository at this point in the history 
- Add $weekStartsAt/$weekEndsAt optional arguments for week methods
- Deprecate many static setters
- Fix #1386 weekNumberInMonth for months starting a sunday
- Implement methods from, fromNow, to, toNow
  • Loading branch information
@kylekatarnls
kylekatarnls committed Jul 12, 2018
2 parents 5840ae7 + 647c567 commit 8140df7
Show file tree
Hide file tree
Showing 6 changed files with 257 additions and 20 deletions.
110 changes: 91 additions & 19 deletions src/Carbon/Traits/Date.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -777,6 +777,10 @@ public static function isStrictModeEnabled()
}

/**
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* You should rather use method variants: addMonthsWithOverflow/addMonthsNoOverflow, same variants
* are available for quarters, years, decade, centuries, millennia (singular and plural forms).
*
* Indicates if months should be calculated with overflow.
*
* @param bool $monthsOverflow
Expand Down Expand Up @@ -809,6 +813,10 @@ public static function shouldOverflowMonths()
}

/**
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* You should rather use method variants: addMonthsWithOverflow/addMonthsNoOverflow, same variants
* are available for quarters, years, decade, centuries, millennia (singular and plural forms).
*
* Indicates if years should be calculated with overflow.
*
* @param bool $yearsOverflow
Expand Down Expand Up @@ -1549,7 +1557,7 @@ public function get($name)

// @property-read int 1 through 5
case $name === 'weekNumberInMonth':
return (int) ceil(($this->day + $this->copy()->startOfMonth()->dayOfWeek - 1) / static::DAYS_PER_WEEK);
return (int) ceil(($this->day + $this->copy()->startOfMonth()->dayOfWeekIso - 1) / static::DAYS_PER_WEEK);

// @property int does a diffInYears() with default parameters
case $name === 'age':
Expand Down Expand Up @@ -1928,6 +1936,9 @@ public static function getWeekStartsAt()
}

/**
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* Use $weekEndsAt optional parameter instead when using endOfWeek method
*
* Set the first day of week
*
* @param int $day week start day
Expand All @@ -1950,6 +1961,10 @@ public static function getWeekEndsAt()
}

/**
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* Use $weekStartsAt optional parameter instead when using startOfWeek, floorWeek, ceilWeek
* or roundWeek method
*
* Set the last day of week
*
* @param int $day
Expand All @@ -1972,6 +1987,26 @@ public static function getWeekendDays()
}

/**
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* You should rather consider week-end is always saturday and sunday, and if you have some custom
* week-end days to handle, give to those days an other name and create a macro for them:
*
* ```
* Carbon::macro('isDayOff', function ($date) {
* return $date->isSunday() || $date->isMonday();
* });
* Carbon::macro('isNotDayOff', function ($date) {
* return !$date->isDayOff();
* });
* if ($someDate->isDayOff()) ...
* if ($someDate->isNotDayOff()) ...
* // Add 5 not-off days
* $count = 5;
* while ($someDate->isDayOff() || ($count-- > 0)) {
* $someDate->addDay();
* }
* ```
*
* Set weekend days
*
* @param array $days
Expand All @@ -1994,6 +2029,13 @@ public static function getMidDayAt()
}

/**
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* You should rather consider mid-day is always 12pm, then if you need to test if it's an other
* hour, test it explicitly:
* $date->format('G') == 13
* or to set explicitly to a given hour:
* $date->setTime(13, 0, 0, 0)
*
* Set midday/noon hour
*
* @param int $hour midday hour
Expand Down Expand Up @@ -2045,7 +2087,7 @@ protected static function translator()
}

/**
* Get the translator instance in use
* Get the translator instance in use.
*
* @return \Symfony\Component\Translation\TranslatorInterface
*/
Expand All @@ -2055,7 +2097,7 @@ public static function getTranslator()
}

/**
* Set the translator instance to use
* Set the translator instance to use.
*
* @param \Symfony\Component\Translation\TranslatorInterface $translator
*
Expand All @@ -2067,7 +2109,7 @@ public static function setTranslator(TranslatorInterface $translator)
}

/**
* Get the current translator locale
* Get the current translator locale.
*
* @return string
*/
Expand Down Expand Up @@ -2271,7 +2313,10 @@ public static function getAvailableLocales()
///////////////////////////////////////////////////////////////////

/**
* Set if UTF8 will be used for localized date/time
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* You should rather use UTF-8 language packages on every machine.
*
* Set if UTF8 will be used for localized date/time.
*
* @param bool $utf8
*/
Expand Down Expand Up @@ -2311,6 +2356,11 @@ public static function resetToStringFormat()
}

/**
* @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
* You should rather let Carbon object being casted to string with DEFAULT_TO_STRING_FORMAT, and
* use other method or custom format passed to format() method if you need to dump an other string
* format.
*
* Set the default format used when type juggling a Carbon instance to a string
*
* @param string $format
Expand Down Expand Up @@ -3585,31 +3635,49 @@ public function ceil($precision = 1)
/**
* Round the current instance week.
*
* @param int $weekStartsAt optional start allow you to specify the day of week to use to start the week
*
* @return CarbonInterface
*/
public function roundWeek()
public function roundWeek($weekStartsAt = null)
{
return $this->closest($this->copy()->floorWeek(), $this->copy()->ceilWeek());
return $this->closest($this->copy()->floorWeek($weekStartsAt), $this->copy()->ceilWeek($weekStartsAt));
}

/**
* Truncate the current instance week.
*
* @param int $weekStartsAt optional start allow you to specify the day of week to use to start the week
*
* @return CarbonInterface
*/
public function floorWeek()
public function floorWeek($weekStartsAt = null)
{
return $this->startOfWeek();
return $this->startOfWeek($weekStartsAt);
}

/**
* Ceil the current instance week.
*
* @param int $weekStartsAt optional start allow you to specify the day of week to use to start the week
*
* @return CarbonInterface
*/
public function ceilWeek()
public function ceilWeek($weekStartsAt = null)
{
return $this->endOfWeek()->roundDay();
if ($this->isMutable()) {
$startOfWeek = $this->copy()->startOfWeek($weekStartsAt);

return $startOfWeek != $this ?
$this->startOfWeek($weekStartsAt)->addWeek() :
$this;
}

$startOfWeek = $this->startOfWeek($weekStartsAt);

return $startOfWeek != $this ?
$startOfWeek->addWeek() :
$this->copy();
}

///////////////////////////////////////////////////////////////////
Expand Down Expand Up @@ -3751,12 +3819,14 @@ public function endOfCentury()
/**
* Resets the date to the first day of week (defined in $weekStartsAt) and the time to 00:00:00
*
* @param int $weekStartsAt optional start allow you to specify the day of week to use to start the week
*
* @return static
*/
public function startOfWeek()
public function startOfWeek($weekStartsAt = null)
{
$date = $this;
while ($date->dayOfWeek !== static::$weekStartsAt) {
while ($date->dayOfWeek !== ($weekStartsAt ?? static::$weekStartsAt)) {
$date = $date->subDay();
}

Expand All @@ -3766,12 +3836,14 @@ public function startOfWeek()
/**
* Resets the date to end of week (defined in $weekEndsAt) and time to 23:59:59
*
* @param int $weekEndsAt optional start allow you to specify the day of week to use to end the week
*
* @return static
*/
public function endOfWeek()
public function endOfWeek($weekEndsAt = null)
{
$date = $this;
while ($date->dayOfWeek !== static::$weekEndsAt) {
while ($date->dayOfWeek !== ($weekEndsAt ?? static::$weekEndsAt)) {
$date = $date->addDay();
}

Expand Down Expand Up @@ -3845,15 +3917,15 @@ public function endOfSecond()
*
* @return static
*/
public function startOf($unit)
public function startOf($unit, ...$params)
{
$ucfUnit = ucfirst(static::singularUnit($unit));
$method = "startOf$ucfUnit";
if (!method_exists($this, $method)) {
throw new InvalidArgumentException("Unknown unit '$unit'");
}

return $this->$method();
return $this->$method(...$params);
}

/**
Expand All @@ -3863,15 +3935,15 @@ public function startOf($unit)
*
* @return static
*/
public function endOf($unit)
public function endOf($unit, ...$params)
{
$ucfUnit = ucfirst(static::singularUnit($unit));
$method = "endOf$ucfUnit";
if (!method_exists($this, $method)) {
throw new InvalidArgumentException("Unknown unit '$unit'");
}

return $this->$method();
return $this->$method(...$params);
}

/**
Expand Down
98 changes: 97 additions & 1 deletion src/Carbon/Traits/Difference.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -292,7 +292,8 @@ public function secondsUntilEndOfDay()
}

/**
* Get the difference in a human readable format in the current locale.
* Get the difference in a human readable format in the current locale from current instance to an other
* instance given (or now if null given).
*
* When comparing a value in the past to default now:
* 1 hour ago
Expand Down Expand Up @@ -434,4 +435,99 @@ public function diffForHumans($other = null, $syntax = null, $short = false, $pa

return static::translator()->trans($transId, [':time' => $time]);
}

/**
* @alias diffForHumans
*
* Get the difference in a human readable format in the current locale from current instance to an other
* instance given (or now if null given).
*/
public function from($other = null, $syntax = null, $short = false, $parts = 1)
{
return $this->diffForHumans($other, $syntax, $short, $parts);
}

/**
* Get the difference in a human readable format in the current locale from an other
* instance given (or now if null given) to current instance.
*
* When comparing a value in the past to default now:
* 1 hour from now
* 5 months from now
*
* When comparing a value in the future to default now:
* 1 hour ago
* 5 months ago
*
* When comparing a value in the past to another value:
* 1 hour after
* 5 months after
*
* When comparing a value in the future to another value:
* 1 hour before
* 5 months before
*
* @param Carbon|null $other
* @param int $syntax difference modifiers (ago, after, etc) rules
* Possible values:
* - CarbonInterface::DIFF_ABSOLUTE
* - CarbonInterface::DIFF_RELATIVE_AUTO
* - CarbonInterface::DIFF_RELATIVE_TO_NOW
* - CarbonInterface::DIFF_RELATIVE_TO_OTHER
* Default value: CarbonInterface::DIFF_RELATIVE_AUTO
* @param bool $short displays short format of time units
* @param int $parts displays number of parts in the interval
*
* @return string
*/
public function to($other = null, $syntax = null, $short = false, $parts = 1)
{
if (!$syntax && !$other) {
$syntax = CarbonInterface::DIFF_RELATIVE_TO_NOW;
}

return $this->resolveCarbon($other)->diffForHumans($this, $syntax, $short, $parts);
}

/**
* Get the difference in a human readable format in the current locale from current
* instance to now.
*
* @param int $syntax difference modifiers (ago, after, etc) rules
* Possible values:
* - CarbonInterface::DIFF_ABSOLUTE
* - CarbonInterface::DIFF_RELATIVE_AUTO
* - CarbonInterface::DIFF_RELATIVE_TO_NOW
* - CarbonInterface::DIFF_RELATIVE_TO_OTHER
* Default value: CarbonInterface::DIFF_RELATIVE_AUTO
* @param bool $short displays short format of time units
* @param int $parts displays number of parts in the interval
*
* @return string
*/
public function fromNow($syntax = null, $short = false, $parts = 1)
{
return $this->from(null, $syntax, $short, $parts);
}

/**
* Get the difference in a human readable format in the current locale from an other
* instance given to now
*
* @param int $syntax difference modifiers (ago, after, etc) rules
* Possible values:
* - CarbonInterface::DIFF_ABSOLUTE
* - CarbonInterface::DIFF_RELATIVE_AUTO
* - CarbonInterface::DIFF_RELATIVE_TO_NOW
* - CarbonInterface::DIFF_RELATIVE_TO_OTHER
* Default value: CarbonInterface::DIFF_RELATIVE_AUTO
* @param bool $short displays short format of time units
* @param int $parts displays number of parts in the interval
*
* @return string
*/
public function toNow($syntax = null, $short = false, $parts = 1)
{
return $this->to(null, $syntax, $short, $parts);
}
}

0 comments on commit 8140df7

Please sign in to comment.