[Proposal] Find the nth day in a month. about carbon

[tassoevan]

+1 That would be nice.

[BradEstey]

Maybe firstInMonth(), lastInMonth(), nthInMonth(), nextInMonth() would be better syntax, since then it would take the current date and return a value within the boundaries of that month. It also allows for expanding into firstInQuarter() and firstInYear() options.

Carbon::now()->firstInMonth(Carbon::THURSDAY);
// Returns the date of the first Thursday in the current month.

Carbon::now()->lastInMonth(Carbon::THURSDAY);
// Returns the date of the last Thursday in the current month. 

Carbon::now()->nthInMonth(Carbon::THURSDAY, 2);
// Returns the date of the 2nd Thursday in the current month. 

Carbon::now()->nextInMonth(Carbon::THURSDAY);
// Returns the next Thursday in the current month.

Carbon::now()->next(Carbon::THURSDAY);
// Returns the next Thursday, regardless of month/quarter/year etc..

Carbon::now()->last(Carbon::THURSDAY);
// Returns the date of the last Thursday before the current date.

Carbon::now()->firstInQuarter(Carbon::THURSDAY);
// Returns the first Thursday in the current quarter.

Carbon::now()->lastInQuarter(Carbon::THURSDAY);
// Returns the last Thursday in the current quarter.

Carbon::now()->nthInYear(Carbon::THURSDAY, 10);
// Returns the 10th Thursday in the current year.

Carbon::now()->lastInYear(Carbon::THURSDAY);
// Returns the last Thursday in the current year.

[tassoevan]

I think that bound nth*() methods in month, year, etc. is not interesting here, since it does not agree with other methods that simply increase a superior date component. So, a code like

Carbon::createFromDate(2013, 6)->nth(Carbon::FRIDAY, 5);

would return a july date, not a invalid value or exception.

[briannesbitt]

I like your 2nd option... firstInMonth() etc. Is it expected to modify the current date or return a new instance? I assume modify the current instance?

Agreed about the nthInMonth(Carbon::FRIDAY, 6) issue ... what would that return? Maybe it could return a boolean false (indicating an invalid request) and no modification would be done ?!?

Just a heads up that there also is this for creating new dates http://www.php.net/manual/en/datetime.formats.relative.php

[briannesbitt]

Wacky, I left a long comment but don't see it anymore. Argh.

Anyway, I pulled in your changes and then proceeded to modify the code a bit. Its in master, see what you think.

[BradEstey]

Sweet! I juggled back and forth on whether last() should be previous() as well. I felt like last(Carbon::MONDAY) was more recognizable as "last Monday" when reading.. and shorter. But previous() is more clear that it is in the past and not some cryptic prophecy of when the last Monday will occur. :)