Support pushing an entire Period instance forward or backwards in time

[adamnicholson]

Introduction

Currently, if you wish to advance a Period instance forward or backwards in time, this must be implemented in userland.

An example would be wanting to advance Period('2016-01-01', '2016-07-07') forward 5 days, to result in Period('2016-06-01', '2016-07-12')

Proposal

This PR adds new advance(DateInterval $by) and recede(DateInterval $by) methods to Period, which perform the operation described above.

For example:

$period = new Period('2016-01-01 15:32:12', '2016-01-15 12:00:01');
$moved = $period->advance(new DateInterval('P1D')); // new Period('2016-01-02 15:32:12', '2016-01-16 12:00:01')

Backward Incompatible Changes

There are no BC breaks.

Targeted release version

The next release.

PR Impact

None

Open issues

None

[nyamsprod]

@adamnicholson I like the idea but you could improve the implementation by:

• using directly the constructor
• using the internal validation method to broaden the usage

For instance your advance method would be better like this

public function advance($interval)
{
    $interval = static::filterDateInterval($interval);

    return new static($this->startDate->add($interval), $this->endDate->add($interval));
}

This way you ensure for instance that someone can do

use League\Period\Period;

$period = Period::createFromDay('today');
$new_period = $period->advance('+1 DAY');

[adamnicholson]

@nyamsprod good point, I've updated the PR.

One thought I had was whether this should even be 2 methods, or 1? If it were 1 it would require the user to pass in an inverted DateInterval instance (or use an inverted string) for the recede.

2 methods is a bit more user friendly I thought, but you would get what seems like unusual on the surface (although totally logical) behaviour if you pass in inverted intervals

Eg.

$period = new Period('2016-01-02 15:32:12', '2016-01-16 12:00:01');
$moved = $period->advance('- 1 day'); // new Period('2016-01-01 15:32:12', '2016-01-15 12:00:01')

$period = new Period('2016-01-02 15:32:12', '2016-01-16 12:00:01');
$moved = $period->recede('- 1 day'); // new Period('2016-01-03 15:32:12', '2016-01-17 12:00:01')

[nyamsprod]

@adamnicholson Good remark. One method also means an easier class to maintain as long as the documentation is clear. So let's make it one method. Let's call it advance and we will just document that in order to get a recede period users will have to use an inverted DateInterval object. and call it a day 👍

[adamnicholson]

Sounds good to me!

[nyamsprod]

@adamnicholson yep just squash all your commits into one for clean history reason and I'll merge your PR for a 3.3.0 release probably next week!

[nyamsprod]

@adamnicholson you should also make a PR on the gh-pages to update the documentation by adding the relevant info

[nyamsprod]

@adamnicholson after a week-end to think about it I think the method should be called move

public Period::move($interval): Period

This way depending on the interval submitted we move forward or backward both datepoints and it will make more sense IMHO.

If you make this change and squash your intermediary commits I'll merge your PR ASAP

[adamnicholson]

Good shout. Done that now.

[nyamsprod]

@adamnicholson version 3.3.0 is release with the move method 🎱