Skip to content

Commit

Permalink
Implement WeekDay, Month and Unit enums
Browse files Browse the repository at this point in the history 
Resolves #2701
  • Loading branch information
@kylekatarnls
kylekatarnls committed Dec 9, 2023
1 parent cc423b8 commit ec6043a
Show file tree
Hide file tree
Showing 17 changed files with 602 additions and 87 deletions.
9 changes: 5 additions & 4 deletions phpdoc.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -291,28 +291,29 @@ function dumpParameter(string $method, ReflectionParameter $parameter): string
$unit = $vars->name;
$unitName = unitName($unit);
$plUnit = pluralize($unit);
$enums = $unitName === 'month' ? 'Month|' : '';
$autoDocLines[] = [
'@method',
'self',
"$plUnit(int \$value)",
"$plUnit({$enums}int \$value)",
"Set current instance $unitName to the given value.",
];
$autoDocLines[] = [
'@method',
'self',
"$unit(int \$value)",
"$unit({$enums}int \$value)",
"Set current instance $unitName to the given value.",
];
$autoDocLines[] = [
'@method',
'self',
'set'.ucfirst($plUnit).'(int $value)',
'set'.ucfirst($plUnit)."({$enums}int \$value)",
"Set current instance $unitName to the given value.",
];
$autoDocLines[] = [
'@method',
'self',
'set'.ucfirst($unit).'(int $value)',
'set'.ucfirst($unit)."({$enums}int \$value)",
"Set current instance $unitName to the given value.",
];

Expand Down
8 changes: 4 additions & 4 deletions src/Carbon/Carbon.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -300,10 +300,10 @@
* @method $this year(int $value) Set current instance year to the given value.
* @method $this setYears(int $value) Set current instance year to the given value.
* @method $this setYear(int $value) Set current instance year to the given value.
* @method $this months(int $value) Set current instance month to the given value.
* @method $this month(int $value) Set current instance month to the given value.
* @method $this setMonths(int $value) Set current instance month to the given value.
* @method $this setMonth(int $value) Set current instance month to the given value.
* @method $this months(Month|int $value) Set current instance month to the given value.
* @method $this month(Month|int $value) Set current instance month to the given value.
* @method $this setMonths(Month|int $value) Set current instance month to the given value.
* @method $this setMonth(Month|int $value) Set current instance month to the given value.
* @method $this days(int $value) Set current instance day to the given value.
* @method $this day(int $value) Set current instance day to the given value.
* @method $this setDays(int $value) Set current instance day to the given value.
Expand Down
8 changes: 4 additions & 4 deletions src/Carbon/CarbonImmutable.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -300,10 +300,10 @@
* @method CarbonImmutable year(int $value) Set current instance year to the given value.
* @method CarbonImmutable setYears(int $value) Set current instance year to the given value.
* @method CarbonImmutable setYear(int $value) Set current instance year to the given value.
* @method CarbonImmutable months(int $value) Set current instance month to the given value.
* @method CarbonImmutable month(int $value) Set current instance month to the given value.
* @method CarbonImmutable setMonths(int $value) Set current instance month to the given value.
* @method CarbonImmutable setMonth(int $value) Set current instance month to the given value.
* @method CarbonImmutable months(Month|int $value) Set current instance month to the given value.
* @method CarbonImmutable month(Month|int $value) Set current instance month to the given value.
* @method CarbonImmutable setMonths(Month|int $value) Set current instance month to the given value.
* @method CarbonImmutable setMonth(Month|int $value) Set current instance month to the given value.
* @method CarbonImmutable days(int $value) Set current instance day to the given value.
* @method CarbonImmutable day(int $value) Set current instance day to the given value.
* @method CarbonImmutable setDays(int $value) Set current instance day to the given value.
Expand Down
36 changes: 18 additions & 18 deletions src/Carbon/CarbonInterface.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -312,10 +312,10 @@
* @method CarbonInterface year(int $value) Set current instance year to the given value.
* @method CarbonInterface setYears(int $value) Set current instance year to the given value.
* @method CarbonInterface setYear(int $value) Set current instance year to the given value.
* @method CarbonInterface months(int $value) Set current instance month to the given value.
* @method CarbonInterface month(int $value) Set current instance month to the given value.
* @method CarbonInterface setMonths(int $value) Set current instance month to the given value.
* @method CarbonInterface setMonth(int $value) Set current instance month to the given value.
* @method CarbonInterface months(Month|int $value) Set current instance month to the given value.
* @method CarbonInterface month(Month|int $value) Set current instance month to the given value.
* @method CarbonInterface setMonths(Month|int $value) Set current instance month to the given value.
* @method CarbonInterface setMonth(Month|int $value) Set current instance month to the given value.
* @method CarbonInterface days(int $value) Set current instance day to the given value.
* @method CarbonInterface day(int $value) Set current instance day to the given value.
* @method CarbonInterface setDays(int $value) Set current instance day to the given value.
Expand Down Expand Up @@ -1773,7 +1773,7 @@ public function diffInSeconds($date = null, bool $absolute = false): float;

