cmixin/enhanced-period

Carbon mixin to convert `Carbon\CarbonPeriod` to `Spatie\Period\Period` and vice versa

1.2.1 2023-06-12 16:44 UTC

Requires

• php: ^7.2 || ^8.0
• nesbot/carbon: ^2.23.0-beta.1 || ^3.0@dev || ^4.0@dev
• spatie/period: ^1.4.3 || ^2.0.0

Requires (Dev)

• phpunit/phpunit: ^8.5.14 || ^9.3.8

MIT

• KyleKatarn

README

Carbon mixin to convert Carbon\CarbonPeriod to Spatie\Period\Period and vice versa.

Professionally supported nesbot/carbon is now available

Install

composer require cmixin/enhanced-period

Usage

<?php

use Carbon\CarbonPeriod;
use Cmixin\EnhancedPeriod;

CarbonPeriod::mixin(EnhancedPeriod::class); // This line is not needed if you use Laravel default auto-discovery.

// Use toEnhancedPeriod to convert `Carbon\CarbonPeriod` objects to `Spatie\Period\Period` ones
$a = CarbonPeriod::create('2018-01-01', '2018-01-10')->toEnhancedPeriod();
$b = CarbonPeriod::create('2018-01-15', '2018-01-31')->toEnhancedPeriod();

// Use fromEnhancedPeriod to convert `Spatie\Period\Period` objects to `Carbon\CarbonPeriod` ones
echo CarbonPeriod::fromEnhancedPeriod($a->gap($b));

// Or you can directly call gap() or most of the other `Spatie\Period\Period` methods directly on `Carbon\CarbonPeriod`:
$a = CarbonPeriod::create('2018-01-01', '2018-01-10');
$b = CarbonPeriod::create('2018-01-15', '2018-01-31');

// It will use `Spatie\Period\Period::gap` and automatically convert the result to `Carbon\CarbonPeriod`
echo $a->gap($b);

Both output (using the default Carbon\CarbonPeriod cast to string):

Every 1 day from 2018-01-11 to 2018-01-14

See all methods you can call on Spatie\Period\Period objects.

And here are the methods you can call directly on CarbonPeriod instances:

length

length(): int

CarbonPeriod::create('2019-08-20', '2019-09-01')->length();

overlapsWith

overlapsWith($period, ...$arguments): bool

CarbonPeriod::create('2019-08-20', '2019-09-01')->overlapsWith('2019-08-28', '2019-09-03');

You can pass to overlapsWith: Spatie\Period\Period, CarbonPeriod, DatePeriod or arguments to construct a CarbonPeriod.

Note: ->overlapsWith will give different results from ->overlaps because it use internally Spatie\Period\Period and its precision mask (use floor rounding).

touchesWith

touchesWith($period, ...$arguments): bool

CarbonPeriod::create('2019-08-20', '2019-09-01')->touchesWith('2019-09-02', '2019-09-06');

You can pass to overlapsWith: Spatie\Period\Period, CarbonPeriod, DatePeriod or arguments to construct a CarbonPeriod.

Note: ->touchesWith will give different results from ->isConsecutiveWith because it use internally Spatie\Period\Period and its precision mask (use floor rounding).

duration

Warning: this method requires spatie/period >= 2.0

duration(): Spatie\Period\PeriodDuration

CarbonPeriod::create('2019-08-20', '2019-09-01')->duration();

Get a representation of the iteration duration.

overlap

Warning: does not match spatie/period 1 overlap() method because of upcoming renaming, it's for now called overlapSingle in spatie/period.

overlap($period, ...$arguments): ?CarbonPeriod

CarbonPeriod::create('2019-08-20', '2019-09-01')->overlap('2019-08-25', '2019-09-05'); // [2019-08-25, 2019-09-01]

Return overlap period between current and a given other period.

overlapAny

Warning: due to upcoming renaming, it's for now called overlap in spatie/period.

overlapAny($period, ...$arguments): CarbonPeriod[]

$a = CarbonPeriod::create('2018-01-01', '2018-01-31');
$b = CarbonPeriod::create('2018-02-10', '2018-02-20');
$c = CarbonPeriod::create('2018-03-01', '2018-03-31');
$d = CarbonPeriod::create('2018-01-20', '2018-03-10');

