Period & Quarter

If you have ever worked on reporting metrics within a program or codebase you maintain, you will have likely come across the need to generate periods of time with start and end dates, or manage calendar or fiscal quarters to filter data with.

The Period and Quarter packages for PHP and Laravel do just that. Simple packages with simple usage, the Period package allows users to easily access start and end dates for common periods of time like “past thirty days” or “last month” or “this week”.

The Quarter package extends the functionality of the Period class to manage calendar and fiscal year quarterly dates.

Both packages are open source, free to use, and free to contribute to.

Period.php – Github

Quarter.php – Github

Period.php

Usage

All instances of Period take in a Carbon instance for the startDate and endDate. You can specify a specific start and end date yourself, or use some of the built-in helper functions to get commonly needed periods of time.

You can define a period by passing a start and end date to the static create method:

Copy Code

$customPeriod = Period::create(
    Carbon::now()->subDays(3),
    Carbon::now()
);

You can also use one of the many methods provided for you to generate pre-defined periods of time:

Copy Code

//days
Period::today();
Period::yesterday();
Period::lastDays(int $days); //$days = 2
Period::lastDaysExcludingToday(int $days);

//weeks
Period::thisWeek();
Period::thisWeekExcludingToday();
Period::lastWeek();
Period::lastWeeks(int $weeks);

//months
Period::thisMonth();
Period::thisMonthExcludingToday();
Period::lastMonth();
Period::lastMonths(int $months);

//quarters (3 months)
Period::thisQuarter();
Period::thisQuarterExcludingToday();
Period::lastQuarter();
Period::lastQuarters(int $quarters);

//years
Period::thisYear();
Period::thisYearExcludingToday();
Period::lastYear();
Period::lastYears(int $years);

Quarter.php

Usage

The Quarter class extends the Period class, and has access to all of the parent methods for Period, while also adding some additional helper methods for handling the quarters of a calendar or fiscal year:

Copy Code

//Jan 1, YYYY - Mar 31, YYYY
Quarter::first();

//Apr 1, YYYY - Jun 30, YYYY
Quarter::second();

//Jul 1, YYYY - Sep 30, YYYY
Quarter::third();

//Oct 1, YYYY - Dec 31, YYYY
Quarter::fourth();

You can specify the year you want to access the quarter for, and you can specify if you want a calendar year (default) or a fiscal year by chaining the fiscal() method to the object instantiation:

Copy Code

//July 1, 2020 - September 30, 2020
Quarter::first()
       ->year(2020)
       ->fiscal();

You can also specify that the resulting object instance be of the type Period by chaining the asPeriod() method:

Copy Code

//July 1, 2020 - September 30, 2020
Quarter::first()
       ->year(2020)
       ->fiscal()
       ->asPeriod();

Finally, you can access the next and previous quarters given any instance of a quarter class:

Copy Code

//July 1, 2020 - September 30, 2020
$q1_2020 = Quarter::first()
                  ->year(2020)
                  ->fiscal();

$q2_2020 = $q1_2020->next();
$q4_2019 = $q1_2020->previous();