/**
* @param string $unit microsecond, millisecond, second, minute,
* hour, day, week, months, quarter, years,
* hour, day, week, month, quarter, year,
* century, millennium
* @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date
* @param bool $absolute Get the absolute of the difference
Expand Down Expand Up @@ -2271,13 +2271,13 @@ public static function getDays();
* Return the number of days since the start of the week (using the current locale or the first parameter
* if explicitly given).
*
* @param int|null $weekStartsAt optional start allow you to specify the day of week to use to start the week,
* if not provided, start of week is inferred from the locale
* (Sunday for en_US, Monday for de_DE, etc.)
* @param WeekDay|int|null $weekStartsAt optional start allow you to specify the day of week to use to start the week,
* if not provided, start of week is inferred from the locale
* (Sunday for en_US, Monday for de_DE, etc.)
*
* @return int
*/
public function getDaysFromStartOfWeek(?int $weekStartsAt = null): int;
public function getDaysFromStartOfWeek(WeekDay|int|null $weekStartsAt = null): int;

/**
* Get the fallback locale.
Expand Down Expand Up @@ -3201,11 +3201,11 @@ public function isoWeekYear($year = null, $dayOfWeek = null, $dayOfYear = null);
/**
* Get/set the ISO weekday from 1 (Monday) to 7 (Sunday).
*
* @param int|null $value new value for weekday if using as setter.
* @param WeekDay|int|null $value new value for weekday if using as setter.
*
* @return static|int
*/
public function isoWeekday($value = null);
public function isoWeekday(WeekDay|int|null $value = null);

/**
* Get the number of weeks of the current week-year using given first day of week and first
Expand Down Expand Up @@ -3947,14 +3947,14 @@ public function setDateTimeFrom($date = null);
* Set the day (keeping the current time) to the start of the week + the number of days passed as the first
* parameter. First day of week is driven by the locale unless explicitly set with the second parameter.
*
* @param int $numberOfDays number of days to add after the start of the current week
* @param int|null $weekStartsAt optional start allow you to specify the day of week to use to start the week,
* if not provided, start of week is inferred from the locale
* (Sunday for en_US, Monday for de_DE, etc.)
* @param int $numberOfDays number of days to add after the start of the current week
* @param WeekDay|int|null $weekStartsAt optional start allow you to specify the day of week to use to start the week,
* if not provided, start of week is inferred from the locale
* (Sunday for en_US, Monday for de_DE, etc.)
*
* @return static
*/
public function setDaysFromStartOfWeek(int $numberOfDays, ?int $weekStartsAt = null);
public function setDaysFromStartOfWeek(int $numberOfDays, WeekDay|int|null $weekStartsAt = null);

/**
* Set the fallback locale.
Expand Down Expand Up @@ -5207,11 +5207,11 @@ public function weekYear($year = null, $dayOfWeek = null, $dayOfYear = null);
/**
* Get/set the weekday from 0 (Sunday) to 6 (Saturday).
*
* @param int|null $value new value for weekday if using as setter.
* @param WeekDay|int|null $value new value for weekday if using as setter.
*
* @return static|int
*/
public function weekday($value = null);
public function weekday(WeekDay|int|null $value = null);