foreach ($d->overlapAny($a, $b, $c) as $period) {
  echo $period."\n";
}

Return overlap chunks that are present in at least 2 periods.

A       [========]
B                    [==]
C                            [=====]
CURRENT        [===============]

OVERLAP        [=]   [==]    [=]

overlapAll

overlapAll(...$periods): ?CarbonPeriod

$a = CarbonPeriod::create('2018-01-01', '2018-01-31');
$b = CarbonPeriod::create('2018-01-10', '2018-01-15');
$c = CarbonPeriod::create('2018-01-10', '2018-01-31');

echo $a->overlapAll($b, $c);

Return the merged overlap of all periods.

A              [============]
B                   [==]
C                  [=======]

OVERLAP             [==]

diffAny

Warning: due to upcoming renaming, it's for now called diffSingle in spatie/period.

diffAny($period, ...$arguments): CarbonPeriod[]

$a = CarbonPeriod::create('2018-01-01', '2018-01-15');
$b = CarbonPeriod::create('2018-01-10', '2018-01-30');

foreach ($a->diffAny($b) as $period) {
  echo $period."\n";
}

Returns the difference between the current period and an other given one.

diff

diff(...$periods): CarbonPeriod[]

$a = CarbonPeriod::create('2018-01-01', '2018-01-31');
$b = CarbonPeriod::create('2018-02-10', '2018-02-20');
$c = CarbonPeriod::create('2018-02-11', '2018-03-31');

$current = CarbonPeriod::create('2018-01-20', '2018-03-15');

foreach ($current->diff($a, $b, $c) as $period) {
  echo $period."\n";
}

Returns periods in the current ones that are not covered by periods passed as arguments.

A                   [====]
B                               [========]
C         [=====]
CURRENT      [========================]

DIFF             [=]      [====]

gap

gap($period, ...$arguments): ?CarbonPeriod

$a = CarbonPeriod::create('2018-01-01', '2018-01-10');
$b = CarbonPeriod::create('2018-01-15', '2018-01-31');

echo $a->gap($b);

Returns the gap period between the current one and the one passed as argument.

A       [========]
B                     [===========]

GAP               [==]

fromEnhancedPeriod

fromEnhancedPeriod(Period $period, bool $mutable = false): CarbonPeriod

$period = CarbonPeriod::fromEnhancedPeriod(Period::make('2018-01-01', '2018-01-10'));

Convert a Spatie period into a Carbon period, you can pass true as a second argument to select Carbon as date class rather than CarbonImmutable (by default).

fromNullableEnhancedPeriod

fromNullableEnhancedPeriod(Period|null $period, bool $mutable = false): CarbonPeriod|null

$period = CarbonPeriod::fromNullableEnhancedPeriod($spatiePeriod);

Same as fromEnhancedPeriod but allow null value.

fromPeriodCollection

fromPeriodCollection(PeriodCollection $periods, $mutable = false): CarbonPeriod[]

$periods = CarbonPeriod::fromPeriodCollection(new PeriodCollection(
  Period::make('2018-01-01', '2018-01-10'),
  Period::make('2018-01-15', '2018-01-31')
));

foreach ($periods as $period) {
  echo $period; // $period is a CarbonPeriod instance
}

Convert PeriodCollection object into an array of CarbonPeriod instances.

You can pass true as a second argument to select Carbon as date class rather than CarbonImmutable (by default).

convertDateIntervalToPrecision

convertDateIntervalToPrecision(DateInterval $interval): int|Precision

$precision = CarbonPeriod::convertDateIntervalToPrecision(CarbonInterval::day());
// Precision::DAY() (with PHP >= 8 and spatie/period >= 2)
// Precision::DAY (in older versions)

Convert DateInterval objects (such as CarbonInterval) into a Spatie precision mask if it exists, throws an RuntimeException if it does not match any mask.

convertDateIntervalToPrecision

convertPrecisionMaskToDateInterval(int|Precision $precisionMask): CarbonInterval

$interval = CarbonPeriod::convertPrecisionMaskToDateInterval(Precision::DAY()); // CarbonInterval::day()
// Pass Precision object (such as Precision::DAY()) with PHP >= 8 and spatie/period >= 2
// Pass integer masks (such as Precision::DAY) with older versions

Convert Spatie precision mask into a CarbonInterval.