/**
* Get the number of weeks of the current week-year using given first day of week and first
Expand Down
59 changes: 34 additions & 25 deletions src/Carbon/CarbonInterval.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -377,14 +377,14 @@ public static function getCascadeFactors()
protected static function getDefaultCascadeFactors(): array
{
return [
'milliseconds' => [Carbon::MICROSECONDS_PER_MILLISECOND, 'microseconds'],
'seconds' => [Carbon::MILLISECONDS_PER_SECOND, 'milliseconds'],
'minutes' => [Carbon::SECONDS_PER_MINUTE, 'seconds'],
'hours' => [Carbon::MINUTES_PER_HOUR, 'minutes'],
'dayz' => [Carbon::HOURS_PER_DAY, 'hours'],
'weeks' => [Carbon::DAYS_PER_WEEK, 'dayz'],
'months' => [Carbon::WEEKS_PER_MONTH, 'weeks'],
'years' => [Carbon::MONTHS_PER_YEAR, 'months'],
'milliseconds' => [CarbonInterface::MICROSECONDS_PER_MILLISECOND, 'microseconds'],
'seconds' => [CarbonInterface::MILLISECONDS_PER_SECOND, 'milliseconds'],
'minutes' => [CarbonInterface::SECONDS_PER_MINUTE, 'seconds'],
'hours' => [CarbonInterface::MINUTES_PER_HOUR, 'minutes'],
'dayz' => [CarbonInterface::HOURS_PER_DAY, 'hours'],
'weeks' => [CarbonInterface::DAYS_PER_WEEK, 'dayz'],
'months' => [CarbonInterface::WEEKS_PER_MONTH, 'weeks'],
'years' => [CarbonInterface::MONTHS_PER_YEAR, 'months'],
];
}

Expand Down Expand Up @@ -1193,18 +1193,26 @@ public static function instance(DateInterval $interval, array $skip = [], bool $
* Always return a new instance. Parse only strings and only these likely to be intervals (skip dates
* and recurrences). Throw an exception for invalid format, but otherwise return null.
*
* @param mixed|int|DateInterval|string|Closure|null $interval interval or number of the given $unit
* @param string|null $unit if specified, $interval must be an integer
* @param bool $skipCopy set to true to return the passed object
* (without copying it) if it's already of the
* current class
* @param mixed|int|DateInterval|string|Closure|Unit|null $interval interval or number of the given $unit
* @param Unit|string|null $unit if specified, $interval must be an integer
* @param bool $skipCopy set to true to return the passed object
* (without copying it) if it's already of the
* current class
*
* @return static|null
*/
public static function make($interval, $unit = null, bool $skipCopy = false): ?self
{
if ($interval instanceof Unit) {
$interval = $interval->value;
}

if ($unit instanceof Unit) {
$unit = $unit->value;
}

if ($unit) {
$interval = "$interval ".Carbon::pluralUnit($unit);
$interval = "$interval $unit";
}

if ($interval instanceof DateInterval) {
Expand Down Expand Up @@ -2102,9 +2110,9 @@ public function toDateInterval(): DateInterval
*
* @param DateTimeInterface|string|int ...$params Start date, [end date or recurrences] and optional settings.
*
* @return CarbonPeriod
* @return CarbonPeriodImmutable
*/
public function toPeriod(...$params): CarbonPeriod
public function toPeriod(...$params): CarbonPeriodImmutable
{
if ($this->tzName) {
$tz = \is_string($this->tzName) ? new DateTimeZone($this->tzName) : $this->tzName;
Expand All @@ -2114,33 +2122,33 @@ public function toPeriod(...$params): CarbonPeriod
}
}

return CarbonPeriod::create($this, ...$params);
return CarbonPeriodImmutable::create($this, ...$params);
}

/**
* Decompose the current interval into
*
* @param mixed|int|DateInterval|string|Closure|null $interval interval or number of the given $unit
* @param string|null $unit if specified, $interval must be an integer
* @param mixed|int|DateInterval|string|Closure|Unit|null $interval interval or number of the given $unit
* @param Unit|string|null $unit if specified, $interval must be an integer
*
* @return CarbonPeriod
* @return CarbonPeriodImmutable
*/
public function stepBy($interval, ?string $unit = null): CarbonPeriod
public function stepBy($interval, Unit|string|null $unit = null): CarbonPeriodImmutable
{
$start = $this->startDate ?: Carbon::make($this->startDate ?: 'now');
$start = $this->startDate ?: CarbonImmutable::make($this->startDate ?: 'now');
$end = $this->endDate ?: $start->copy()->add($this);

try {
$step = static::make($interval, $unit);
} catch (InvalidFormatException $exception) {
if ($unit || !\is_string($interval) || preg_match('/(\s|\d)/', $interval)) {
if ($unit || (\is_string($interval) ? preg_match('/(\s|\d)/', $interval) : !($interval instanceof Unit))) {
throw $exception;
}

$step = static::make("1 $interval");
$step = static::make(1, $interval);
}

return CarbonPeriod::create($step, $start, $end);
return CarbonPeriodImmutable::create($step, $start, $end);
}

/**
Expand Down Expand Up @@ -3065,6 +3073,7 @@ private static function getFlipCascadeFactors(): array
* @template T of DateInterval
*
* @param DateInterval $interval
*
* @psalm-param class-string<T> $className
*
* @return T
Expand Down
Loading

0 comments on commit ec6043a

Please sign in to comment.